🔧
API
🧪
Tutorials
Delta Format
The Delta Format was originally described by the Quill rich text editor. We adapted the approach to describe changes on sequence-like data (e.g. Y.Text, Y.Array, Y.XmlFragment).
A Delta is a format to describe changes on a sequence-like data structure like Y.Array, Y.XmlFragment, or Y.Text. But it can also be used to describe the current state of a sequence-like data structure, as you can see in the following example:
1
const ytext = ydoc.getText()
2
3
ytext.toDelta() // => []
4
ytext.insert(0, 'World', { bold: true })
5
ytext.insert(0, 'Hello ')
6
ytext.toDelta() // => [{ insert: 'Hello ' }, { insert: 'World', attributes: { bold: true } }]
Copied!
In many cases, you can even use the delta format to apply changes on a document. In Y.Text the delta format is very handy to express complex operations:
1
ytext.insert(0, 'Hello ')
2
ytext.insert(6, 'World', { bold: true })
3
// is equivalent to
4
ytext.applyDelta([{ insert: 'Hello ' }, { insert: 'World', attributes: { bold: true } }])
Copied!
Delta Description
Delete
1
delta = [{
2
delete: 3
3
}]
Copied!
Expresses the intention to delete the first 3 characters.
Retain
1
delta = [{
2
retain: 1
3
}, {
4
delete: 3
5
}]
Copied!
Expresses the intention to retain one item, and then delete three. E.g.
1
ytext.insert(0, '12345')
2
ytext.applyDelta(delta)
3
ytext.toDelta() // => { insert: '15' }
Copied!
Insert (on Y.Text)
The
insert delta is always a string in Y.Text. Furthermore, Y.Text also allows assigning formatting attributes to the inserted text.1
delta = [{
2
retain: 1
3
}, {
4
insert: 'abc', attributes: { bold: true }
5
}, {
6
retain: 1
7
}, {
8
insert: 'xyz'
9
}]
Copied!
Expresses the intention to insert
"abc" at index-position 1 and make the insertion bold. Then we skip another character and insert "xyz" without formatting attributes. E.g.1
ytext.insert(0, '123')
2
ytext.applyDelta(delta)
3
ytext.toDelta() // => [{ insert: '1' },
4
// { insert: 'abc', attributes: { bold: true } },
5
// { insert: '2xyz3' }]
Copied!
Retain (on Y.Text)
In Y.Text the
retain delta may also contain formatting attributes that are applied on the retained text.1
delta = [{
2
retain: 5, attributes: { italic: true }
3
}]
Copied!
Expresses the intention to format the first five characters italic.
Insert (on Y.Array & Y.XmlFragment)
The
insert delta is always an Array of inserted content in Y.Array & Y.XmlFragment.1
yarray.observe(event => { console.log(event.changes.delta) })
2
3
yarray.insert(0, [1, 2, 3]) // => [{ insert: [1, 2, 3] }]
4
yarray.insert(2, ["abc"]) // => [{ retain: 2 }, { insert: ["abc"] }]
5
yarray.delete(0, 1) // => [{ delete: 1 }]
Copied!
The delta format is very powerful to express changes that are performed in a Transaction. As explained in the shared types section, events are fired after transactions. With the delta format we can express multiple changes in a single event. E.g.
1
yarray.observe(event => { console.log(event.changes.delta) })
2
3
ydoc.transact(() => {
4
// perform all changes in a single transaction
5
yarray.insert(0, [1, 2, 3]) // => [{ insert: [1, 2, 3] }]
6
yarray.insert(2, ["abc"]) // => [{ retain: 2 }, { insert: ["abc"] }]
7
yarray.delete(0, 1) // => [{ delete: 1 }]
8
}) // => [{ insert: [2, "abc", 3] }]
9
10
ydoc.transact(() => {
11
yarray.insert(0, 'x')
12
yarray.insert(2, 'y')
13
}) // => [{ insert: ['x'] }, { retain: 1 }, { insert: ['y'] }]
Copied!
Last modified 11mo ago
Copy link
Edit on GitHub
Contents
Delta Description