十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

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

Editor.js 快速上手:块级编辑器架构、安装配置与干净 JSON 输出实战指南 Editor.js 快速上手块级编辑器架构、安装配置与干净 JSON 输出实战指南【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.jsEditor.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 定义顶层包含三个字段| 字段 | 类型 | 说明 | | -- | -- | -- | |time|number| 保存时的时间戳毫秒 | |blocks|OutputBlockData[]| 保存的所有块 | |version|string| 编辑器版本号 |其中每个块OutputBlockData包含id块唯一 ID、typeTool 类型名、dataTool 保存的数据、以及可选的tunesBlock Tunes 数据。安装 Editor.js安装只需三步安装核心 → 安装所需 Tools → 初始化实例。支持 NPM、Yarn 或 CDN 三种方式详细步骤可参考 docs/installation.md。方式一NPM / Yarn推荐npm i editorjs/editorjs然后在应用中引入模块import EditorJS from editorjs/editorjs;仓库 package.json 表明该包以 UMDdist/editorjs.umd.js与 ESMdist/editorjs.mjs两种格式发布并随包附带 TypeScript 类型声明types/index.d.ts可在现代打包工具如仓库使用的 Vite中直接使用。方式二CDN可通过 jsDelivr CDN 加载指定版本https://cdn.jsdelivr.net/npm/editorjs/editorjs2.31.7再以普通script标签引入script src.../script方式三本地文件将构建产物editor.js复制到项目目录后直接引用script srceditor.js/script选择并安装 Tools块插件在 Editor.js 中每个块类型都由一个独立的 Tool 插件提供你需要按需装配。常用官方工具包括Heading标题、Quote引用、Image图片、Simple Image无需后端的极简图片、Nested List嵌套列表、Checklist待办清单、Link链接卡片、EmbedYouTube、Twitch、Vimeo、Instagram 等嵌入、Table表格、Delimiter分隔线、Warning警告框、Code代码块、Raw HTML原始 HTML、Attaches附件、Marker标记、Inline Code行内代码等。它们可以通过与核心相同的方式安装NPM、CDN 或本地文件。以 CDN 方式加载工具为例与 example.html 的做法一致script srchttps://cdn.jsdelivr.net/npm/editorjs/headerlatest/script script srchttps://cdn.jsdelivr.net/npm/editorjs/listlatest/script script srchttps://cdn.jsdelivr.net/npm/editorjs/editorjslatest/script注意工具的具体安装命令与版本请以各工具的官方发布页为准Core 的构建与测试脚本可查看 package.json如yarn test:e2e、yarn lint等。初始化编辑器实例在页面中放置一个容器元素作为编辑器的挂载点div ideditorjs/div然后创建 EditorJS 实例import EditorJS from editorjs/editorjs; const editor new EditorJS({ tools: { // ...你的工具配置 } });零配置与极简配置根据 src/components/core.ts 的实现配置对象是可选的。直接new EditorJS()会使用默认holder元素 ID 为editorjs与默认 Paragraph 工具也可以传入字符串形式的 holder IDvar 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.mdvar editor new EditorJS({ holder: document.querySelector(.editor), // DOM 元素 }); var editor2 new EditorJS({ holder: codex-editor, // 等价于 document.getElementById(codex-editor) });兼容说明旧属性holderId已标记废弃将被holder取代两者不能同时传入core.ts 会抛出校验错误。若holder对应元素不存在初始化也会直接报错。工具装配toolstools是一个以工具名为键的映射值可以是 Tool 类本身或一个配置对象。配置对象中可设置classTool 类inlineToolbar布尔值或工具名数组控制该块的 Inline Toolbarconfig传给 Tool 构造函数的用户配置例如placeholdershortcut为该工具绑定键盘快捷键例如CMDSHIFTH。参考 example.html 的完整示例var editor new EditorJS({ holder: editorjs, readOnly: false, tools: { header: { class: Header, inlineToolbar: [marker, link], config: { placeholder: Header }, shortcut: CMDSHIFTH }, image: SimpleImage, // 也可以直接传类不做任何配置 list: { class: List, inlineToolbar: true, shortcut: CMDSHIFTL }, quote: { class: Quote, inlineToolbar: true, config: { quotePlaceholder: Enter a quote, captionPlaceholder: Quote\s author, }, shortcut: CMDSHIFTO } }, 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回调还可以使用实例的isReadyPromisevar 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 与 logLevelplaceholder默认为空可自定义首块提示语使用自定义初始块时该值会作为config传入 Tool 构造函数docs/usage.md。autofocus页面加载后自动聚焦编辑器autofocus: true。logLevel控制控制台日志输出可选值为VERBOSE全部、INFOinfo 与 debug、WARN仅错误与警告、ERROR仅错误。保存数据Saving Data调用实例的save()方法它会返回一个 Promiseresolve 出保存的 JSON 数据const data await editor.save();也可以使用实例上的saverAPIeditor.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。更多能力与 Roadmap常用键盘操作| 操作 | 快捷键 | 说明 | | -- | -- | -- | | 打开 / 浏览 Toolbox |TAB| 需在空块上 | | 回退浏览 Toolbox |SHIFTTAB| Toolbox 打开时 | | 创建块 |ENTER| Toolbox 打开且已选中工具时 | | 加粗 / 斜体 / 插入链接 |CMDB/CMDI/CMDK| 需有选中文本 |工具级快捷键可在tools配置中通过shortcut声明如CMDSHIFTH。生态与路线图Editor.js 生态还包括editorjs/create-tool工具脚手架、统一的 CodeX Icons 图标体系、新的首页与文档等已落地的能力。从仓库 README.md 的 Roadmap 看当前阶段已完成「统一工具栏」Block Tunes 移入左侧、Toolbox 垂直化、嵌套菜单、分隔线、转换菜单等协作编辑Inline Tools JSON 格式、Operations Observer/Executor/Manager/Transformer、Undo/Redo 管理器等、块拖拽、跨块选择与跨块光标移动等功能仍在规划中。深入阅读指引如果你想继续深入仓库内还有丰富的参考资料docs/installation.md更完整的安装与初始化指南含 CDN、本地文件、isReady用法docs/usage.md基础使用、快捷键、holder / placeholder / autofocus / logLevel 说明docs/tools.mdTool 类结构、内部设置、粘贴处理HTML 标签 / RegExp / 文件、清洗Sanitize与转换Conversion配置docs/block-tunes.md 与 docs/tools-inline.mdBlock Tunes 与 Inline Tools 的扩展机制docs/sanitizer.md 与 docs/api.md数据清洗规则与编辑器 API 说明types/index.d.tsEditorJS 主类、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),仅供参考
返回列表