Editor.js API 深度解析：开发者必备指南

Editor.js API 深度解析：开发者必备指南

editor.js A block-style editor with clean JSON output 项目地址: https://gitcode.com/gh_mirrors/ed/editor.js

Editor.js 作为一款现代化的块级编辑器，其强大的 API 设计为开发者提供了丰富的扩展能力。本文将深入解析 Editor.js 的核心 API 接口，帮助开发者更好地理解和运用这些功能。

一、Block API：块级操作的核心

Block API 是 Editor.js 中最基础也是最重要的 API 之一，它提供了对单个内容块的操作能力。

关键属性和方法

1. 基础属性

   • name：获取块的工具名称（在初始化配置中定义的键名）
   • config：获取工具初始化时的配置对象
   • holder：获取包裹工具内容的 HTML 元素
   • isEmpty：判断块是否包含可编辑内容
   • selected：判断块是否被选中

2. 布局控制

   block.stretched = true; // 设置块为拉伸状态
   

3. 数据操作

   • save()：异步保存当前块的状态数据
   • validate(data)：验证块数据是否有效
   • dispatchChange()：手动触发编辑器变更事件

4. 方法调用

   block.call('customMethod', {param: value});
   

   这种设计允许安全地调用工具实例中的任何方法。

二、全局 API 接口

Editor.js 提供了一系列全局 API 模块，每个模块专注于特定功能。

1. BlocksAPI：多块管理

api.blocks.insert('paragraph', {text: 'Hello'}, {}, 0, true);

主要功能包括：

• 块的增删改查
• 块的位置交换
• 批量渲染
• 获取块信息

最佳实践：优先使用 move() 而非已弃用的 swap() 方法进行块位置调整。

2. SanitizerAPI：安全防护

const cleanHTML = api.sanitizer.clean(dirtyHTML, {
  p: {style: true},
  b: true
});

这个 API 基于 HTMLJanitor 实现，开发者可以：

• 使用默认安全配置
• 自定义白名单规则
• 自动合并内联工具的净化规则

3. 工具栏控制

api.toolbar.open();  // 打开主工具栏
api.inlineToolbar.close();  // 关闭内联工具栏

三、光标控制：CaretAPI

精准的光标控制是编辑器的核心功能之一。

api.caret.setToBlock(2, 'start', 3);  // 在第3个块起始位置偏移3个字符

支持的光标位置参数：

• start：块起始位置
• end：块结束位置
• default：浏览器默认行为

四、实用工具 API

1. NotifierAPI：用户反馈

api.notifier.show({
  message: '操作成功',
  style: 'success'  // 或 'error'
});

2. TooltipAPI：提示工具

api.tooltip.show(element, '提示内容', {
  placement: 'top',
  delay: 100
});

支持丰富的配置选项：

• 四种定位方式
• 各方向边距调整
• 显示/隐藏延迟

3. ListenerAPI：事件管理

api.listeners.on(element, 'click', handler);
// 无需手动移除，编辑器会自动清理

五、生命周期管理

销毁实例

editor.destroy();  // 彻底清理编辑器实例

销毁过程包括：

1. 清空容器元素
2. 移除所有事件监听
3. 重置实例对象

六、API 快捷方式

Editor.js 提供了常用方法的快捷访问方式：

| 快捷方式 | 对应方法 | |----------|------------------| | clear() | blocks.clear() | | render() | blocks.render() | | focus() | caret.focus() | | save() | saver.save() |

editor.focus();  // 等同于 editor.api.caret.focus()

结语

Editor.js 的 API 设计体现了模块化、功能专一化的思想。通过深入理解这些 API，开发者可以：

1. 创建更强大的自定义工具
2. 实现精细的编辑器控制
3. 构建更安全的富文本处理流程
4. 提供更友好的用户交互体验

建议开发者在实际项目中结合具体需求，灵活运用这些 API 接口，充分发挥 Editor.js 的潜力。

editor.js A block-style editor with clean JSON output 项目地址: https://gitcode.com/gh_mirrors/ed/editor.js