编辑器 API

config 相关

getConfig

获取编辑器所有配置

editor.getConfig()

getMenuConfig

获取单个 menu 的配置。menu 配置相关的可参考这里。

editor.getMenuConfig(menuKey)

getAllMenuKeys

获取编辑器所有 menu 的 key

editor.getAllMenuKeys()

alert

编辑器 alert ，可通过 customAlert 配置。

editor.alert('错误信息', 'error')

内容处理

handleTab

控制编辑器按 tab 键时，输入什么。默认如下

editor.handleTab = () => editor.insertText('    ')

getHtml

editor.getHtml() 获取非格式化的 html

html

<p>head</p><p>hello <strong>word</strong></p>

你可以自行格式化 html ，如使用 xml-formatter

getHtmlWithId

editor.getHtmlWithId(idKey?) 获取带唯一标识属性的 HTML。

const html = editor.getHtmlWithId() // 默认属性名为 data-w-e-id
const html2 = editor.getHtmlWithId('data-node-id') // 自定义属性名

适用于需要在服务端或展示层做“节点追踪 / 精确定位”的场景。默认不影响 editor.getHtml() 的输出。

getText

获取当前编辑器的纯文本内容

const text = editor.getText()

setHtml

重置编辑器的 HTML 内容。【注意】只能解析 editor.getHtml() 返回的 HTML 格式，不支持自定义 HTML 格式。

editor.setHtml('<p>hello</p>')

如果想插入一段 HTML ，请使用 dangerouslyInsertHtml

isEmpty

判断当前编辑器内容是否为空（只有一个空段落）

editor.isEmpty()

TIP

该方法只能识别只有一个空段落情况，其他情况（如有一个空标题、空表格）请使用 editor.getText() 来判断。

getSelectionText

获取选中的文本

editor.getSelectionText()

getElemsByType

通过 type 获取编辑器的 element 列表。

editor.getElemsByType('image') // 所有图片
editor.getElemsByType('link') // 所有链接
// 其他

getElemsByTypePrefix

通过 type 前缀获取编辑器的 element 列表。

editor.getElemsByTypePrefix('header') // 获取所有标题 header1 header2 header3...
// 其他

deleteBackward

向后删除，相当于按 backspace 键。

editor.deleteBackward()

deleteForward

向后删除，相当于按 delete 键（部分键盘没有这个键）

editor.deleteForward()

deleteFragment

删除选中的内容

editor.deleteFragment()

getFragment

获取选中的内容，json 格式

editor.getFragment()

insertBreak

在选区回车换行

editor.insertBreak()

insertText

在选区插入文本

editor.insertText('xxx')

dangerouslyInsertHtml

如果是 editor.getHtml() 获取的 HTML 格式，可以完美解析。
如果是其他的 HTML 格式，则不能保证语义正确 —— dangerously 。

editor.dangerouslyInsertHtml(`<h1>标题</h1><p>文本 <b>加粗</b></p>`)

TIP

如果你想重置编辑器 HTML 内容，请使用 setHtml

clear

清空编辑器内容

editor.clear()

undo

撤销

editor.undo()

redo

重做

editor.redo()

clear history

清空 undo / redo 历史栈。

editor.clearHistory()

常见用法是在 editor.setHtml(...) 或数据回显完成后执行一次，避免用户撤销回旧内容。

history without merging

如果你需要让某次程序化插入单独成为一条历史记录，而不是和前一次操作合并，可以直接使用 slate-history 的 HistoryEditor.withoutMerging(...)。

import { HistoryEditor } from 'slate-history'

HistoryEditor.withoutMerging(editor as HistoryEditor, () => {
  editor.insertText('plain text')
})

这类用法常见于“粘贴 HTML 后，用户选择转成纯文本再插入”的场景。因为编辑器实例运行时已经经过 slate-history 扩展，所以不需要额外等待 wangEditor 再封装一个新 API。

节点操作

使用节点操作 API 前，请查看节点数据结构。

insertNode

在选区插入一个节点

const node = { type: 'paragraph', children: [{ text: 'simple text' }] }
editor.insertNode(node)

insertNodes

在选区插入多个节点

import { SlateTransforms } from '@wangeditor-next/editor'

const node1 = { type: 'paragraph', children: [{ text: 'aaa' }] }
const node2 = { type: 'paragraph', children: [{ text: 'bbb' }] }
const nodeList = [node1, node2]

SlateTransforms.insertNodes(editor, nodeList)

removeNodes

删除选区所在的节点

import { SlateTransforms } from '@wangeditor-next/editor'

SlateTransforms.removeNodes(editor)

获取选中节点

可使用 SlateEditor.nodes 获取选中的节点。详情可参考 Slate.js 中的 Editor.nodes API 。

import { SlateEditor, SlateElement, SlateNode } from '@wangeditor-next/editor'

const nodeEntries = SlateEditor.nodes(editor, {
    match: (node: SlateNode) => {  // TS syntax
    // match: (node) => {          // JS syntax
        if (SlateElement.isElement(node)) {
            if (node.type === 'paragraph') {
                return true // 匹配 paragraph
            }
        }
        return false
    },
    universal: true,
})

if (nodeEntries == null) {
    console.log('当前未选中的 paragraph')
} else {
    for (let nodeEntry of nodeEntries) {
        const [node, path] = nodeEntry
        console.log('选中了 paragraph 节点', node)
        console.log('节点 path 是', path)
    }
}

setNodes

设置选中节点的属性

import { SlateTransforms } from '@wangeditor-next/editor'

SlateTransforms.setNodes(editor, {
  // @ts-ignore
  textAlign: 'right'
}, {
  mode: 'highest' // 针对最高层级的节点
})

getParentNode

获取一个节点的父节点

const parentNode = editor.getParentNode(node) // 返回 node 或者 null

toDOMNode

获取一个节点对应的 DOM 节点

const elem = editor.toDOMNode(node) // 返回 HTMLElement

isInline

判断一个节点是否是 inline

const inline = editor.isInline(node)

isVoid

判断一个节点是否是 void

const void = editor.isVoid(node)

TIP

void node 即没有子元素的节点（它本身就可以看作是一个特殊字符），例如 image video 。可参考 html void element 定义。

你可以通过 editor.isVoid 自定义哪些元素是 void ，但需要详细学习 slate 。

isText

判断一个节点是否是 text

import { SlateText } from '@wangeditor-next/editor'

SlateText.isText(node) // true/false

isElement

判断一个节点是否是 elem

import { SlateElement } from '@wangeditor-next/editor'

SlateElement.isElement(node) // true/false

addMark

为选中的文本添加标记（文本样式）

editor.addMark('bold', true)     // 加粗
editor.addMark('color', '#999')  // 文本颜色

removeMark

对选中的文字，取消标记（文本样式）

editor.removeMark('bold') // 取消加粗

marks

获取选中文字的标记（文本样式）

import { SlateEditor } from '@wangeditor-next/editor'

SlateEditor.marks(editor) // 例如 { bold: true, color: "#595959" }

DOM 相关

id 属性

获取编辑器 id

editor.id // 如 'wangEditor-1'

isFullScreen 属性

编辑器是否全屏

editor.isFullScreen // true/false

focus

聚焦到编辑器

editor.focus()

// editor.focus(true) // 选区定位到最后

blur

失焦编辑器

editor.blur()

isFocused

判断当前编辑器是否聚焦？

editor.isFocused() // true/false

updateView

强制更新视图

editor.updateView()

TIP

updateView 是内部 API ，不建议用户使用。如要使用，也请勿频繁执行。

scrollToElem

滚动到指定元素，类似锚点。如滚动到某个标题的位置。可实现标题目录，参考 demo。

可根据 toDOMNode 获取 node 对应的 DOM 元素。

editor.scrollToElem(elemId)

showProgressBar

显示进度条，一般用于上传功能

editor.showProgressBar(progress) // progress 为 0-100 的数字

hidePanelOrModal

隐藏当前的弹框（如插入链接）和下拉列表（如设置标题、设置字体）

editor.hidePanelOrModal()

fullScreen

设置为全屏

editor.fullScreen()

TIP

全屏功能，有 html 结构的要求，请参考这里

unFullScreen

取消全屏

editor.unFullScreen()

disable

禁用编辑器，设置为只读

editor.disable()

isDisabled

判断当前编辑器是否只读？

editor.isDisabled() // true/false

enable

取消禁用，取消只读

editor.enable()

destroy

销毁编辑器和工具栏

editor.destroy()

TIP

destroy 仅仅是移除编辑器、工具栏的 DOM 节点，全局绑定的事件等。
自己定义的变量，如 const editor = createEditor({...}) ，这个 editor 还需要自己来销毁。

获取编辑区域容器 DOM

获取编辑区域容器 DOM 节点

editor.getEditableContainer()

selection 相关

selection 数据结构参考 slate Location 。

selection 属性

获取编辑器当前的选区。如果未选中，则返回 null 。

editor.selection // selection 或 null

selection 数据结构如下：

json

{
  "anchor": { "path": [1,0], "offset":8 },
  "focus": { "path": [1,0], "offset":10 }
}

select

选中一个指定的选区。

const newSelection = {
  anchor: { path: [1,0], offset:8 },
  focus: { path: [1,0], offset:10 }
}
editor.select(newSelection)

selectAll

选中所有内容

editor.selectAll()

deselect

取消选中

editor.deselect()

move

移动光标

editor.move(3) // 移动 3 个字符

moveReverse

反向移动光标

editor.moveReverse(2) // 反向移动 2 个字符

restoreSelection

恢复最近一次非 null 选区。如编辑器 blur 之后，再重新恢复选区。

editor.restoreSelection()

isSelectedAll

判断编辑器是否全部选中。

editor.isSelectedAll() // true/false

getSelectionPosition

获取选区的定位，将视情况返回 left right top bottom 的其中几个。

editor.getSelectionPosition() // 例如 { left: "80.15px", top: "116px" }

【注意】该定位是相对于编辑区域的，而非 body 。
你可以获取编辑区域 DOM 元素的定位 editor.getEditableContainer().getBoundingClientRect() 从而计算出相对于 body 的定位。

getNodePosition

获取某个节点的定位，将视情况返回 left right top bottom 的其中几个。

editor.getNodePosition(node) // 例如 { left: "80.15px", top: "116px" }

【注意】该定位是相对于编辑区域的，而非 body。
你可以获取编辑区域 DOM 元素的定位 editor.getEditableContainer().getBoundingClientRect() 从而计算出相对于 body 的定位。

自定义事件

wangEditor 使用 event-emitter 来做自定义事件。

on

监听某个事件

editor.on('event-key', fn)

off

取消监听

editor.off('event-key', fn)

once

只监听一次

editor.once('event-key', fn)

emit

触发事件

editor.emit('event-key')

内置的事件

editor.on('fullScreen', () => { console.log('fullScreen') })
editor.on('unFullScreen', () => { console.log('unFullScreen') })
editor.on('scroll', () => { console.log('scroll') })
editor.on('modalOrPanelShow', modalOrPanel => { console.log(modalOrPanel) })
editor.on('modalOrPanelHide', () => { console.log('modalOrPanelHide') })

使用 slate 解锁更多 API

wangEditor 基于 slate.js（但不依赖 React）开发

上文已列出了比较常用的 API ，但这并不是全部。 slate.js 还提供了更多 API ，可满足你的所有操作需求。

Transforms API

参考 slate Transforms API

使用如下方式即可得到 slate Transforms 对象，不用再单独安装 slate 。

import { SlateTransforms } from '@wangeditor-next/editor'

Node Editor API

参考 slate Node API

使用如下方式即可得到 slate Node 相关对象，不用再单独安装 slate 。

import { SlateEditor, SlateNode, SlateElement, SlateText } from '@wangeditor-next/editor'

Location API

参考 slate Location API

使用如下方式即可得到 slate Location 相关对象，不用再单独安装 slate 。

import { SlateLocation, SlatePath, SlatePoint, SlateRange } from '@wangeditor-next/editor'

编辑器 API ​

config 相关 ​

getConfig ​

getMenuConfig ​

getAllMenuKeys ​

alert ​

内容处理 ​

handleTab ​

getHtml ​

getHtmlWithId ​

getText ​

setHtml ​

isEmpty ​

getSelectionText ​

getElemsByType ​

getElemsByTypePrefix ​

deleteBackward ​

deleteForward ​

deleteFragment ​

getFragment ​

insertBreak ​

insertText ​

dangerouslyInsertHtml ​

clear ​

undo ​

redo ​

clear history ​

history without merging ​

节点操作 ​

insertNode ​

insertNodes ​

removeNodes ​

获取选中节点 ​

setNodes ​

getParentNode ​

toDOMNode ​

isInline ​

isVoid ​

isText ​

isElement ​

addMark ​

removeMark ​

marks ​

DOM 相关 ​

id 属性 ​

isFullScreen 属性 ​

focus ​

blur ​

isFocused ​

updateView ​

scrollToElem ​

showProgressBar ​

hidePanelOrModal ​

fullScreen ​

unFullScreen ​

disable ​

isDisabled ​

enable ​

destroy ​

获取编辑区域容器 DOM ​

selection 相关 ​

selection 属性 ​

select ​

selectAll ​

deselect ​

move ​

moveReverse ​

restoreSelection ​

isSelectedAll ​

getSelectionPosition ​

getNodePosition ​

自定义事件 ​

on ​

off ​

once ​

emit ​

内置的事件 ​

使用 slate 解锁更多 API ​

Transforms API ​

Node Editor API ​