Comment on page
Editor
The
Editor
object stores all the state of a Slate editor. It can be extended by plugins to add helpers and implement new behaviors. It's a type of Node
and its path is []
.interface Editor {
children: Node[]
selection: Range | null
operations: Operation[]
marks: Omit<Text, 'text'> | null
// Schema-specific node behaviors.
isInline: (element: Element) => boolean
isVoid: (element: Element) => boolean
markableVoid: (element: Element) => boolean
normalizeNode: (entry: NodeEntry) => void
onChange: (options?: { operation?: Operation }) => void
// Overrideable core actions.
addMark: (key: string, value: any) => void
apply: (operation: Operation) => void
deleteBackward: (unit: 'character' | 'word' | 'line' | 'block') => void
deleteForward: (unit: 'character' | 'word' | 'line' | 'block') => void
deleteFragment: () => void
insertBreak: () => void
insertFragment: (fragment: Node[]) => void
insertNode: (node: Node) => void
insertText: (text: string) => void
removeMark: (key: string) => void
}
Note: This method is imported directly from Slate and is not part of the Editor object.
Creates a new, empty
Editor
object.Get the matching ancestor above a location in the document.
Options:
at?: Location = editor.selection
: Where to start at which iseditor.selection
by default.match?: NodeMatch = () => true
: Narrow the matchmode?: 'highest' | 'lowest' = 'lowest'
: Iflowest
(default), returns the lowest matching ancestor. Ifhighest
, returns the highest matching ancestor.voids?: boolean = false
: Whenfalse
ignore void objects.
Get the point after a location.
If there is no point after the location (e.g. we are at the bottom of the document) returns
undefined
.Options:
{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}
Get the point before a location.
If there is no point before the location (e.g. we are at the top of the document) returns
undefined
.Options:
{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}
Get the start and end points of a location.
Get the end point of a location.
Get the first node at a location.
Get the fragment at a location.
Get the last node at a location.
Get the leaf text node at a location.
Options:
{depth?: number, edge?: 'start' | 'end'}
Iterate through all of the levels at a location.
Options:
{at?: Location, match?: NodeMatch, reverse?: boolean, voids?: boolean}
Get the marks that would be added to text at the current selection.
Get the matching node in the branch of the document after a location.
Note: To find the next Point, and not the next Node, use the
Editor.after
methodOptions:
{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}
Get the node at a location.
Options:
depth?: number, edge?: 'start' | 'end'
At any given
Location
or Span
in the editor provided by at
(default is the current selection), the method returns a Generator of NodeEntry
objects that represent the nodes that include at
. At the top of the hierarchy is the Editor
object itself.Options:
{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean}
options.match
: Provide a value to the match?
option to limit the NodeEntry
objects that are returned.options.mode
:'all'
(default): Return all matching nodes'highest'
: in a hierarchy of nodes, only return the highest level matching nodes'lowest'
: in a hierarchy of nodes, only return the lowest level matching nodes
Get the parent node of a location.
Options:
{depth?: number, edge?: 'start' | 'end'}
Get the path of a location.
Options:
{depth?: number, edge?: 'start' | 'end'}
Get the start or end point of a location.
Options:
{edge?: 'start' | 'end'}
Iterate through all of the positions in the document where a
Point
can be placed. The first Point
returns is always the starting point followed by the next Point
as determined by the unit
option.Read
options.unit
to see how this method iterates through positions.Note: By default void nodes are treated as a single point and iteration will not happen inside their content unless the voids option is set, then iteration will occur.
Options:
at?: Location = editor.selection
: TheLocation
in which to iterate the positions of.unit?: 'offset' | 'character' | 'word' | 'line' | 'block' = 'offset'
:offset
: Moves to the next offsetPoint
. It will include thePoint
at the end of aText
object and then move onto the firstPoint
(at the 0th offset) of the nextText
object. This may be counter-intuitive because the end of aText
and the beginning of the nextText
might be thought of as the same position.character
: Moves to the nextcharacter
but is not always the nextindex
in the string. This is because Unicode encodings may require multiple bytes to create one character. Unlikeoffset
,character
will not count the end of aText
and the beginning of the nextText
as separate positions to return. Warning: The character offsets for Unicode characters does not appear to be reliable in some cases like a Smiley Emoji will be identified as 2 characters.word
: Moves to the position immediately after the nextword
. Inreverse
mode, moves to the position immediately before the previousword
.line
|block
: Starts at the beginning position and then the position at the end of the block. Then starts at the beginning of the next block and then the end of the next block.
reverse?: boolean = false
: Whentrue
returns the positions in reverse order. In the case of theunit
beingword
, the actual returned positions are different (i.e. we will get the start of a word in reverse instead of the end).voids?: boolean = false
: Whentrue
include void Nodes.
Get the matching node in the branch of the document before a location.
Note: To find the previous Point, and not the previous Node, use the
Editor.before
methodOptions:
{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}
Get a range of a location.
Get the start point of a location.
Get the text string content of a location.
Note: by default the text of void nodes is considered to be an empty string, regardless of content, unless the voids option is set.
Options: :
{voids?: boolean}
Match a void node in the current branch of the editor.
Options:
{at?: Location, mode?: 'highest' | 'lowest', voids?: boolean}
Add a custom property to the leaf text nodes and any nodes that
editor.markableVoid()
allows in the current selection.If the selection is currently collapsed, the marks will be added to the
editor.marks
property instead, and applied when text is inserted next.Delete content in the editor backward from the current selection.
Options:
{unit?: 'character' | 'word' | 'line' | 'block'}
Delete content in the editor forward from the current selection.
Options:
{unit?: 'character' | 'word' | 'line' | 'block'}
Delete the content in the current selection.
Insert a block break at the current selection.
Inserts a fragment at the specified location or (if not defined) the current selection or (if not defined) the end of the document.
Options:
{at?: Location, hanging?: boolean, voids?: boolean}
Atomically insert
node
at the specified location or (if not defined) the current selection or (if not defined) the end of the document.Options supported:
NodeOptions & {hanging?: boolean, select?: boolean}
.Insert a string of text at the specified location or (if not defined) the current selection or (if not defined) the end of the document.
Options:
{at?: Location, voids?: boolean}
Remove a custom property from all of the leaf text nodes within non-void nodes or void nodes that
editor.markableVoid()
allows in the current selection.If the selection is currently collapsed, the removal will be stored on
editor.marks
and applied to the text inserted next.Convert a range into a non-hanging one.
A "hanging" range is one created by the browser's "triple-click" selection behavior. When triple-clicking a block, the browser selects from the start of that block to the start of the next block. The range thus "hangs over" into the next block. If
unhangRange
is given such a range, it moves the end backwards until it's in a non-empty text node that precedes the hanging block.Note that
unhangRange
is designed for the specific purpose of fixing triple-clicked blocks, and therefore currently has a number of caveats:- It does not modify the start of the range; only the end. For example, it does not "unhang" a selection that starts at the end of a previous block.
- It only does anything if the start block is fully selected. For example, it does not handle ranges created by double-clicking the end of a paragraph (which browsers treat by selecting from the end of that paragraph to the start of the next).
Options:
voids?: boolean = false
: Allow placing the end of the selection in a void node.
Check if a node has block children.
Check if a node has inline and text children.
Check if a node has text children.
Check if a value is a block
Element
object.Check if a value is an
Editor
object.Check if a point is the end point of a location.
Check if a point is an edge of a location.
Check if an element is empty, accounting for void nodes.
Check if a value is an inline
Element
object.Check if the editor is currently normalizing after each operation.
Check if a point is the start point of a location.
Check if a value is a void
Element
object.Normalize any dirty objects in the editor.
Options:
{force?: boolean; operation?: Operation}
Call a function, deferring normalization until after it completes. See Normalization - Implications for Other Code;
Create a mutable ref for a
Path
object, which will stay in sync as new operations are applied to the editor.Options:
{affinity?: 'backward' | 'forward' | null}
Get the set of currently tracked path refs of the editor.
Create a mutable ref for a
Point
object, which will stay in sync as new operations are applied to the editor.Options:
{affinity?: 'backward' | 'forward' | null}
Get the set of currently tracked point refs of the editor.
Create a mutable ref for a
Range
object, which will stay in sync as new operations are applied to the editor.Options:
{affinity?: 'backward' | 'forward' | 'outward' | 'inward' | null}
Get the set of currently tracked range refs of the editor.
Replace these methods to modify the original behavior of the editor when building Plugins. When modifying behavior, call the original method when appropriate. For example, a plugin that marks image nodes as "void":
const withImages = editor => {
const { isVoid } = editor
editor.isVoid = element => {
return element.type === 'image' ? true : isVoid(element)
}
return editor
}
Check if a value is an inline
Element
object.Check if a value is a void
Element
object.Override this method to prevent normalizing the editor.
Options:
{ dirtyPaths: Path[]; initialDirtyPathsLength: number; iteration: number; operation?: Operation }
Called when there is a change in the editor.
Tells which void nodes accept Marks. Slate's default implementation returns
false
, but if some void elements support formatting, override this function to include them.Add a custom property to the leaf text nodes within non-void nodes or void nodes that
editor.markableVoid()
allows in the current selection. If the selection is currently collapsed, the marks will be added to the editor.marks
property instead, and applied when text is inserted next.Remove a custom property from the leaf text nodes within non-void nodes or void nodes that
editor.markableVoid()
allows in the current selection.Returns the fragment at the current selection. Used when cutting or copying, as an example, to get the fragment at the current selection.
When a user presses backspace or delete, it invokes the method based on the selection. For example, if the selection is expanded over some text and the user presses the backspace key,
deleteFragment
will be called, but if the selection is collapsed, deleteBackward
will be called.Delete content in the editor backward from the current selection.
Delete content in the editor forward from the current selection.
Delete the content of the current selection.
Insert a fragment at the current selection. If the selection is currently expanded, delete it first.
Insert a block break at the current selection. If the selection is currently expanded, delete it first.
Insert a soft break at the current selection. If the selection is currently expanded, delete it first.
Insert a node at the current selection. If the selection is currently expanded, delete it first.
Insert text at the current selection. If the selection is currently expanded, delete it first.
Apply an operation in the editor.
Last modified 6mo ago