🔧
API
🧪
Tutorials
Y.XmlElement
A shared type that represents an XML node
1
import * as Y from 'yjs'
2
3
const ydoc = new Y.Doc()
4
5
// You can define a Y.XmlElement as a top-level type or a nested type
6
7
// Method 1: Define a top-level type
8
// Note that the nodeName is always "undefined"
9
// when defining an XmlElement as a top-level type.
10
const yxmlElement = ydoc.get('prop-name', Y.XmlElement)
11
// Method 2: Define Y.XmlFragment that can be included into the Yjs document
12
const yxmlNested = new Y.XmlElement('node-name')
13
14
// Common methods
15
const yxmlText = new Y.XmlText()
16
yxmlFragment.insert(0, [yxmlText])
17
yxmlFragment.firstChild === yxmlText
18
yxmlFragment.insertAfter(yxmlText, [new Y.XmlElement('node-name')])
19
yxmlFragment.get(0) === yxmlText // => true
20
21
//show result in dev console
22
console.log(yxmlFragment.toDOM())
Copied!
API
const yxmlElement = Y.XmlElement(nodeName: string)yxmlElement.nodeName: string
The name of this Y.XmlElement as a String.yxmlElement.prevSibling: Y.XmlElement | Y.XmlText | null
The previous sibling of this type. Is null if this is the first child of its parent.yxmlElement.nextSibling: Y.XmlElement | Y.XmlText | null
The next sibling of this type. Is null if this is the last child of its parent.yxmlElement.toString(): string
Returns the XML-String representation of this element. E.g. "<div height="30px"></div>"yxmlElement.setAttribute(name: string, value: string | Y.AbstractType)
Set an XML attribute. Technically, the value can only be a string. But we also allow shared types. In this case, the XML type can't be properly converted to a string.yxmlElement.removeAttribute(name: string)
Remove an XML attribute.yxmlElement.getAttribute(name: string): string | Y.AbstractType
Retrieve an XML attribute.yxmlElement.getAttributes(): Object<string, string | Y.AbstractType>
Retrieve all XML attributes.Observing changes: Y.XmlEvent
The
yxmlElement.observe callback fires Y.XmlEvent events that you can use to calculate the changes that happened during a transaction. We use an adaption of the Quill delta format to calculate insertions & deletions of child-elements. Changes on the xml-attributes are expressed using the same API from Y.Map.1
yxmlFragment.observe(yxmlElent => {
2
yxmlEvent.target === yarray // => true
3
4
// Observe when child-elements are added or deleted.
5
// Log the Xml-Delta Format to calculate the difference to the last observe-event
6
console.log(yxmlEvent.changes.delta)
7
8
// Observe attribute changes.
9
// Option 1: A set of keys that changed
10
yxmlEvent.keysChanged // => Set<strings>
11
// Option 2: Compute the differences
12
yxmlEvent.changes.keys // => Map<string, { action: 'add'|'update'|'delete', oldValue: any}>
13
14
// The change format is equivalent to the Y.MapEvent change format.
15
yxmlEvent.changes.keys.forEach((change, key) => {
16
if (change.action === 'add') {
17
console.log(`Attribute "${key}" was added. Initial value: "${ymap.get(key)}".`)
18
} else if (change.action === 'update') {
19
console.log(`Attribute "${key}" was updated. New value: "${ymap.get(key)}". Previous value: "${change.oldValue}".`)
20
} else if (change.action === 'delete') {
21
console.log(`Attribute "${key}" was deleted. New value: undefined. Previous value: "${change.oldValue}".`)
22
}
23
})
24
})
25
26
yxmlElement.insert(0, [new Y.XmlText()]) // => [{ insert: [yxmlText] }]
27
yxmlElement.delete(0, 1) // [{ delete: 1 }]
28
29
yxmlElement.setAttribute('key', 'value') // Attribute "key" was added. Initial value: "undefined".
30
yxmlElement.setAttribute('key', 'new value') // Attribute "key" was updated. New value: "new value". Previous value: "value"
31
yxmlElement.deleteAttribute('key') // Attribute "key" was deleted. New value: undefined. Previous value: "new value"
Copied!
Y.XmlEvent API
[todo]
describe childListChanged and attributesChanged
See Y.Event API. The API is inherited from Y.Event.I'm still in the process of moving the documentation to this place. For now, you can find the API docs in the README:
GitHub - yjs/yjs: Shared data types for building collaborative software
GitHub
API DOCS
Last modified 4mo ago
Copy link
Edit on GitHub