mirror of
https://github.com/ianstormtaylor/slate.git
synced 2025-09-02 19:52:32 +02:00
Next (#3093)
* remove some key usage from core, refactor Operations.apply * undeprecate some methods * convert more key usage to paths * update deprecations * convert selection commands to use all paths * refactor word boundary selection logic * convert many at-range commands to use paths * convert wrapBlock and wrapInline to not use keys * cleanup * remove chainability from editor * simplify commands, queries and middleware * convert deleteAtRange * remove key usage from schema, deprecate *ByKey methods * migrate *ByKey tests, remove index from *ByPath signatures * rename at-current-range tests * deprecate mode key usage, migrate more tests away from keys * deprecate range and point methods which rely on keys to work * refactor insertBlock, without fixing warnings * add pathRef/pointRef, fix insertBlock/Inline deprecations, work on insertFragment * refactor insertFragment * get rich-text example rendering * fix lint * refactor query files, fix more tests * remove unused queries, refactor others * deprecate splitDescendantsByPath * merge master * add typescript, convert slate, slate-hyperscript, slate-plain-serializer * add Point, Path, Range, Annotation tests * add Annotation, Change, Element, Fragment, Mark, Range, Selection, Value interfaces tests * add Operation and Text tests * add Node tests * get operations and normalization tests working for slate * get *AtPath command tests passing * rename *AtPath command tests * rename * get *AtPoint tests working * rename * rename * add value queries tests * add element, mark and path queries tests * convert most on-selection tests * convert on-selection commands * rename * get addMarks and delete commands working * rename * rename * rename * refactor value.positions(), work on delete tests * progress on delete tests * more delete work * finish delete tests * start converting to at-based commands * restructure query tests * restructure operations tests * more work converting to multi-purpose commands * lots of progress on converting to at-based commands * add unwrapNodes * remove setValue * more progress * refactor node commands to use consistent matching logic * cleanup, get non-fragment commands passing * remove annotations and isAtomic * rename surround/pluck to cover/uncover * add location concept, change at-path to from-path for iterables * refactor batches * add location-based queries * refactor hanging logic * more location query work * renaming * use getMatch more * add split to wrap/unwrap * flip levels/ancestors ordering * switch splitNodes to use levels * change split to always:false by default * fix tests * add more queries tests * fixing more delete logic * add more splitNodes tests * get rest of delete tests passing * fix location-based logic in some commands * cleanup * get previous packages tests passing again * add slate-history package * start slate-schema work * start of react working * rendering fixes * get rich and plain text examples working * get image example working with hooks and dropping * refactor onDrop to be internal * inline more event handlers * refactor lots of event-related logic * change rendering to use render props * delete unused stuff * cleanup dom utils * remove unused deps * remove unnecessary packages, add placeholder * remove slate-react-placeholder package * remove unused dep * remove unnecessary tests, fix readonly example * convert checklists example * switch to next from webpack * get link example working * convert more examples * preserve keys, memoized leafs/texts, fix node lookup * fix to always useLayoutEffect for ordering * fix annotations to be maps, memoize elements * remove Change interface * remove String interface * rename Node.entries to Node.nodes * remove unnecessary value queries * default to selection when iterating, cleanup * remove unused files * update scroll into view logic * fix undoing, remove constructor types * dont sync selection while composing * add workflows * remove unused deps * convert mentions example * tweaks * convert remaining examples * rename h to jsx, update schema * fix schema tests * fix slate-schema logic and tests * really fix slate-schema and forced-layout example * get start of insertFragment tests working * remove Fragment interface * remove debugger * get all non-skipped tests passing * cleanup deps * run prettier * configure eslint for typescript * more eslint fixes... * more passing * update some docs * fix examples * port windows undo hotkey change * fix deps, add basic firefox support * add event overriding, update walkthroughs * add commands, remove classes, cleanup examples * cleanup rollup config * update tests * rename queries tests * update other tests * update walkthroughs * cleanup interface exports * cleanup, change mark transforms to require location * undo mark transform change * more * fix tests * fix example * update walkthroughs * update docs * update docs * remove annotations * remove value, move selection and children to editor * add migrating doc * fix lint * fix tests * fix DOM types aliasing * add next export * update deps, fix prod build * fix prod build * update scripts * update docs and changelogs * update workflow and pull request template
This commit is contained in:
Ian Storm Taylor
GitHub
117
docs/walkthroughs/01-installing-slate.md
Normal file
117
docs/walkthroughs/01-installing-slate.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Installing Slate
|
||||
|
||||
Slate is a monorepo divided up into multi npm packages, so to install it you do:
|
||||
|
||||
```
|
||||
yarn add slate slate-react
|
||||
```
|
||||
|
||||
You'll also need to be sure to install Slate's peer dependencies:
|
||||
|
||||
```
|
||||
yarn add react react-dom
|
||||
```
|
||||
|
||||
_Note, if you'd rather use a pre-bundled version of Slate, you can `yarn add slate` and retrieve the bundled `dist/slate.js` file! Check out the [Using the Bundled Source](./using-the-bundled-source.md) guide for more information._
|
||||
|
||||
Once you've installed Slate, you'll need to import it.
|
||||
|
||||
Slate exposes a set of modules that you'll use to build your editor. The most important of which are the `Editor` class and the `<Editable>` component.
|
||||
|
||||
```js
|
||||
// Import the Slate editor factory.
|
||||
import { createEditor } from 'slate'
|
||||
|
||||
// Import the Slate components and React plugin.
|
||||
import { Slate, Editable, withReact } from 'slate-react'
|
||||
```
|
||||
|
||||
Before we use those imports, let's start with an empty `<App>` component:
|
||||
|
||||
```jsx
|
||||
// Define our app...
|
||||
const App = () => {
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
The next step is to create a new `Editor` object. We want the editor to be stable across renders, so we use the `useMemo` hook:
|
||||
|
||||
```jsx
|
||||
const App = () => {
|
||||
// Create a Slate editor object that won't change across renders.
|
||||
const editor = useMemo(() => withReact(createEditor()), [])
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
Of course we haven't rendered anything, so you won't see any changes.
|
||||
|
||||
Next up is to render a `<Slate>` context provider.
|
||||
|
||||
The provider component leeps track of your Slate editor, it's plugins, it's default value, 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 App = () => {
|
||||
const editor = useMemo(() => withReact(createEditor()), [])
|
||||
// Render the Slate editor context.
|
||||
return <Slate editor={editor} />
|
||||
}
|
||||
```
|
||||
|
||||
You can think of the `<Slate>` component as provided an "un-controlled" editor context to every component underneath it.
|
||||
|
||||
This is a slightly different mental model than things like `<input>` or `<textarea>`, because rich-text documents are more complex. You'll often want to include toolbars, or live previews, or other complex components next to your editable content.
|
||||
|
||||
By having a shared context, those other components can execute commands, query the editor's state, etc.
|
||||
|
||||
Okay, so the next step is to render the `<Editable>` component itself:
|
||||
|
||||
```jsx
|
||||
const App = () => {
|
||||
const editor = useMemo(() => withReact(createEditor()), [])
|
||||
return (
|
||||
// Add the editable component inside the context.
|
||||
<Slate editor={editor}>
|
||||
<Editable />
|
||||
</Slate>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
The `<Editable>` component acts like `contenteditable`. Anywhere you render it will render an editable rich-text document for the nearest editor context.
|
||||
|
||||
There's only last step. So far we haven't defined what the default value of the editor is, so it's empty. Let's fix that by defining an initial value.
|
||||
|
||||
The value is just plain JSON. Here's one contains a single paragraph block with some text in it:
|
||||
|
||||
```js
|
||||
// Create our default value...
|
||||
const defaultValue = [
|
||||
{
|
||||
type: 'paragraph',
|
||||
children: [
|
||||
{
|
||||
text: 'A line of text in a paragraph.',
|
||||
marks: [],
|
||||
},
|
||||
],
|
||||
},
|
||||
]
|
||||
|
||||
const App = () => {
|
||||
const editor = useMemo(() => withReact(createEditor()), [])
|
||||
return (
|
||||
// Add the default value as a prop to the editor context.
|
||||
<Slate editor={editor} defaultValue={defaultValue}>
|
||||
<Editable />
|
||||
</Slate>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
There you have it!
|
||||
|
||||
That's the most basic example of Slate. If you render that onto the page, you should see a paragraph with the text `A line of text in a paragraph.`. And when you type, you should see the text change!
|
||||
|
||||
You'll notice that there is no `onChange` handler defined. That's because the `<Slate>` context acts like an **un-controlled** component, with the changes automatically being propogated to any context consumers. However, just like with un-controlled components you can attach an `onChange` prop to listen for changes. We'll cover that later.
|
||||
Reference in New Issue
Block a user