Members Interface
Interface for a text node.
For more information about our API support guarantees, see here.
This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.
Signature
/** @sealed */
interface Members
Remarks
The string is broken up into substrings which are referred to as 'characters'. Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit. This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings, and avoids the issue where indexing a string and iterating it segment the string differently. This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do): applications will likely want to include higher level segmentation logic which might differ between operations like delete (which often operates on something in between unicode code points and grapheme clusters) and navigation/selection (which typically uses grapheme clusters).
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| characterCount() | Alpha | number | Gets the number of characters currently in the text. |
| characters() | Alpha | Iterable<string> | Gets an iterable over the characters currently in the text. |
| charactersCopy() | Alpha | string[] | Optimized way to get a copy of the characters() in an array. |
| fullString() | Alpha | string | Copy the content of this node into a string. |
| insertAt(index, additionalCharacters) | Alpha | void | Insert a range of characters into the string based on character index. |
| onCharactersChanged(callback) | Alpha | () => void | Subscribe to shallow character-level changes on this text node — inserts and removes only. |
| removeRange(startIndex, endIndex) | Alpha | void | Remove a range from a string based on character index. See removeRange(start, end) for more details on the behavior. |
Method Details
characterCount
Gets the number of characters currently in the text.
For more information about our API support guarantees, see here.
Signature
characterCount(): number;
Remarks
The length of characters(). This is not the length of the string returned by fullString(), as that string may contain characters which are made up of multiple UTF-16 code units.
Returns
Return type: number
characters
Gets an iterable over the characters currently in the text.
For more information about our API support guarantees, see here.
Signature
characters(): Iterable<string>;
Remarks
This iterator matches the behavior of TreeArrayNode with respect to edits during iteration.
Returns
Return type: Iterable<string>
charactersCopy
Optimized way to get a copy of the characters() in an array.
For more information about our API support guarantees, see here.
Signature
charactersCopy(): string[];
Returns
Return type: string[]
fullString
Copy the content of this node into a string.
For more information about our API support guarantees, see here.
Signature
fullString(): string;
Returns
Return type: string
insertAt
Insert a range of characters into the string based on character index.
For more information about our API support guarantees, see here.
Signature
insertAt(index: number, additionalCharacters: string): void;
Remarks
See insertAt(index, value) for more details on the behavior. See fromString(value) for how the additionalCharacters string is broken into characters.
Parameters
| Parameter | Type | Description |
|---|---|---|
| index | number | |
| additionalCharacters | string |
onCharactersChanged
Subscribe to shallow character-level changes on this text node — inserts and removes only.
For more information about our API support guarantees, see here.
Signature
onCharactersChanged(callback: (ops: readonly TextOp[] | undefined) => void): () => void;
Remarks
Only fires on shallow changes — inserts and removes. It does not fire on deep changes such as formatting property updates on existing characters. For formatted text, use onContentChanged(callback) to also receive deep changes.
All counts in the delivered ops are in Unicode code points, not UTF-16 code units. For characters outside the Basic Multilingual Plane (e.g. emoji), one code point corresponds to two UTF-16 code units — convert before using the counts as string indices.
Parameters
| Parameter | Type | Description |
|---|---|---|
| callback | (ops: readonly TextOp[] | undefined) => void | Called after each change with a sequence of TextOps describing what changed, or undefined when a delta could not be computed (e.g. during a schema upgrade). |
Returns
A cleanup function that unsubscribes the callback when called.
Return type: () => void
removeRange
Remove a range from a string based on character index. See removeRange(start, end) for more details on the behavior.
For more information about our API support guarantees, see here.
Signature
removeRange(startIndex: number | undefined, endIndex: number | undefined): void;
Parameters
| Parameter | Type | Description |
|---|---|---|
| startIndex | number | undefined | |
| endIndex | number | undefined |
See Also
fromString(value) for construction.
Tree for schema.