1
0
mirror of https://github.com/ianstormtaylor/slate.git synced 2025-08-31 02:49:56 +02:00

Make onChange prop optional, update examples and docs to treat slate as uncontrolled (#4922)

* Make onChange prop optional, update examples and docs to treat slate as uncontrolled

* Add changeset
This commit is contained in:
Eric Meier
2022-04-03 16:52:32 +01:00
committed by GitHub
parent 08d5a12c91
commit 9892cf0ffb
29 changed files with 207 additions and 246 deletions

View File

@@ -66,53 +66,23 @@ declare module 'slate' {
}
```
```typescript
// Also you must annotate `useState<Descendant[]>` and the editor's initial value.
const App = () => {
const initialValue: CustomElement[] = []
const [value, setValue] = useState<Descendant[]>(initialValue)
return (
<Slate value={value} onChange={setValue}>
...
</Slate>
)
}
```
Next we want to create state for `value`:
```jsx
const App = () => {
const [editor] = useState(() => withReact(createEditor()))
// Keep track of state for the value of the editor.
const [value, setValue] = useState([])
return null
}
```
Next up is to render a `<Slate>` context provider.
The provider component keeps track of your Slate editor, its plugins, its value, its selection, and any changes that occur. It **must** be rendered above any `<Editable>` components. But it can also provide the editor state to other components like toolbars, menus, etc. using the `useSlate` hook.
```jsx
const initialValue = []
const App = () => {
const [editor] = useState(() => withReact(createEditor()))
const [value, setValue] = useState([])
// Render the Slate context.
return (
<Slate
editor={editor}
value={value}
onChange={newValue => setValue(newValue)}
/>
)
return <Slate editor={editor} value={initialValue} />
}
```
You can think of the `<Slate>` component as providing a context to every component underneath it.
> As of v0.67 the Slate Provider's "value" prop is now only used as initial state for editor.children. If your code relies on replacing editor.children you should do so by replacing it directly instead of relying on the "value" prop to do this for you. See [Slate PR 4540](https://github.com/ianstormtaylor/slate/pull/4540) for a more in-depth discussion.
> Slate Provider's "value" prop is only used as initial state for editor.children. If your code relies on replacing editor.children you should do so by replacing it directly instead of relying on the "value" prop to do this for you. See [Slate PR 4540](https://github.com/ianstormtaylor/slate/pull/4540) for a more in-depth discussion.
This is a slightly different mental model than things like `<input>` or `<textarea>`, because richtext documents are more complex. You'll often want to include toolbars, or live previews, or other complex components next to your editable content.
@@ -121,16 +91,14 @@ By having a shared context, those other components can execute commands, query t
Okay, so the next step is to render the `<Editable>` component itself:
```jsx
const initialValue = []
const App = () => {
const [editor] = useState(() => withReact(createEditor()))
const [value, setValue] = useState([])
return (
// Add the editable component inside the context.
<Slate
editor={editor}
value={value}
onChange={newValue => setValue(newValue)}
>
<Slate editor={editor} value={initialValue}>
<Editable />
</Slate>
)
@@ -144,22 +112,20 @@ There's only one last step. So far we've been using an empty `[]` array as the i
The value is just plain JSON. Here's one containing a single paragraph block with some text in it:
```jsx
// Add the initial value.
const initialValue = [
{
type: 'paragraph',
children: [{ text: 'A line of text in a paragraph.' }],
},
]
const App = () => {
const [editor] = useState(() => withReact(createEditor()))
// Add the initial value when setting up our state.
const [value, setValue] = useState([
{
type: 'paragraph',
children: [{ text: 'A line of text in a paragraph.' }],
},
])
const [editor] = useState(() => withReact(createEditor())
const [value, setValue] = useState()
return (
<Slate
editor={editor}
value={value}
onChange={newValue => setValue(newValue)}
>
<Slate editor={editor} value={initialValue}>
<Editable />
</Slate>
)