Editor.js API 完全指南Block、Blocks、Caret、Sanitizer、Toolbar 与 Tooltip 等公开接口详解【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.jsEditor.js 是一个输出干净 JSON 数据的块级Block-style编辑器其内核将编辑能力通过一个统一的 API 模块暴露给插件Tool与块级调优Tune开发者。本文以仓库中 docs/api.md 为骨架结合 types/api 下的类型声明与 src/components/modules/api 的源码实现系统讲解 Editor.js 的 Block API、Blocks API、Sanitizer API、Toolbar/InlineToolbar API、Listener API、Caret API、Notifier API、Destroy 与 Tooltip API以及 API 速记方法Shorthands。读完本文你将掌握如何在 Tool 内部使用this.api.*、如何在外部通过editor.*操作整个编辑器并理解每个方法背后的实现与类型签名可直接用于插件开发与宿主页面集成。一、API 总览插件与宿主各有一套入口Editor.js 的 API 由API模块统一提供见 src/components/modules/api/index.ts。该模块将内核各子模块的methods汇总为一个完整的API接口对象对 Tool / Tune 开发者Tool 的构造函数参数中会携带一个api对象插件内通过this.api.xxx调用公开方法对宿主页面new EditorJS(config)返回的实例上直接挂载了同一套 API如editor.blocks、editor.caret、editor.saver见下方API 速记方法一节。最权威的接口定义位于 types/api/index.d.ts它export了blocks、events、listeners、sanitizer、saver、selection、styles、caret、toolbar、notifier、tooltip、inline-toolbar、block、readonly、i18n、ui、tools等全部子接口。源码中API.methods的完整装配如下src/components/modules/api/index.ts{ blocks: this.Editor.BlocksAPI.methods, caret: this.Editor.CaretAPI.methods, tools: this.Editor.ToolsAPI.methods, events: this.Editor.EventsAPI.methods, listeners: this.Editor.ListenersAPI.methods, notifier: this.Editor.NotifierAPI.methods, sanitizer: this.Editor.SanitizerAPI.methods, saver: this.Editor.SaverAPI.methods, selection: this.Editor.SelectionAPI.methods, styles: this.Editor.StylesAPI.classes, toolbar: this.Editor.ToolbarAPI.methods, inlineToolbar: this.Editor.InlineToolbarAPI.methods, tooltip: this.Editor.TooltipAPI.methods, i18n: this.Editor.I18nAPI.methods, readOnly: this.Editor.ReadOnlyAPI.methods, ui: this.Editor.UiAPI.methods, }类型层面的最小接口形态docs/api.md 中的API接口示例export interface API { blocks: IBlocksAPI; caret: ICaretAPI; sanitizer: ISanitizerAPI; toolbar: IToolbarAPI; // ... }此外源码还提供了getMethodsForTool(toolName, isTune)src/components/modules/api/index.ts它会在通用 API 之上覆盖注入该 Tool 专属的i18n翻译方法——这解释了为什么不同 Tool 拿到的this.api.i18n会自动带上其命名空间。二、Block API操作单个块的属性与方法Block API 描述的是某一个具体 Block的属性和方法。你可以通过editor.blocks.getBlockByIndex(index)或getById(id)拿到它也可以在 Tool 构造函数参数其类型见 types/tools/block-tool.d.ts的block属性中直接获得当前块。完整声明见 types/api/block.d.ts核心成员如下成员类型说明idstringBlock 唯一标识符只读namestringBlock 所用 Tool 的名称即初始化配置tools属性中指定的 keyconfigToolConfig编辑器初始化时传入的 Tool 配置holderHTMLElement包裹 Tool HTML 内容的宿主元素isEmptybooleanBlock 是否没有任何可编辑内容selectedbooleanBlock 是否被跨块选择Cross-Block Selection选中focusablebooleanBlock 是否有可聚焦的输入区新增成员types/api/block.d.ts中定义stretchedboolean设置/读取 Block 的拉伸状态Setter Gettercall(methodName, param?)void带错误检查与异常处理地调用 Tool 实例方法例如 块生命周期钩子save()Promisevoid \| SavedData从当前 Block 状态保存数据返回 Tool 名称与保存耗时validate(data)Promiseboolean若 Tool 定义了validate方法则调用之dispatchChange()void主动告知编辑器本块已变更用于手动触发onChange回调适合编辑器内核无法感知的块内变更getActiveToolboxEntry()PromiseToolboxConfigEntry \| undefined返回与当前 Block 数据对应的 Toolbox 条目例如 Heading 1/2/3供动态 Toolbox 使用types/api/block.d.ts#L82-L86典型用法在 Tool 内部this.api.block可直接读取block.holder定位 DOM、用block.isEmpty判断占位符显示在宿主侧可用block.call(methodName, params)安全调用 Tool 的公开方法其底层会自动做存在性检查与错误处理。三、Blocks API块的批量增删改查与渲染Blocks API 提供对整个块集合的操作方法清单完整类型见 types/api/blocks.d.ts方法说明render(data)渲染传入的 JSON 数据OutputDatarenderFromHTML(data)解析并渲染传入的 HTML 字符串不适用于生产环境swap(fromIndex, toIndex)交换两个位置的 Block已废弃改用movemove(toIndex, fromIndex?)将 Block 移动到新位置fromIndex缺省时为当前块索引delete(index?)删除指定索引的 Block缺省删除当前块getCurrentBlockIndex()获取当前块索引getBlockByIndex(index)按索引返回 Block API 对象getBlocksCount()返回块总数stretchBlock(index, status)拉伸 Block已废弃改用 Block API 的stretchedinsertNewBlock()在当前工作区后插入新块已废弃insert(type?, data?, config?, index?, needToFocus?)按参数插入新块update(id, data?, tunes?)按 Block id 更新块数据与块调优tune数据insert在类型声明中还有两个额外可选参数types/api/blocks.d.ts#L115-L123replace是否替换该索引上已存在的块默认false与id新块的显式 id省略则自动生成并返回新插入块的BlockAPI。除原文档列出的方法外类型声明还包含以下常用补充能力types/api/blocks.d.tsgetById(id)按 id 返回 Block APIgetBlockIndex(blockId)按 id 获取块索引getBlockByElement(element)按 HTML 元素反查所属 BlockinsertMany(blocks, index?)在指定索引批量插入多个块composeBlockData(toolName)为指定 Tool 生成一个空块的数据convert(id, newType, dataOverrides?)将块转换为另一种类型要求源/目标 Tool 分别提供conversionConfig.export/conversionConfig.import转换不可行时抛出错误clear()清空编辑器区域内的所有块。四、Sanitizer APIHTML 净化sanitizer.clean(taintString, config)使用 HTMLJanitor 清洗脏字符串返回干净字符串实现见 src/components/modules/api/sanitizer.ts底层调用 src/components/utils/sanitizer.ts 的clean。类型签名types/api/sanitizer.d.tsclean(taintString: string, config: SanitizerConfig): string;要点Editor.js 自带一套不含任何属性的基础净化配置你可以传入自己的config进行继承式扩展若 Tool 启用了行内工具inline-tools其净化规则会被取出并与你传入的自定义规则合并。原文档给出的完整示例let taintString divp stylefont-size: 5em;b/bBlockWithTexta onclickvoid(0)/div let customConfig { b: true, p: { style: true, }, } this.api.sanitizer.clean(taintString, customConfig);上例中b标签被允许保留p标签的style属性被放行而a标签上的onclick事件属性会被清洗掉——这正是编辑器保存内容时对不可信 HTML 进行安全兜底的典型场景。五、Toolbar API 与 InlineToolbar APIToolbar APItypes/api/toolbar.d.ts方法说明open()打开 Toolbarclose()关闭 Toolbar同时关闭 Toolbox 与块设置面板若已打开toggleBlockSettings(openingState?)切换当前块的设置面板开关状态toggleToolbox(openingState?)切换 Toolbox 开关状态InlineToolbar APItypes/api/inline-toolbar.d.ts方法说明open()为当前选区打开行内工具条close()关闭行内工具条这两个 API 通常由宿主页面在需要程序化控制工具栏显示时使用例如在自定义快捷键或外部按钮中调用editor.toolbar.toggleToolbox(true)。六、Listener API受控的 DOM 监听Listener API 用于管理 DOM 事件监听types/api/listeners.d.ts。其价值在于所有通过该 API 注册的监听器都会被内核统一收集并在编辑器销毁时自动移除——解决忘了 removeEventListener 导致内存泄漏的经典问题。方法说明on(element, eventType, handler, useCapture?)向元素添加事件监听返回监听器 idoff(element, eventType, handler, useCapture?)按元素/事件/处理函数移除监听offById(id)按on返回的监听器 id 移除监听Tool 开发时优先使用this.api.listeners.on(...)代替原生addEventListener可将事件清理工作完全交给内核。七、Caret API光标位置管理Caret API 提供管理光标位置的方法types/api/caret.d.ts。每个方法都接受position与offset两个参数offset用于将光标按指定字符数偏移。Position取值及语义Value说明start光标置于块开头end光标置于块末尾default大致模拟浏览器默认行为多数情况下等价于start每个方法返回boolean成功设置返回true失败例如目标索引处没有块返回false。方法清单setToFirstBlock(position?, offset?): boolean— 光标移到第一个块setToLastBlock(position?, offset?): boolean— 光标移到最后一个块setToNextBlock(position?, offset?): boolean— 光标移到下一个块setToPreviousBlock(position?, offset?): boolean— 光标移到上一个块setToBlock(blockOrIdOrIndex, position?, offset?): boolean— 光标移到指定块。注意类型声明中第一个参数可以是BlockAPI、Block id 或索引三者之一见types/api/caret.d.ts#L51-L57对应源码resolveBlock解析逻辑focus(atEnd?): boolean— 光标聚焦到编辑器atEnd为true时置于末尾。从源码实现看src/components/modules/api/caret.tssetToFirstBlock会先检查BlockManager.firstBlock是否存在不存在则直接返回false默认position取this.Editor.Caret.positions.DEFAULT默认offset为0——这与类型签名中的可选参数完全一致。八、Notifier API通知消息需要展示成功或失败消息时可使用通知模块codex-notifier接口见 types/api/notifier.d.ts。在宿主侧调用原文档示例let editor new EditorJS({ onReady: () { editor.notifier.show({ message: Editor is ready! }); }, });在 Tool 类中调用原文档示例this.api.notifier.show({ message: Cannot upload image. Wrong mime-type., style: error, });通知的视觉效果如下来自仓库 docs 中的实际截图show支持NotifierOptions、ConfirmNotifierOptions、PromptNotifierOptions三种选项类型可满足普通提示、确认框与输入框三类交互需求。九、Destroy API销毁编辑器实例当页面不再需要该编辑器时调用editor.destroy()。它依次执行以下步骤见 docs/api.md 与 src/components/modules/api 相关实现将宿主元素holder的innerHTML置为空字符串清空其内容移除所有与 Editor.js 相关的事件监听器这正是 Listener API 统一收集监听器的意义所在删除实例对象上的全部属性并将实例的prototype置为null。执行destroy后编辑器实例会变成一个空对象从而释放页面上占用的 JS Heap 内存。这在 SPA 单页应用中切换页面/组件时尤其重要。十、Tooltip API工具提示Tooltip API 用于在元素附近显示帮助提示参数与codex-tooltip库一致类型见 types/api/tooltip.d.ts。showthis.api.tooltip.show(element, content, options)— 在指定元素上显示自定义内容的 Tooltip。参数类型说明elementHTMLElementTooltip 将显示在该元素附近contentString或Node追加到 Tooltip 中的内容optionsObject显示选项见下表可用显示选项名称类型作用placementtop/bottom/left/rightTooltip 的显示方位默认bottommarginTopNumbertop方位时 Tooltip 上方的偏移marginBottomNumberbottom方位时 Tooltip 下方的偏移marginLeftNumberleft方位时 Tooltip 左侧的偏移marginRightNumberright方位时 Tooltip 右侧的偏移delayNumber显示前的延迟毫秒默认70hidingDelayNumber隐藏前的延迟毫秒默认0hidethis.api.tooltip.hide()— 隐藏 Tooltip。onHoverthis.api.tooltip.onHover(element, content, options)— 便捷装饰器在mouseenter时显示、mouseleave时隐藏 Tooltip适合为按钮、图标等控件添加悬停说明。this.api.tooltip.show(element, content, options); this.api.tooltip.hide(); this.api.tooltip.onHover(element, content, options);十一、API 速记方法ShorthandsEditor.js 实例对部分 API 提供了速记别名方便宿主页面调用别名对应方法clearblocks.clearrenderblocks.renderfocuscaret.focussavesaver.save原文档示例const editor EditorJS(); editor.focus(); editor.save();save()的完整类型为save(): PromiseOutputDatatypes/api/saver.d.ts返回的是整个编辑器的干净 JSON 输出——这也是 Editor.js 以clean JSON output为核心卖点的落点。小结Editor.js 的 API 设计遵循模块化 统一出口的思路内核每个功能模块块管理、光标、净化、工具栏、监听、通知、Tooltip、保存器等各自实现methods再由 src/components/modules/api/index.ts 汇总为统一的API对象并同步注入给 Tool 与宿主实例。开发插件时以 docs/tools.md 配合本文的 API 清单使用宿主集成时则优先利用速记方法focus/save/clear/render与destroy()管理生命周期。所有方法的权威签名均可直接查阅 types/api 目录下的类型声明文件其与源码实现一一对应可作为集成与调试时最可靠的参考依据。【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考