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
3.0 KiB
<Editor>
import { Editor } from 'slate-react'
The top-level React component that renders the Slate editor itself.
Props
<Editor
autoCorrect={Boolean}
autoFocus={Boolean}
className={String}
commands={Object}
onChange={Function}
placeholder={String | Element}
plugins={Array}
queries={Object}
readOnly={Boolean}
role={String}
schema={Object}
spellCheck={Boolean}
value={Value}
style={Object}
tabIndex={Number}
/>
autoCorrect
Boolean
Whether or not the editor should attempt to autocorrect spellcheck errors.
autoFocus
Boolean
Whether or not the editor should attempt to give the contenteditable element focus when it's loaded onto the page.
className
String
An optional class name to apply to the contenteditable element.
onChange
Function onChange(change: Change)
A change handler that will be called with the change that applied the change. You should usually pass the newly changed change.value back into the editor through its value property. This hook allows you to add persistence logic to your editor.
placeholder
String || Element
A placeholder string (or React element) that will be rendered as the default block type's placeholder.
plugins
Array
An array of Plugins that define the editor's behavior.
readOnly
Boolean
Whether the editor should be in "read-only" mode, where all of the rendering is the same, but the user is prevented from editing the editor's content.
role
String
ARIA property to define the role of the editor, it defaults to textbox when editable.
spellCheck
Boolean
Whether or not spellcheck is turned on for the editor.
style
Object
An optional dictionary of styles to apply to the contenteditable element.
tabIndex
Number
Indicates if it should participate to sequential keyboard navigation.
value
Value
A Value object representing the current value of the editor.
Plugin-like Props
In addition to its own properties, the editor allows passing any of the properties that a plugin defines as well.
These properties are actually just a convenience—an implicit plugin definition. Internally, they are grouped together and turned into a plugin that is given first priority in the plugin stack.
For example, these two snippets of code are equivalent:
const plugins = [
somePlugin
]
<Editor
onKeyDown={myKeyHandler}
plugins={plugins}
value={value}
/>
const editorPlugin = {
onKeyDown: myKeyHandler
}
const plugins = [
editorPlugin,
somePlugin
]
<Editor
plugins={plugins}
value={value}
/>
onBeforeInput
onBlur
onFocus
onCopy
onCut
onDrop
onKeyDown
onKeyUp
onPaste
onSelect
schema
To see how these properties behave, check out the Plugins reference.