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<FormatSchema extends ImplicitAllowedTypes, ExtraAtomsSchema extends readonly LazyItem<TreeNodeSchema<string, NodeKind, TextAtom & TreeNode>>[]> extends PlainText.Members
Extends: PlainText.Members
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| FormatSchema | ImplicitAllowedTypes | |
| ExtraAtomsSchema | readonly LazyItem<TreeNodeSchema<string, NodeKind, TextAtom & TreeNode>>[] |
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 |
|---|---|---|---|
| charactersWithFormatting() | Alpha | readonly FormattedAtom<TreeNodeFromImplicitAllowedTypes<FormatSchema>, TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>[] | Gets an array type view of the characters currently in the text. |
| formatRange(startIndex, endIndex, format) | Alpha | void | Apply formatting to a range of characters based on character index. |
| getString(startIndex, endIndex) | Alpha | string | Returns a substring of the text from startIndex to endIndex |
| getUniformRun(startIndex, endIndex) | Alpha | number | Returns the length of the run of characters starting at startIndex which have the same formatting and atom type, up to endIndex. |
| insertAt(index, additionalCharacters, format) | Alpha | void | insertAt(index, additionalCharacters) with optional formatting to apply to all additional characters, and allowing an array of atoms instead of a string. |
| insertWithFormattingAt(index, additionalCharacters) | Alpha | void | Insert a range of characters into the string based on character index. |
| onContentChanged(callback) | Alpha | () => void | Subscribe to all content changes on this text node, including both shallow changes (inserts/removes) and deep changes (formatting updates on existing characters). |
| reformat(startIndex, endIndex, format) | Alpha | void | Replace formatting of a range of characters based on character index. |
Method Details
charactersWithFormatting
Gets an array type view of the characters currently in the text.
For more information about our API support guarantees, see here.
Signature
charactersWithFormatting(): readonly FormattedAtom<TreeNodeFromImplicitAllowedTypes<FormatSchema>, TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>[];
Remarks
This iterator matches the behavior of TreeArrayNode with respect to edits during iteration.
For more efficient access, use getUniformRun(startIndex, endIndex) and getString(startIndex, endIndex) to access ranges of characters to avoid having to inspect the formatting on every atom.
Returns
Return type: readonly FormattedAtom<TreeNodeFromImplicitAllowedTypes<FormatSchema>, TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>[]
formatRange
Apply formatting to a range of characters based on character index.
For more information about our API support guarantees, see here.
Signature
formatRange(startIndex: number | undefined, endIndex: number | undefined, format: Partial<TreeNodeFromImplicitAllowedTypes<FormatSchema>>): void;
Remarks
The start and end behave the same as in removeRange(start, end). This edits existing formatting subtrees on each atom, and only works when those atoms are object nodes.
This is typically used to set some formatting property, like bold on a range of text without impacting other formatting properties.
Parameters
| Parameter | Type | Description |
|---|---|---|
| startIndex | number | undefined | The starting index (inclusive) of the range to format. |
| endIndex | number | undefined | The ending index (exclusive) of the range to format. |
| format | Partial<TreeNodeFromImplicitAllowedTypes<FormatSchema>> | The formatting to apply to the specified range. For each atom, every property of format will be cloned and assigned to the atom's format's corresponding subtree, overwriting any existing values for those properties. All enumerable own properties of format will be applied, including those with undefined values. |
getString
Returns a substring of the text from startIndex to endIndex
For more information about our API support guarantees, see here.
Signature
getString(startIndex: number, endIndex?: number): string;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| startIndex | number | starting index (inclusive) | |
| endIndex | optional | number | Optional ending index (exclusive). Defaults to the end of the text. |
Returns
Return type: string
getUniformRun
Returns the length of the run of characters starting at startIndex which have the same formatting and atom type, up to endIndex.
For more information about our API support guarantees, see here.
Signature
getUniformRun(startIndex: number, endIndex?: number): number;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| startIndex | number | The starting index of the run. | |
| endIndex | optional | number | The ending index (exclusive) of the run. Defaults to the end of the text. |
Returns
Return type: number
insertAt
insertAt(index, additionalCharacters) with optional formatting to apply to all additional characters, and allowing an array of atoms instead of a string.
For more information about our API support guarantees, see here.
Signature
/** @override */
insertAt(index: number, additionalCharacters: string | Iterable<TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>, format?: InsertableTreeFieldFromImplicitField<FormatSchema>): void;
Remarks
Use insertWithFormattingAt(index, additionalCharacters) if you need to specify formatting for atom independently.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| index | number | ||
| additionalCharacters | string | Iterable<TreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>> | ||
| format | optional | InsertableTreeFieldFromImplicitField<FormatSchema> | Optional formatting to apply to all additional characters. If not specified, the default formatting (from createSchema(inputSchemaFactory, formatSchema, extraAtoms, defaultFormatInsertable)) will be used. |
insertWithFormattingAt
Insert a range of characters into the string based on character index.
For more information about our API support guarantees, see here.
Signature
insertWithFormattingAt(index: number, additionalCharacters: Iterable<FormattedAtomInsertable<InsertableTreeNodeFromImplicitAllowedTypes<FormatSchema>, InsertableTreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>>): void;
Remarks
See insertAt(index, value) for more details on the behavior. See fromString(value, format) for how the additionalCharacters string is broken into characters.
Parameters
| Parameter | Type | Description |
|---|---|---|
| index | number | |
| additionalCharacters | Iterable<FormattedAtomInsertable<InsertableTreeNodeFromImplicitAllowedTypes<FormatSchema>, InsertableTreeNodeFromImplicitAllowedTypes<TextAtomSchemas<ExtraAtomsSchema>>>> |
onContentChanged
Subscribe to all content changes on this text node, including both shallow changes (inserts/removes) and deep changes (formatting updates on existing characters).
For more information about our API support guarantees, see here.
Signature
onContentChanged(callback: (ops: readonly PlainText.TextOp[] | undefined) => void): () => void;
Remarks
Unlike onCharactersChanged(callback) which only fires on shallow changes (inserts and removes), this method also fires on deep changes — formatting property updates on existing characters. The formattingChanged flag on retain ops indicates which character ranges had formatting updates.
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 PlainText.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
reformat
Replace formatting of a range of characters based on character index.
For more information about our API support guarantees, see here.
Signature
reformat(startIndex?: number | undefined, endIndex?: number | undefined, format?: InsertableTreeFieldFromImplicitField<FormatSchema>): void;
Remarks
The start and end behave the same as in removeRange(start, end).
This is typically used to normalize formatting, like resetting the formatting of a range to default settings.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| startIndex | optional | number | undefined | The starting index (inclusive) of the range to format. |
| endIndex | optional | number | undefined | The ending index (exclusive) of the range to format. |
| format | optional | InsertableTreeFieldFromImplicitField<FormatSchema> | The formatting to replace the formatting of the indicated range with. For each atom, format will be cloned and assigned to the atom's format, overwriting any existing formatting. If not specified the defaultFormat from createSchema(inputSchemaFactory, formatSchema, extraAtoms, defaultFormatInsertable) will be used. |
See Also
fromString(value, format) for construction.
createSchema(inputSchemaFactory, formatSchema, extraAtoms, defaultFormatInsertable) for creating schemas whose nodes implement this.