Editor.js 快速上手：块级编辑器架构、安装配置与干净 JSON 输出实战指南-酒店常州论坛

Editor.js 快速上手：块级编辑器架构、安装配置与干净 JSON 输出实战指南

【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js

Editor.js 是一款开源的块级（Block-Style）所见即所得文本编辑器，它的核心特色是将内容拆分为一个个独立「块」（Block），每一类块由独立插件（Tool）提供，从而获得极高的扩展性。本文将基于当前仓库（@editorjs/editorjs，版本 2.31.7）的源码与文档，完整讲解从安装、工具装配、实例初始化到数据保存的全流程，并深入解读输出数据结构与核心配置项的底层实现，帮助你快速在 Web 应用中集成一套可清洗、可扩展、可跨端复用的编辑器方案。

Editor.js 是什么：块级编辑器与干净 JSON 输出

块级（Block-Style）编辑器的核心思想

与经典 WYSIWYG 编辑器使用单一contenteditable元素承载整篇 HTML 标记不同，Editor.js 的工作区由独立的块组成：段落、标题、图片、列表、引用等各自是一个独立的可编辑元素（或更复杂的结构），由插件提供、由编辑器核心统一管理。正如仓库中的 example.html 所描述的：用户输入的内容被拆分为独立的 Blocks，每个 Block 都是独立的编辑单元，这种结构让内容组织、样式隔离与功能扩展都更加可控。

干净 JSON 输出：内容与样式解耦

经典编辑器输出的是「内容数据与外观标记混杂」的原始 HTML，而 Editor.js 输出的是包含每个块数据的 JSON 对象。这意味着同一份数据可以自由复用：

渲染为 HTML 供 Web 客户端使用；
在 iOS / Android 等移动端原生渲染；
生成 Facebook Instant Articles 或 Google AMP 标记；
生成音频版本、供语音阅读器解析，或作为 AI 聊天机器人的内容源；
在后端进行清洗（Sanitize）、校验与处理。

数据格式（即OutputData）由 types/data-formats/output-data.d.ts 定义，顶层包含三个字段：

其中每个块（OutputBlockData）包含：id（块唯一 ID）、type（Tool 类型名）、data（Tool 保存的数据）、以及可选的tunes（Block Tunes 数据）。

安装 Editor.js

安装只需三步：安装核心 → 安装所需 Tools → 初始化实例。支持 NPM、Yarn 或 CDN 三种方式，详细步骤可参考 docs/installation.md。

方式一：NPM / Yarn（推荐）

npm i @editorjs/editorjs

然后在应用中引入模块：

import EditorJS from '@editorjs/editorjs';

仓库 package.json 表明该包以 UMD（dist/editorjs.umd.js）与 ESM（dist/editorjs.mjs）两种格式发布，并随包附带 TypeScript 类型声明（types/index.d.ts），可在现代打包工具（如仓库使用的 Vite）中直接使用。

方式二：CDN

可通过 jsDelivr CDN 加载指定版本：

https://cdn.jsdelivr.net/npm/@editorjs/editorjs@2.31.7

再以普通<script>标签引入：

<script src="..."></script>

方式三：本地文件

将构建产物editor.js复制到项目目录后直接引用：

<script src="editor.js"></script>

选择并安装 Tools（块插件）

在 Editor.js 中，每个块类型都由一个独立的 Tool 插件提供，你需要按需装配。常用官方工具包括：Heading（标题）、Quote（引用）、Image（图片）、Simple Image（无需后端的极简图片）、Nested List（嵌套列表）、Checklist（待办清单）、Link（链接卡片）、Embed（YouTube、Twitch、Vimeo、Instagram 等嵌入）、Table（表格）、Delimiter（分隔线）、Warning（警告框）、Code（代码块）、Raw HTML（原始 HTML）、Attaches（附件）、Marker（标记）、Inline Code（行内代码）等。它们可以通过与核心相同的方式安装（NPM、CDN 或本地文件）。

以 CDN 方式加载工具为例（与 example.html 的做法一致）：

<script src="https://cdn.jsdelivr.net/npm/@editorjs/header@latest"></script> <script src="https://cdn.jsdelivr.net/npm/@editorjs/list@latest"></script> <script src="https://cdn.jsdelivr.net/npm/@editorjs/editorjs@latest"></script>

注意：工具的具体安装命令与版本请以各工具的官方发布页为准；Core 的构建与测试脚本可查看 package.json（如yarn test:e2e、yarn lint等）。

初始化编辑器实例

在页面中放置一个容器元素，作为编辑器的挂载点：

<div id="editorjs"></div>

然后创建 EditorJS 实例：

import EditorJS from '@editorjs/editorjs'; const editor = new EditorJS({ tools: { // ...你的工具配置 } });

零配置与极简配置

根据 src/components/core.ts 的实现，配置对象是可选的。直接new EditorJS()会使用默认holder（元素 ID 为editorjs）与默认 Paragraph 工具；也可以传入字符串形式的 holder ID：

var editor = new EditorJS(); // 零配置，等同 new EditorJS('editorjs') var editor = new EditorJS('editorjs');

核心初始化流程（见 src/components/core.ts）是异步的：先校验配置、构造并配置各内部模块，再依次prepare工具与渲染初始数据，全部完成后isReadyPromise 才会 resolve；初始化失败时isReady会被 reject。

holder：挂载点

holder支持元素 ID 字符串或 DOM 元素引用（见 docs/usage.md）：

var editor = new EditorJS({ holder: document.querySelector('.editor'), // DOM 元素 }); var editor2 = new EditorJS({ holder: 'codex-editor', // 等价于 document.getElementById('codex-editor') });

兼容说明：旧属性holderId已标记废弃，将被holder取代；两者不能同时传入（core.ts 会抛出校验错误）。若holder对应元素不存在，初始化也会直接报错。

工具装配（tools）

tools是一个以工具名为键的映射，值可以是 Tool 类本身，或一个配置对象。配置对象中可设置：

class：Tool 类；
inlineToolbar：布尔值或工具名数组，控制该块的 Inline Toolbar；
config：传给 Tool 构造函数的用户配置（例如placeholder）；
shortcut：为该工具绑定键盘快捷键，例如'CMD+SHIFT+H'。

参考 example.html 的完整示例：

var editor = new EditorJS({ holder: 'editorjs', readOnly: false, tools: { header: { class: Header, inlineToolbar: ['marker', 'link'], config: { placeholder: 'Header' }, shortcut: 'CMD+SHIFT+H' }, image: SimpleImage, // 也可以直接传类，不做任何配置 list: { class: List, inlineToolbar: true, shortcut: 'CMD+SHIFT+L' }, quote: { class: Quote, inlineToolbar: true, config: { quotePlaceholder: 'Enter a quote', captionPlaceholder: 'Quote\'s author', }, shortcut: 'CMD+SHIFT+O' } }, data: { /* 初始数据 */ }, onReady: function () { /* 就绪回调 */ }, onChange: function (api, event) { /* 变更回调 */ } });

核心配置参数总览

以下配置项均在 types/configs/editor-config.d.ts 中定义，其默认值处理逻辑见 core.ts：

| 配置项 | 类型 | 默认值 | 说明 | | -- | -- | -- | -- | |holder|string \| HTMLElement|'editorjs'| 编辑器挂载元素（ID 或 DOM 引用），必填 | |holderId| 同上 | 无 | 已废弃，请改用holder| |tools|Object|{}| 工具映射，键为工具名 | |defaultBlock|string|'paragraph'| 默认块工具名，initialBlock为废弃别名 | |data|OutputData|{ blocks: [] }| 初始渲染数据，为空时自动生成一个默认块 | |autofocus|boolean|false| 就绪后是否将光标置于第一个块 | |placeholder|string \| false|false| 首块占位提示文本 | |minHeight|number|300| 编辑器底部可聚焦区域高度（px） | |logLevel|LogLevels|'VERBOSE'| 控制台日志级别 | |readOnly|boolean|false| 是否以只读模式渲染 | |hideToolbar|boolean|false| 是否隐藏工具栏 | |inlineToolbar|string[] \| boolean|true| 全部工具默认的 Inline Toolbar 配置 | |sanitizer|SanitizerConfig|{ p: true, b: true, a: true }| 默认清洗规则 | |i18n|I18nConfig|{}| 国际化配置（含direction，默认ltr） | |onReady|Function| 空函数 | 编辑器就绪回调 | |onChange|Function| 空函数 | 内容变更回调 |

就绪监听：onReady 与 isReady

初始化是异步的，不会阻塞主脚本。除了配置对象中的onReady回调，还可以使用实例的isReadyPromise：

var editor = new EditorJS(); editor.isReady .then(() => { /* 编辑器已就绪 */ }) .catch((reason) => { console.log(`Editor.js initialization failed because of ${reason}`); });

也支持async/await写法保持代码同步感：

try { await editor.isReady; /* 初始化完成后的操作 */ } catch (reason) { console.log(`Editor.js initialization failed because of ${reason}`); }

其他实用配置：placeholder、autofocus 与 logLevel

placeholder：默认为空，可自定义首块提示语；使用自定义初始块时该值会作为config传入 Tool 构造函数（docs/usage.md）。
autofocus：页面加载后自动聚焦编辑器（autofocus: true）。
logLevel：控制控制台日志输出，可选值为VERBOSE（全部）、INFO（info 与 debug）、WARN（仅错误与警告）、ERROR（仅错误）。

保存数据（Saving Data）

调用实例的save()方法，它会返回一个 Promise，resolve 出保存的 JSON 数据：

const data = await editor.save();

也可以使用实例上的saverAPI：editor.saver.save()。

底层保存流程

从 src/components/modules/saver.ts 的源码可以看到保存的完整链路：

遍历BlockManager中的全部块，为每个块异步调用其save()方法提取数据；
调用每个块的validate()校验数据，校验失败（isValid为 false）的块会被跳过并记录日志；
通过sanitizeBlocks对提取的数据按各工具的清洗配置（sanitizeConfig）进行统一清洗；
最终组装出包含time、blocks、version的OutputData返回。

保存示例（配合 JSON 预览）

参考 example.html 中保存按钮的实现：

saveButton.addEventListener('click', function () { editor.save() .then((savedData) => { cPreview.show(savedData, document.getElementById("output")); }) .catch((error) => { console.error('Saving error', error); }); });

典型的保存输出

例如一个含标题与列表的文档，保存结果大致如下（块数据的具体字段由各工具决定）：

{ "time": 1718000000000, "blocks": [ { "id": "abc123", "type": "header", "data": { "text": "Editor.js", "level": 2 } }, { "id": "def456", "type": "list", "data": { "items": ["It is a block-styled editor", "It returns clean data output in JSON"], "style": "unordered" } } ], "version": "2.31.7" }

完整示例与只读模式

仓库根目录的 example/example.html 是一个可直接打开体验的完整示例页：它通过 CDN 加载了 Header、Simple Image、List、Checklist、Quote、Code、Embed、Table、Link、Warning、Marker、Inline Code 等十余个工具，展示了tools完整配置、data初始数据、onReady与onChange回调的用法；页面还内置了「保存并预览 JSON」和「切换只读模式」两个交互：

保存按钮通过editor.save()获取数据并用json-preview.js实时展示 JSON 输出；
只读切换通过editor.readOnly.toggle()实现，返回值可判断当前是否处于只读状态（example.html）。

深入阅读指引

如果你想继续深入，仓库内还有丰富的参考资料：

docs/installation.md：更完整的安装与初始化指南（含 CDN、本地文件、isReady用法）；
docs/usage.md：基础使用、快捷键、holder / placeholder / autofocus / logLevel 说明；
docs/tools.md：Tool 类结构、内部设置、粘贴处理（HTML 标签 / RegExp / 文件）、清洗（Sanitize）与转换（Conversion）配置；
docs/block-tunes.md 与 docs/tools-inline.md：Block Tunes 与 Inline Tools 的扩展机制；
docs/sanitizer.md 与 docs/api.md：数据清洗规则与编辑器 API 说明；
types/index.d.ts：EditorJS 主类、API接口与全部公共类型的类型定义（save、render、clear、focus、destroy等方法签名）；
src/components/core.ts 与 src/components/modules/saver.ts：核心引导流程与保存链路的源码实现；
docs/CHANGELOG.md：版本变更记录。

掌握上述内容后，你就可以将 Editor.js 以「块 + 插件」的方式集成进自己的产品，并通过统一的 JSON 数据打通 Web、移动端、AMP / Instant Articles 与后端处理管线，实现真正的「一次编辑、处处复用」。

【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析