yonote/yjs
23
0
Fork 0
Code Pull Requests 1 Releases Activity

complete documentation about relative positions

Browse Source
This commit is contained in:
Kevin Jahns 2022-04-07 22:11:10 +02:00
parent 5f56baa23e
commit 4aacb487d2
1 changed files with 43 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -791,6 +791,21 @@ Convert V2 update format to the V1 update format.
### Relative Positions ### Relative Positions
When working with collaborative documents, we often need to work with positions.
Positions may represent cursor locations, selection ranges, or even assign a
comment to a range of text. Normal index-positions (expressed as integers) are
not convenient to use because the index-range is invalidated as soon as a remote
change manipulates the document. Relative positions give you a powerful API to
express positions.
A relative position is fixated to an element in the shared document and is not
affected by remote changes. I.e. given the document `"a|c"`, the relative
position is attached to `c`. When a remote user modifies the document by
inserting a character before the cursor, the cursor will stay attached to the
character `c`. `insert(1, 'x')("a|c") = "ax|c"`. When the relative position is
set to the end of the document, it will stay attached to the end of the
document.
#### Example: Transform to RelativePosition and back #### Example: Transform to RelativePosition and back
```js ```js
@ -825,14 +840,35 @@ pos.index === 2 // => true
``` ```
<dl> <dl>
<b><code>Y.createRelativePositionFromTypeIndex(Uint8Array|Y.Type, number)</code></b> <b><code>
<dd></dd> Y.createRelativePositionFromTypeIndex(type:Uint8Array|Y.Type, index: number
<b><code>Y.createAbsolutePositionFromRelativePosition(RelativePosition, Y.Doc)</code></b> [, assoc=0])
<dd></dd> </code></b>
<b><code>Y.encodeRelativePosition(RelativePosition):Uint8Array</code></b> <dd>
<dd></dd> Create a relative position fixated to the i-th element in any sequence-like
shared type (if <code>assoc >= 0</code>). By default, the position associates
with the character that comes after the specified index position. If
<code>assoc < 0</code>, then the relative position associates with the character
before the specified index position.
</dd>
<b><code>
Y.createAbsolutePositionFromRelativePosition(RelativePosition, Y.Doc):
{ type: Y.AbstractType, index: number, assoc: number } | null
</code></b>
<dd>
Create an absolute position from a relative position. If the relative position
cannot be referenced, or the type is deleted, then the result is null.
</dd>
<b><code>
Y.encodeRelativePosition(RelativePosition):Uint8Array
</code></b>
<dd>
Encode a relative position to an Uint8Array. Binary data is the preferred
encoding format for document updates. If you prefer JSON encoding, you can
simply JSON.stringify / JSON.parse the relative position instead.
</dd>
<b><code>Y.decodeRelativePosition(Uint8Array):RelativePosition</code></b> <b><code>Y.decodeRelativePosition(Uint8Array):RelativePosition</code></b>
<dd></dd> <dd>Decode a binary-encoded relative position to a RelativePositon object.</dd>
</dl> </dl>
### Y.UndoManager ### Y.UndoManager