MediumEditor 富文本编辑器 API 详解

MediumEditor 富文本编辑器 API 详解

medium-editor Medium.com WYSIWYG editor clone. Uses contenteditable API to implement a rich text solution. 项目地址: https://gitcode.com/gh_mirrors/me/medium-editor

MediumEditor 是一个轻量级的富文本编辑器，它模仿 Medium.com 的编辑体验，提供了简洁而强大的 API。本文将深入解析 MediumEditor 的核心 API，帮助开发者更好地理解和使用这个编辑器。

编辑器初始化与销毁

构造函数 MediumEditor(elements, options)

这是创建编辑器实例的入口函数，主要功能包括：

• 将传入的元素转换为可编辑的 contenteditable 元素
• 处理 <textarea> 元素的特殊转换
• 初始化自定义扩展和按钮
• 设置必要的事件监听

参数说明：

• elements：可以是选择器字符串、DOM 元素或元素集合
• options：配置对象，用于自定义编辑器行为

示例代码：

const editor = new MediumEditor('.editable', {
    toolbar: {
        buttons: ['bold', 'italic', 'underline']
    }
});

destroy() 方法

完全销毁编辑器实例，包括：

• 调用所有扩展的销毁方法
• 移除所有事件监听
• 清理自定义属性
• 恢复隐藏的 <textarea> 元素

setup() 方法

重新初始化已被销毁的编辑器实例，使用原始的选择器和配置。

元素动态管理

addElements(elements)

动态添加元素到已初始化的编辑器实例中：

• 支持多种元素传入方式
• 自动处理 <textarea> 转换
• 确保新元素获得完整功能

removeElements(elements)

从编辑器中移除元素：

• 保留元素的 contenteditable 属性
• 移除所有事件监听和引用
• 恢复 <textarea> 元素

事件处理机制

MediumEditor 提供了灵活的事件系统：

on() 和 off()

基于原生 addEventListener 和 removeEventListener 的封装，确保在编辑器销毁时自动清理事件。

subscribe() 和 unsubscribe()

用于监听和取消监听自定义事件，如：

• editableInput：内容变化时触发
• blur：失去焦点时触发
• focus：获得焦点时触发

示例：

editor.subscribe('editableInput', (event, editable) => {
    console.log('内容已修改', editable.innerHTML);
});

选区操作 API

MediumEditor 提供了丰富的选区管理功能：

saveSelection() 和 restoreSelection()

保存和恢复用户选区状态，常用于临时操作后恢复原有选区。

selectElement(element)

将选区设置为指定元素的内容，并更新工具栏状态。

exportSelection() 和 importSelection()

将选区状态序列化和反序列化，便于存储和恢复复杂选区。

编辑器操作命令

execAction(action, opts)

执行原生编辑命令，如：

• bold：加粗文本
• italic：斜体文本
• createLink：创建链接

示例：

editor.execAction('bold');
editor.execAction('createLink', {value: 'https://example.com'});

pasteHTML(html, options)

安全地插入 HTML 内容，支持自定义清理规则：

• cleanTags：要移除的标签
• unwrapTags：要去除但保留内容的标签
• cleanAttrs：要移除的属性

实用工具方法

getContent(index) 和 setContent(html, index)

获取和设置编辑器内容，支持按索引操作多个编辑区域。

serialize()

将编辑器内容序列化为 JSON 对象，便于存储和传输。

delay(fn)

延迟执行函数，延迟时间由配置中的 delay 选项决定。

静态方法和属性

MediumEditor.getEditorFromElement(element)

通过 DOM 元素获取关联的编辑器实例。

MediumEditor.version

获取当前编辑器版本号。

最佳实践建议

1. 动态内容管理：使用 addElements 和 removeElements 实现动态内容区域管理。

2. 事件处理：优先使用 subscribe 监听自定义事件，而非直接绑定原生事件。

3. 选区保存：在执行可能破坏选区的操作前，先调用 saveSelection()。

4. 安全插入：使用 pasteHTML 而非直接操作 DOM，确保内容安全。

5. 多实例管理：通过 getEditorFromElement 在复杂应用中管理多个编辑器实例。

通过合理利用这些 API，开发者可以构建出功能丰富、用户体验良好的富文本编辑功能。MediumEditor 的 API 设计既保持了简单性，又提供了足够的灵活性，适合各种复杂的编辑场景。

medium-editor Medium.com WYSIWYG editor clone. Uses contenteditable API to implement a rich text solution. 项目地址: https://gitcode.com/gh_mirrors/me/medium-editor