mirror of
https://github.com/ianstormtaylor/slate.git
synced 2025-08-30 10:29:48 +02:00
update docs
This commit is contained in:
Ian Storm Taylor
10
docs/guides/changes.md
Normal file
10
docs/guides/changes.md
Normal file
@@ -0,0 +1,10 @@
|
||||
|
||||
# Changes
|
||||
|
||||
All changes to a Slate editor's state, whether it's the `selection`, `document`, `history`, etc. happen via "changes"—specifically, via the [`Change`](../reference/slate/change.md) model.
|
||||
|
||||
This is important because the `Change` model is responsible for ensuring that every change to a Slate state can be expressed in terms of low-level [operations](./operation.md).
|
||||
|
||||
Slate changing any state in the editor via a series of "change" methods.
|
||||
|
||||
|
||||
@@ -51,7 +51,7 @@ Find the Slate node from a DOM `element` and Slate `state`.
|
||||
|
||||
```js
|
||||
function onSomeNativeEvent(event) {
|
||||
const node = fidnNode(event.target)
|
||||
const node = findNode(event.target)
|
||||
// Do something with `node`...
|
||||
}
|
||||
```
|
||||
|
||||
@@ -19,31 +19,37 @@ A [`State`](./state.md) with the change's current operations applied. Each time
|
||||
|
||||
## Methods
|
||||
|
||||
### `apply`
|
||||
`apply(options: Object) => Change`
|
||||
|
||||
Applies current change steps, saving them to the history if needed.
|
||||
|
||||
### `call`
|
||||
`call(customChange: Function, ...arguments) => Change`
|
||||
`call(customChange: Function, ...args) => Change`
|
||||
|
||||
This method calls the provided function argument `customChange` with the current instance of the `Change` object as the first argument and passes through the remaining arguments.
|
||||
|
||||
The function signature for `customChange` is:
|
||||
|
||||
`customChange(change: Change, ...arguments)`
|
||||
This method calls the provided `customChange` function with the current instance of the `Change` object as the first argument and passes through the remaining `args`.
|
||||
|
||||
The purpose of `call` is to enable custom change methods to exist and called in a chain. For example:
|
||||
|
||||
```
|
||||
return state.change()
|
||||
.call(myCustomInsertTableChange, columns, rows)
|
||||
.focus()
|
||||
.apply()
|
||||
```js
|
||||
function addBoldMark(change) {
|
||||
change.addMark('bold_mark')
|
||||
}
|
||||
|
||||
function insertParagraph(change) {
|
||||
change.insertBlock('paragraph_block')
|
||||
}
|
||||
|
||||
function onSomeEvent(event, change) {
|
||||
change
|
||||
.call(insertParagraph)
|
||||
.insertText('Some text...')
|
||||
.extendToStartOfBlock()
|
||||
.call(addBoldMark)
|
||||
.collapseToEnd()
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Current State Changes
|
||||
|
||||
These changes act on the `document` based on the current `selection`. They are equivalent to calling the [Document Changes](#document-changes) with the current selection as the `range` argument, but they are there for convenience, since you often want to act with the current selection, as a user would.
|
||||
|
||||
### `deleteBackward`
|
||||
`deleteBackward(n: Number) => Change`
|
||||
|
||||
@@ -153,6 +159,8 @@ Surround the text in the current selection with `prefix` and `suffix` strings. I
|
||||
|
||||
## Selection Changes
|
||||
|
||||
These changes change the current `selection`, without touching the `document`.
|
||||
|
||||
### `blur`
|
||||
`blur() => Change`
|
||||
|
||||
@@ -234,100 +242,10 @@ Select the entire document and focus the selection.
|
||||
Unset the selection.
|
||||
|
||||
|
||||
## Node Changes
|
||||
|
||||
### `addMarkByKey`
|
||||
`addMarkByKey(key: String, offset: Number, length: Number, mark: Mark) => Change`
|
||||
|
||||
Add a `mark` to `length` characters starting at an `offset` in a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `insertNodeByKey`
|
||||
`insertNodeByKey(key: String, index: Number, node: Node) => Change`
|
||||
|
||||
Insert a `node` at `index` inside a parent [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `insertFragmentByKey`
|
||||
`insertFragmentByKey(key: String, index: Number, fragment: Fragment) => Transform`
|
||||
|
||||
Insert a [`Fragment`](./fragment.md) at `index` inside a parent [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `insertTextByKey`
|
||||
`insertTextByKey(key: String, offset: Number, text: String, [marks: Set]) => Change`
|
||||
|
||||
Insert `text` at an `offset` in a [`Text Node`](./text.md) by its `key` with optional `marks`.
|
||||
|
||||
### `moveNodeByKey`
|
||||
`moveNodeByKey(key: String, newKey: String, newIndex: Number) => Change`
|
||||
|
||||
Move a [`Node`](./node.md) by its `key` to a new parent node with its `newKey` and at a `newIndex`.
|
||||
|
||||
### `removeMarkByKey`
|
||||
`removeMarkByKey(key: String, offset: Number, length: Number, mark: Mark) => Change`
|
||||
|
||||
Remove a `mark` from `length` characters starting at an `offset` in a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `removeNodeByKey`
|
||||
`removeNodeByKey(key: String) => Change`
|
||||
|
||||
Remove a [`Node`](./node.md) from the document by its `key`.
|
||||
|
||||
### `replaceNodeByKey`
|
||||
`replaceNodeByKey(key: String, node: Node) => Change`
|
||||
|
||||
Replace a [`Node`](./node.md) in the document with a new [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `removeTextByKey`
|
||||
`removeTextByKey(key: String, offset: Number, length: Number) => Change`
|
||||
|
||||
Remove `length` characters of text starting at an `offset` in a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `setMarkByKey`
|
||||
`setMarkByKey(key: String, offset: Number, length: Number, mark: Mark, properties: Object) => Change`
|
||||
|
||||
Set a dictionary of `properties` on a [`mark`](./mark.md) on a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `setNodeByKey`
|
||||
`setNodeByKey(key: String, properties: Object) => Change` <br/>
|
||||
`setNodeByKey(key: String, type: String) => Change`
|
||||
|
||||
Set a dictionary of `properties` on a [`Node`](./node.md) by its `key`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `splitNodeByKey`
|
||||
`splitNodeByKey(key: String, offset: Number) => Change`
|
||||
|
||||
Split a node by its `key` at an `offset`.
|
||||
|
||||
### `unwrapInlineByKey`
|
||||
`unwrapInlineByKey(key: String, properties: Object) => Change` <br/>
|
||||
`unwrapInlineByKey(key: String, type: String) => Change`
|
||||
|
||||
Unwrap all inner content of an [`Inline`](./inline.md) node by its `key` that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `unwrapBlockByKey`
|
||||
`unwrapBlockByKey(key: String, properties: Object) => Change` <br/>
|
||||
`unwrapBlockByKey(key: String, type: String) => Change`
|
||||
|
||||
Unwrap all inner content of a [`Block`](./block.md) node by its `key` that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `unwrapNodeByKey`
|
||||
`unwrapNodeByKey(key: String) => Change`
|
||||
|
||||
Unwrap a single node from its parent. If the node is surrounded with siblings, its parent will be split. If the node is the only child, the parent is removed, and simply replaced by the node itself. Cannot unwrap a root node.
|
||||
|
||||
### `wrapBlockByKey`
|
||||
`wrapBlockByKey(key: String, properties: Object) => Change` <br/>
|
||||
`wrapBlockByKey(key: String, type: String) => Change`
|
||||
|
||||
Wrap the given node in a [`Block`](./block.md) node that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `wrapInlineByKey`
|
||||
`wrapInlineByKey(key: String, properties: Object) => Change` <br/>
|
||||
`wrapInlineByKey(key: String, type: String) => Change`
|
||||
|
||||
Wrap the given node in a [`Inline`](./inline.md) node that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
## Document Changes
|
||||
|
||||
These changes act on a specific [`Range`](./range.md) of the document.
|
||||
|
||||
### `deleteBackwardAtRange`
|
||||
`deleteBackwardAtRange(range: Range, n: Number) => Change`
|
||||
|
||||
@@ -439,8 +357,105 @@ Wrap the [`Inline`](./inline.md) nodes in a `range` with a new [`Inline`](./inli
|
||||
Surround the text in a `range` with `prefix` and `suffix` strings. If the `suffix` is ommitted, the `prefix` will be used instead.
|
||||
|
||||
|
||||
## Node Changes
|
||||
|
||||
These changes are lower-level, and act on a specific node by its `key`. They're often used in your custom components because you'll have access to `props.node`.
|
||||
|
||||
### `addMarkByKey`
|
||||
`addMarkByKey(key: String, offset: Number, length: Number, mark: Mark) => Change`
|
||||
|
||||
Add a `mark` to `length` characters starting at an `offset` in a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `insertNodeByKey`
|
||||
`insertNodeByKey(key: String, index: Number, node: Node) => Change`
|
||||
|
||||
Insert a `node` at `index` inside a parent [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `insertFragmentByKey`
|
||||
`insertFragmentByKey(key: String, index: Number, fragment: Fragment) => Transform`
|
||||
|
||||
Insert a [`Fragment`](./fragment.md) at `index` inside a parent [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `insertTextByKey`
|
||||
`insertTextByKey(key: String, offset: Number, text: String, [marks: Set]) => Change`
|
||||
|
||||
Insert `text` at an `offset` in a [`Text Node`](./text.md) by its `key` with optional `marks`.
|
||||
|
||||
### `moveNodeByKey`
|
||||
`moveNodeByKey(key: String, newKey: String, newIndex: Number) => Change`
|
||||
|
||||
Move a [`Node`](./node.md) by its `key` to a new parent node with its `newKey` and at a `newIndex`.
|
||||
|
||||
### `removeMarkByKey`
|
||||
`removeMarkByKey(key: String, offset: Number, length: Number, mark: Mark) => Change`
|
||||
|
||||
Remove a `mark` from `length` characters starting at an `offset` in a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `removeNodeByKey`
|
||||
`removeNodeByKey(key: String) => Change`
|
||||
|
||||
Remove a [`Node`](./node.md) from the document by its `key`.
|
||||
|
||||
### `replaceNodeByKey`
|
||||
`replaceNodeByKey(key: String, node: Node) => Change`
|
||||
|
||||
Replace a [`Node`](./node.md) in the document with a new [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `removeTextByKey`
|
||||
`removeTextByKey(key: String, offset: Number, length: Number) => Change`
|
||||
|
||||
Remove `length` characters of text starting at an `offset` in a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `setMarkByKey`
|
||||
`setMarkByKey(key: String, offset: Number, length: Number, mark: Mark, properties: Object) => Change`
|
||||
|
||||
Set a dictionary of `properties` on a [`mark`](./mark.md) on a [`Node`](./node.md) by its `key`.
|
||||
|
||||
### `setNodeByKey`
|
||||
`setNodeByKey(key: String, properties: Object) => Change` <br/>
|
||||
`setNodeByKey(key: String, type: String) => Change`
|
||||
|
||||
Set a dictionary of `properties` on a [`Node`](./node.md) by its `key`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `splitNodeByKey`
|
||||
`splitNodeByKey(key: String, offset: Number) => Change`
|
||||
|
||||
Split a node by its `key` at an `offset`.
|
||||
|
||||
### `unwrapInlineByKey`
|
||||
`unwrapInlineByKey(key: String, properties: Object) => Change` <br/>
|
||||
`unwrapInlineByKey(key: String, type: String) => Change`
|
||||
|
||||
Unwrap all inner content of an [`Inline`](./inline.md) node by its `key` that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `unwrapBlockByKey`
|
||||
`unwrapBlockByKey(key: String, properties: Object) => Change` <br/>
|
||||
`unwrapBlockByKey(key: String, type: String) => Change`
|
||||
|
||||
Unwrap all inner content of a [`Block`](./block.md) node by its `key` that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `unwrapNodeByKey`
|
||||
`unwrapNodeByKey(key: String) => Change`
|
||||
|
||||
Unwrap a single node from its parent. If the node is surrounded with siblings, its parent will be split. If the node is the only child, the parent is removed, and simply replaced by the node itself. Cannot unwrap a root node.
|
||||
|
||||
### `wrapBlockByKey`
|
||||
`wrapBlockByKey(key: String, properties: Object) => Change` <br/>
|
||||
`wrapBlockByKey(key: String, type: String) => Change`
|
||||
|
||||
Wrap the given node in a [`Block`](./block.md) node that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
### `wrapInlineByKey`
|
||||
`wrapInlineByKey(key: String, properties: Object) => Change` <br/>
|
||||
`wrapInlineByKey(key: String, type: String) => Change`
|
||||
|
||||
Wrap the given node in a [`Inline`](./inline.md) node that match `properties`. For convenience, you can pass a `type` string or `properties` object.
|
||||
|
||||
|
||||
## History Changes
|
||||
|
||||
These changes use the history to undo/redo previously made changes.
|
||||
|
||||
### `redo`
|
||||
`redo() => Change`
|
||||
|
||||
|
||||
233
docs/reference/slate/operation.md
Normal file
233
docs/reference/slate/operation.md
Normal file
@@ -0,0 +1,233 @@
|
||||
|
||||
# Operation
|
||||
|
||||
An operation is the lowest-level description of a specific change to a part of Slate's state. They are designed to be collaborative-editing friendly.
|
||||
|
||||
All of the [`Change`](./change.md) methods result in operations being created and applied to a [`State`](./state.md) They're accessible via the `change.operations` property.
|
||||
|
||||
There are a handful of Slate operation types. The goal is to have the fewest possible types, while still maintaining the necessary semantics for collaborative editing to work.
|
||||
|
||||
|
||||
## Properties
|
||||
|
||||
### `mark`
|
||||
`Array`
|
||||
|
||||
A mark that is being added or removed by the operation, or being used as a comparison point when updating an existing mark.
|
||||
|
||||
### `marks`
|
||||
`Array`
|
||||
|
||||
A set of marks that are being added by the operation.
|
||||
|
||||
### `offset`
|
||||
`Number`
|
||||
|
||||
The offset inside a [`Text`](./text.md) node that the operation acts on.
|
||||
|
||||
### `path`
|
||||
`Array`
|
||||
|
||||
The path to the node the operation acts on. The array contains a list of indexes, representing where the node is in the `document` hierarchy.
|
||||
|
||||
### `text`
|
||||
`String`
|
||||
|
||||
The text that is being inserted or removed by the operation.
|
||||
|
||||
### `type`
|
||||
`String`
|
||||
|
||||
The `type` of the operation.
|
||||
|
||||
|
||||
## Text Operations
|
||||
|
||||
### `insert_text`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'insert_text',
|
||||
path: Array,
|
||||
offset: Number,
|
||||
text: String,
|
||||
marks: Array,
|
||||
}
|
||||
```
|
||||
|
||||
Inserts a `text` string at `offset` into a text node at `path`, with optional `marks` to be applied to the inserted characters.
|
||||
|
||||
### `remove_text`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'remove_text',
|
||||
path: Array,
|
||||
offset: Number,
|
||||
text: String,
|
||||
}
|
||||
```
|
||||
|
||||
Removes a string of `text` at `offset` into a text node at `path`.
|
||||
|
||||
|
||||
## Mark Operations
|
||||
|
||||
### `add_mark`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'add_mark',
|
||||
path: Array,
|
||||
offset: Number,
|
||||
length: Number,
|
||||
mark: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Adds a `mark` to the text node at `path` starting at an `offset` and spanning `length` characters.
|
||||
|
||||
### `remove_mark`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'remove_mark',
|
||||
path: Array,
|
||||
offset: Number,
|
||||
length: Number,
|
||||
mark: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Removes a `mark` from a text node at `path` starting at an `offset` and spanning `length` characters.
|
||||
|
||||
### `set_mark`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'set_mark',
|
||||
path: Array,
|
||||
offset: Number,
|
||||
length: Number,
|
||||
mark: Object,
|
||||
properties: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Set new `properties` on any marks that match an existing `mark` in a text node at `path`, starting at an `offset` and spanning `length` characters.
|
||||
|
||||
|
||||
## Node Operations
|
||||
|
||||
### `insert_node`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'insert_node',
|
||||
path: Array,
|
||||
node: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Insert a new `node` at `path`.
|
||||
|
||||
### `merge_node`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'merge_node',
|
||||
path: Array,
|
||||
}
|
||||
```
|
||||
|
||||
Merge the node at `path` with it's previously sibling.
|
||||
|
||||
### `move_node`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'move_node',
|
||||
path: Array,
|
||||
newPath: Array,
|
||||
}
|
||||
```
|
||||
|
||||
Move the node at `path` to a `newPath`.
|
||||
|
||||
### `remove_node`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'remove_node',
|
||||
path: Array,
|
||||
node: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Remove the node at `path`.
|
||||
|
||||
### `set_node`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'set_node',
|
||||
path: Array,
|
||||
properties: Object,
|
||||
node: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Set new `properties` on the node at `path`.
|
||||
|
||||
### `split_node`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'split_node',
|
||||
path: Array,
|
||||
position: Number,
|
||||
target: Number,
|
||||
}
|
||||
```
|
||||
|
||||
Split the node at `path` at `position`. The `position` refers to either the index in the child nodes in the case of [`Block`](./block.md) or [`Inline`](./inline.md) nodes, and the index in the characters in the case of [`Text`](./text.md) nodes. In the case of nested splits, `target` refers to the target path of the child split operation.
|
||||
|
||||
|
||||
## State Operations
|
||||
|
||||
### `set_selection`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'set_selection',
|
||||
properties: Object,
|
||||
selection: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Set new `properties` on the state's selection.
|
||||
|
||||
### `set_state`
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'set_state',
|
||||
properties: Object,
|
||||
state: Object,
|
||||
}
|
||||
```
|
||||
|
||||
Set new `properties` on a state. Properties can contain `data` and `decorations`.
|
||||
|
||||
|
||||
## Helpers
|
||||
|
||||
### `apply`
|
||||
`apply(state: State, operation: Object) => State`
|
||||
|
||||
Applies an `operation` to a `state` object.
|
||||
|
||||
### `invert`
|
||||
`invert(operation: Object) => Object`
|
||||
|
||||
Create an inverse operation that will undo the changes made by the original.
|
||||
Reference in New Issue
Block a user