8dd919dc34
#### Is this adding or improving a _feature_ or fixing a _bug_?
Improvement / debt.
#### What's the new behavior?
This pull request removes the `Change` object as we know it, and folds all of its behaviors into the new `Editor` controller instead, simplifying a lot of the confusion around what is a "change vs. editor" and when to use which. It makes the standard API a **lot** nicer to use I think.
---
###### NEW
**The `editor.command` and `editor.query` methods can take functions.** Previously they only accepted a `type` string and would look up the command or query by type. Now, they also accept a custom function. This is helpful for plugin authors, who want to accept a "command option", since it gives users more flexibility to write one-off commands or queries. For example a plugin could be passed either:
```js
Hotkey({
hotkey: 'cmd+b',
command: 'addBoldMark',
})
```
Or a custom command function:
```js
Hotkey({
hotkey: 'cmd+b',
command: editor => editor.addBoldMark().moveToEnd()
})
```
###### BREAKING
**The `Change` object has been removed.** The `Change` object as we know it previously has been removed, and all of its behaviors have been folded into the `Editor` controller. This includes the top-level commands and queries methods, as well as methods like `applyOperation` and `normalize`. _All places that used to receive `change` now receive `editor`, which is API equivalent._
**Changes are now flushed to `onChange` asynchronously.** Previously this was done synchronously, which resulted in some strange race conditions in React environments. Now they will always be flushed asynchronously, just like `setState`.
**The `render*` and `decorate*` middleware signatures have changed!** Previously the `render*` and `decorate*` middleware was passed `(props, next)`. However now, for consistency with the other middleware they are all passed `(props, editor, next)`. This way, all middleware always receive `editor` and `next` as their final two arguments.
**The `normalize*` and `validate*` middleware signatures have changed!** Previously the `normalize*` and `validate*` middleware was passed `(node, next)`. However now, for consistency with the other middleware they are all passed `(node, editor, next)`. This way, all middleware always receive `editor` and `next` as their final two arguments.
**The `editor.event` method has been removed.** Previously this is what you'd use when writing tests to simulate events being fired—which were slightly different to other running other middleware. With the simplification to the editor and to the newly-consistent middleware signatures, you can now use `editor.run` directly to simulate events:
```js
editor.run('onKeyDown', { key: 'Tab', ... })
```
###### DEPRECATED
**The `editor.change` method is deprecated.** With the removal of the `Change` object, there's no need anymore to create the small closures with `editor.change()`. Instead you can directly invoke commands on the editor in series, and all of the changes will be emitted asynchronously on the next tick.
```js
editor
.insertText('word')
.moveFocusForward(10)
.addMark('bold')
```
**The `applyOperations` method is deprecated.** Instead you can loop a set of operations and apply each one using `applyOperation`. This is to reduce the number of methods exposed on the `Editor` to keep it simpler.
**The `change.call` method is deprecated.** Previously this was used to call a one-off function as a change method. Now this behavior is equivalent to calling `editor.command(fn)` instead.
---
Fixes: https://github.com/ianstormtaylor/slate/issues/2334
Fixes: https://github.com/ianstormtaylor/slate/issues/2282
6.0 KiB
Plugins
Plugins can be attached to an editor to alter its behavior in different ways. Each editor has a "stack" of plugins, which has a specific order, which it runs through when certain hooks are triggered.
Plugins are plain JavaScript objects, containing a set of middleware functions that run for each hook they choose to implement.
Hooks
In addition to the core plugin hooks, when using slate-react there are additional browser-specific event handling hooks, and React-specific rendering hooks available to plugins.
{
decorateNode: Function,
onBeforeInput: Function,
onBlur: Function,
onCopy: Function,
onCut: Function,
onDrop: Function,
onFocus: Function,
onKeyDown: Function,
onKeyUp: Function,
onPaste: Function,
onSelect: Function,
renderEditor: Function,
renderMark: Function,
renderNode: Function,
renderPlaceholder: Function,
shouldNodeComponentUpdate: Function,
}
The event hooks have a signature of (event, editor, next)—the event is a React object that you are used to from React's event handlers.
The rendering hooks are just like render props common to other React API's, and receive (props, editor, next). For more information, see the Rendering reference.
decorateNode
Function decorateNode(node: Node, editor: Editor, next: Function) => Array<Decoration>|Void
The decorateNode hook takes a node and returns an array of decorations with marks to be applied to the node when it is rendered.
onBeforeInput
Function onBeforeInput(event: Event, editor: Editor, next: Function) => Boolean
This handler is called right before a string of text is inserted into the contenteditable element.
Make sure to event.preventDefault() if you do not want the default insertion behavior to occur!
onBlur
Function onBlur(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when the editor's contenteditable element is blurred.
onFocus
Function onFocus(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when the editor's contenteditable element is focused.
onCopy
Function onCopy(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when there is a copy event in the editor's contenteditable element.
onCut
Function onCut(event: Event, editor: Editor, next: Function) => Boolean
This handler is equivalent to the onCopy handler.
onDrop
Function onDrop(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when the user drops content into the contenteditable element. The event is already prevented by default, so you must define a value change to have any affect occur.
onKeyDown
Function onKeyDown(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when any key is pressed in the contenteditable element, before any action is taken.
Make sure to event.preventDefault() if you do not want the default insertion behavior to occur!
onKeyUp
Function onKeyUp(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when any key is released in the contenteditable element.
onPaste
Function onPaste(event: Event, editor: Editor, next: Function) => Boolean
This handler is called when the user pastes content into the contenteditable element. The event is already prevented by default, so you must define a value change to have any affect occur.
onSelect
Function onSelect(event: Event, editor: Editor, next: Function) => Boolean
This handler is called whenever the native DOM selection changes.
🤖 This is not Slate's internal selection representation. If you want to get notified when Slate's
value.selectionchanges, use theonChangeproperty of the<Editor>. This handler is instead meant to give you lower-level access to the DOM selection handling, which is not always triggered as you'd expect.
renderEditor
Function renderEditor(props: Object, editor: Editor, next: Function) => ReactNode|Void
The renderEditor property allows you to define higher-order-component-like behavior. It is passed all of the properties of the editor, including props.children. You can then choose to wrap the existing children in any custom elements or proxy the properties however you choose. This can be useful for rendering toolbars, styling the editor, rendering validation, etc. Remember that the renderEditor function has to render props.children for editor's content to render.
renderMark
Function renderMark(props: Object, editor: Editor, next: Function) => ReactNode|Void
Render a Mark with props. The props object contains:
{
attributes: Object,
children: ReactNode,
editor: Editor,
mark: Mark,
marks: Set<Mark>,
node: Node,
offset: Number,
text: String,
}
You must spread the props.attributes onto the top-level DOM node you use to render the mark.
renderNode
Function renderNode(props: Object, editor: Editor, next: Function) => ReactNode|Void
Render a Node with props. The props object contains:
{
attributes: Object,
children: ReactNode,
editor: Editor,
isFocused: Boolean,
isSelected: BOolean,
node: Node,
parent: Node,
readOnly: Boolean,
}
You must spread the props.attributes onto the top-level DOM node you use to render the node.
renderPlaceholder
Function renderPlaceholder(props: Object, editor: Editor, next: Function) => ReactNode|Void
Render the placeholder that is shown when the editor has no value. The props object contains:
{
editor: Editor,
readOnly: Boolean,
}
The placeholder prop that was passed to the editor can be found at editor.props.placeholder.
shouldNodeComponentUpdate
Function shouldNodeComponentUpdate(previousProps: Object, props: Object, editor: Editor, next: Function) => Boolean|Void
If this function returns true, it can force updating the node's component where otherwise it wouldn't for performance.