Editor API
50 min
the editor object stores all the state of a slate editor it can be extended by plugins docid\ ylkebq1l858sqlxe9x2yp 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 normalizenode (entry nodeentry) => void onchange () => 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 } instantiation methods docid\ hy2ugai1fnvsaa53xavypstatic methods docid\ hy2ugai1fnvsaa53xavypretrieval methods docid\ hy2ugai1fnvsaa53xavypmanipulation methods docid\ hy2ugai1fnvsaa53xavypcheck methods docid\ hy2ugai1fnvsaa53xavypnormalization methods docid\ hy2ugai1fnvsaa53xavypref methods docid\ hy2ugai1fnvsaa53xavypinstance methods docid\ hy2ugai1fnvsaa53xavypschema specific methods to override docid\ hy2ugai1fnvsaa53xavypelement type methods docid\ hy2ugai1fnvsaa53xavypnormalize method docid\ hy2ugai1fnvsaa53xavypcallback method docid\ hy2ugai1fnvsaa53xavypmark methods docid\ hy2ugai1fnvsaa53xavypgetfragment method docid\ hy2ugai1fnvsaa53xavypdelete methods docid\ hy2ugai1fnvsaa53xavypinsert methods docid\ hy2ugai1fnvsaa53xavypoperation handling method docid\ hy2ugai1fnvsaa53xavyp instantiation methods createeditor() => editor note this method is imported directly from slate and is not part of the editor object creates a new, empty editor object static methods retrieval methods editor above\<t extends ancestor>(editor editor, options?) => nodeentry\<t> | undefined get the matching ancestor above a location in the document options at? location = editor selection where to start at which is editor selection by default match? nodematch = () => true narrow the match mode? 'highest' | 'lowest' = 'lowest' if lowest (default), returns the lowest matching ancestor if highest , returns the highest matching ancestor voids? boolean = false when false ignore void objects editor after(editor editor, at location, options?) => point | undefined 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} editor before(editor editor, at location, options?) => point | undefined 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} editor edges(editor editor, at location) => \[point, point] get the start and end points of a location editor end(editor editor, at location) => point get the end point of a location editor first(editor editor, at location) => nodeentry get the first node at a location editor fragment(editor editor, at location) => descendant\[] get the fragment at a location editor last(editor editor, at location) => nodeentry get the last node at a location editor leaf(editor editor, at location, options?) => nodeentry get the leaf text node at a location options {depth? number, edge? 'start' | 'end'} editor levels\<t extends node>(editor editor, options?) => generator\<nodeentry\<t>, void, undefined> iterate through all of the levels at a location options {at? location, match? nodematch, reverse? boolean, voids? boolean} editor marks(editor editor) => omit\<text, 'text'> | null get the marks that would be added to text at the current selection editor next\<t extends descendant>(editor editor, options?) => nodeentry\<t> | undefined get the matching node in the branch of the document after a location note if you are looking for the next point, and not the next node, you are probably looking for the method editor after options {at? location, match? nodematch, mode? 'all' | 'highest' | 'lowest', voids? boolean} editor node(editor editor, at location, options?) => nodeentry get the node at a location options depth? number, edge? 'start' | 'end' editor nodes\<t extends node>(editor editor, options?) => generator\<nodeentry\<t>, void, undefined> 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 editor parent(editor editor, at location, options?) => nodeentry\<ancestor> get the parent node of a location options {depth? number, edge? 'start' | 'end'} editor path(editor editor, at location, options?) => path get the path of a location options {depth? number, edge? 'start' | 'end'} editor point(editor editor, at location, options?) => point get the start or end point of a location options {edge? 'start' | 'end'} editor positions(editor editor, options?) => generator\<point, void, undefined> 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 you pass in true for the voids option, then iteration will occur options at? location = editor selection the location in which to iterate the positions of unit? 'offset' | 'character' | 'word' | 'line' | 'block' = 'offset' offset moves to the next offset point it will include the point at the end of a text object and then move onto the first point (at the 0th offset) of the next text object this may be counter intuitive because the end of a text and the beginning of the next text might be thought of as the same position character moves to the next character but is not always the next index in the string this is because unicode encodings may require multiple bytes to create one character unlike offset , character will not count the end of a text and the beginning of the next text 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 next word in reverse mode, moves to the position immediately before the previous word 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 when true returns the positions in reverse order in the case of the unit being word , 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 when true include void nodes editor previous\<t extends node>(editor editor, options?) => nodeentry\<t> | undefined get the matching node in the branch of the document before a location note if you are looking for the previous point, and not the previous node, you are probably looking for the method editor before options {at? location, match? nodematch, mode? 'all' | 'highest' | 'lowest', voids? boolean} editor range(editor editor, at location, to? location) => range get a range of a location editor start(editor editor, at location) => point get the start point of a location editor string(editor editor, at location, options?) => string 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 you pass in true for the voids option options {voids? boolean} editor void(editor editor, options?) => nodeentry\<element> | undefined match a void node in the current branch of the editor options {at? location, mode? 'highest' | 'lowest', voids? boolean} manipulation methods editor addmark(editor editor, key string, value any) => void add a custom property to the leaf text nodes 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 editor deletebackward(editor editor, options?) => void delete content in the editor backward from the current selection options {unit? 'character' | 'word' | 'line' | 'block'} editor deleteforward(editor editor, options?) => void delete content in the editor forward from the current selection options {unit? 'character' | 'word' | 'line' | 'block'} editor deletefragment(editor editor) => void delete the content in the current selection editor insertbreak(editor editor) => void insert a block break at the current selection editor insertfragment(editor editor, fragment node\[]) => void inserts a fragment at the current selection if the selection is currently expanded, it will be deleted first to atomically insert nodes (including at the very beginning or end), use transforms insertnodes docid\ ivorsdntr 7lbfullsy editor insertnode(editor editor, node node) => void inserts a node at the current selection if the selection is currently expanded, it will be deleted first to atomically insert a node (including at the very beginning or end), use transforms insertnodes docid\ ivorsdntr 7lbfullsy editor inserttext(editor editor, text string) => void inserts text at the current selection if the selection is currently expanded, it will be deleted first editor removemark(editor editor, key string) => void remove a custom property from all of the leaf text nodes 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 editor unhangrange(editor editor, range range, options?) => range 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 methods editor hasblocks(editor editor, element element) => boolean check if a node has block children editor hasinlines(editor editor, element element) => boolean check if a node has inline and text children editor hastexts(editor editor, element element) => boolean check if a node has text children editor isblock(editor editor, value any) => value is element check if a value is a block element object editor iseditor(value any) => value is editor check if a value is an editor object editor isend(editor editor, point point, at location) => boolean check if a point is the end point of a location editor isedge(editor editor, point point, at location) => boolean check if a point is an edge of a location editor isempty(editor editor, element element) => boolean check if an element is empty, accounting for void nodes editor isinline(editor editor, value any) => value is element check if a value is an inline element object editor isnormalizing(editor editor) => boolean check if the editor is currently normalizing after each operation editor isstart(editor editor, point point, at location) => boolean check if a point is the start point of a location editor isvoid(editor editor, value any) => value is element check if a value is a void element object normalization methods editor normalize(editor editor, options?) => void normalize any dirty objects in the editor options {force? boolean} editor withoutnormalizing(editor editor, fn () => void) => void call a function, deferring normalization until after it completes see normalization implications for other code docid\ hy2ugai1fnvsaa53xavyp ; ref methods editor pathref(editor editor, path path, options?) => pathref 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} editor pathrefs(editor editor) => set\<pathref> get the set of currently tracked path refs of the editor editor pointref(editor editor, point point, options?) => pointref 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} editor pointrefs(editor editor) => set\<pointref> get the set of currently tracked point refs of the editor editor rangeref(editor editor, range range, options?) => rangeref 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} editor rangerefs(editor editor) => set\<rangeref> get the set of currently tracked range refs of the editor instance methods schema specific instance methods to override replace these methods to modify the original behavior of the editor when building plugins docid\ ylkebq1l858sqlxe9x2yp 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 } element type methods use these methods so that slate can identify certain elements as inlines docid\ ko nspe9s4u3zgumayhfo or voids docid\ ko nspe9s4u3zgumayhfo isinline(element element) => boolean check if a value is an inline element object isvoid(element element) => boolean check if a value is a void element object normalize method normalizenode(entry nodeentry) => void normalize docid\ bcrusc6m1f9siq sqbobu a node according to the schema callback method onchange() => void called when there is a change in the editor mark methods addmark(key string, value any) => void add a custom property to the leaf text nodes 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 removemark(key string) => void remove a custom property from the leaf text nodes in the current selection getfragment method getfragment() => descendant returns the fragment at the current selection used when cutting or copying, as an example, to get the fragment at the current selection delete methods 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 selecttion is collapsed, deletebackward will be called deletebackward(options? {unit? 'character' | 'word' | 'line' | 'block'}) => void delete content in the editor backward from the current selection deleteforward(options? {unit? 'character' | 'word' | 'line' | 'block'}) => void delete content in the editor forward from the current selection deletefragment() => void delete the content of the current selection insert methods insertfragment(fragment node\[]) => void insert a fragment at the current selection if the selection is currently expanded, delete it first insertbreak() => void insert a block break at the current selection if the selection is currently expanded, delete it first insertsoftbreak() => void insert a soft break at the current selection if the selection is currently expanded, delete it first insertnode(node node) => void insert a node at the current selection if the selection is currently expanded, delete it first inserttext(text string) => void insert text at the current selection if the selection is currently expanded, delete it first operation handling method apply(operation operation) => void apply an operation in the editor