家电销售分析系统：Django 与大数据组件整合实战
2026/9/19 21:20:17
Editor.js 使用指南：从基础操作到快捷键、Holder 与日志配置
【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js
Editor.js 是一个基于 Block（块）架构的富文本编辑器，输出干净的 JSON 数据。本指南以官方 docs/usage.md 为主线，结合仓库源码（如 src/components/core.ts、src/components/modules/blockEvents.ts）为你系统讲解 Editor.js 的日常使用方式：如何创建与管理 Block、如何用快捷键和 Toolbox 高效操作、以及autofocus、holder、placeholder、logLevel等核心配置项的底层行为。读完本文，你将能熟练上手 Editor.js，并为自己的站点配置出一套顺手、可控的编辑体验。
基础操作：认识 Block 与编辑流程
Editor.js 是 Block-Styled（块式）编辑器：Block 是构成一篇内容（Entry）的结构化单元。例如Paragraph（段落）、Heading（标题）、Image（图片）、Video（视频）、List（列表）都是 Block，而每一个 Block 都由一个**插件（Plugin / Tool）**表示。Editor.js 官方维护了大量开箱即用的 Plugins，也提供了简单的 API（tools.md） 供你创建自己的 Tool。
安装完成后（参考 installation.md），编辑器即可按以下流程使用：
- 创建新 Block：按
Enter键，或点击编辑器左侧的Plus Button（加号按钮）； - 打开 Toolbox（工具箱）：按
TAB键或点击 Plus Button，即可查看可用 Tool 列表； - 选择 Block 类型：再次按
TAB在 Toolbox 中翻阅，高亮到你需要的 Block 后按Enter确认插入。
- 行内工具栏（Inline Toolbar）：选中一段文本后，会弹出行内工具栏，可对其应用加粗、斜体等样式，或插入链接：
- 块设置（Block Settings）：点击块右侧的「三点」按钮（
···）打开 Block Settings，可以移动（上移/下移）、删除Block，或应用 Tool 自身提供的设置项——例如设置标题级别（H2/H3/H4）或列表样式：
从源码看，这三类操作分别由不同的模块承载：Toolbox 由 src/components/ui/toolbox.ts 实现并通过 src/components/modules/toolbar/index.ts 对外暴露；移动/删除 Block 的 Tune 定义在 src/components/block-tunes/ 下的block-tune-move-up.ts、block-tune-move-down.ts与block-tune-delete.ts。
快捷键一览
Editor.js 非常重视键盘操作，内置了少量预设快捷键：
| 动作 | 快捷键 | 限制条件 | | -- | -- | -- | |TAB| 显示 / 翻阅 Toolbox | 空 Block 上 | |SHIFT+TAB| 回翻 Toolbox | Toolbox 打开时 | |ENTER| 创建 Block | Toolbox 打开且选中了某个 Tool 时 | |CMD+B| 加粗样式 | 有选中文本时 | |CMD+I| 斜体样式 | 有选中文本时 | |CMD+K| 插入链接 | 有选中文本时 |
TAB 与 Slash（/）的底层逻辑
在 src/components/modules/blockEvents.ts 的tabPressed()中可以看到：TAB按下时，若 Inline Toolbar 已打开则直接返回（避免与 Flipper 冲突）；否则尝试Caret.navigateNext(true)（SHIFT+TAB则为navigatePrevious(true)）在 Block 间移动焦点。
同一文件中slashPressed()（src/components/modules/blockEvents.ts）则揭示了当前仓库中另一个实用操作：在空 Block 中输入/会直接打开 Toolbox——前提是当前 Block 为空（currentBlock.isEmpty），并且/会被插入到搜索框中。这是文档之外、源码可验证的隐藏用法。
为 Tool 自定义快捷键
除了内置快捷键，所有类型的 Tool 都支持自定义快捷键：在 Tool 的配置中指定shortcut即可。例如：
var editor = new EditorJS({ //... tools: { header: { class: Header, shortcut: 'CMD+SHIFT+H' }, list: { class: List, shortcut: 'CMD+SHIFT+L' } } //... });快捷键的注册机制位于 src/components/utils/shortcuts.ts，其底层基于@codexteam/shortcuts库。Tool 侧的实现见 src/components/tools/base.ts：shortcutgetter 优先返回用户配置this.config[UserSettings.Shortcut]，否则回退到 Tool 类自身声明的内部快捷键（CommonInternalSettings.Shortcut）。也就是说，用户配置永远可以覆盖 Tool 内部默认快捷键。
初始化配置项详解
Editor.js 的实例化通常形如new EditorJS(config)。除tools、data外，官方使用文档重点讲解了以下几个配置项。
Autofocus：页面加载后自动聚焦
如果希望在页面加载完成后自动聚焦到编辑器，可在初始配置中传入autofocus: true：
var editor = new EditorJS({ //... autofocus: true //... });从 src/components/core.ts 的源码可以看到其实现细节：当autofocus === true且未开启只读模式（readOnly !== true）时，核心会在渲染完成后把光标（Caret）设置到第一个 Block 的开头（Caret.setToBlock(BlockManager.blocks[0], Caret.positions.START)）。换言之，autofocus在readOnly: true时不会生效。
Holder：编辑器挂载点
holder属性同时支持元素 id 字符串或DOM 元素引用两种写法：
var editor = new EditorJS({ holder: document.querySelector('.editor'), }) var editor2 = new EditorJS({ holder: 'codex-editor' // 等价于 document.getElementById('codex-editor') })holder是 Editor.js 唯一必需的配置项（至少需要指定一个挂载容器）。src/components/core.ts 显示：若完全不传holder，默认值会是'editorjs'（对应页面中<div id="editorjs"></div>），因此也存在零配置用法new EditorJS()。
此外，src/components/core.ts 的validate()方法会在初始化时校验 holder：
- 同时传入
holderId与holder会抛出错误（holderId是已废弃的旧属性，将被移除）； - 传入的字符串 id 必须在页面中真实存在（
$.get(holder)找不到即抛错）； - 传入的对象必须是 DOM Element 节点。
类型定义见 types/configs/editor-config.d.ts：holder类型为string | HTMLElement，同时标注了旧属性holderId已废弃。
Placeholder：空编辑器占位提示
默认情况下，Editor.js 的 placeholder 是空的。可通过placeholder字段传入自定义占位文案：
var editor = new EditorJS({ //... placeholder: 'My awesome placeholder' //... });需要注意的是：如果你使用了自定义的Initial Block（即defaultBlock，见 types/configs/editor-config.d.ts），placeholder属性会通过config传入该 Tool 的构造函数，由 Tool 决定如何使用。占位符的实际渲染依赖data-placeholder等属性配合 CSS（见 src/styles/placeholders.css 与 src/components/modules/ui.ts 中关于 contenteditable 占位逻辑的注释）。
从 src/components/core.ts 还可看到其默认值处理：this.config.placeholder = this.config.placeholder || false，即未配置时等价于false（不显示占位提示）。类型定义允许string | false，意味着你可以用false显式关闭占位提示。
Log level：控制控制台日志量
可以通过配置对象的logLevel属性指定 Editor.js 控制台消息的输出级别：
var editor = new EditorJS({ //... logLevel: 'WARN' //.. })可选值如下：
| 值 | 描述 |
|---|---|
VERBOSE | 显示所有消息 |
INFO | 显示 info 与 debug 消息 |
WARN | 仅显示错误与警告 |
ERROR | 仅显示错误 |
logLevel的取值由 types/configs/log-levels.d.ts 中的LogLevels枚举定义（VERBOSE/INFO/WARN/ERROR）。其默认值为VERBOSE（见 src/components/core.ts，未配置时自动设为VERBOSE并调用setLogLevel）。
实际的过滤逻辑在 src/components/utils.ts：ERROR级别只放行error类型；WARN放行error与warn；INFO仅放行常规的info/log类型。生产环境建议设为WARN或ERROR，减少控制台噪音。
结合初始化与数据保存的完整示例
把以上配置组合起来，一个完整的 Editor.js 初始化示例大致如下（前置条件参见 docs/installation.md，更多示例见 example/example.html）：
<div id="editorjs"></div>var editor = new EditorJS({ holder: 'editorjs', autofocus: true, placeholder: '写点什么…', logLevel: 'WARN', tools: { header: { class: Header, shortcut: 'CMD+SHIFT+H', inlineToolbar: true }, list: { class: List, shortcut: 'CMD+SHIFT+L' } }, onReady: () => { console.log('Editor.js is ready to work!'); }, onChange: (api, event) => { console.log('Now I know that Editor\'s content changed!'); } }); // 保存数据 editor.saver.save() .then((savedData) => { console.log(savedData); // 干净的 JSON OutputData });其中onReady回调与isReadyPromise 用于感知初始化完成时机，saver.save()输出结构化 JSON——这些都属于 docs/installation.md 覆盖的能力，与本文的配置项配合使用可构成完整的「初始化 → 编辑 → 保存」闭环。
小结
Editor.js 的使用体验可以概括为三件事：用 Enter / Plus 按钮创建 Block，用 Tab 翻阅 Toolbox 并选择类型，用 Inline Toolbar 与 Block Settings 做样式与结构调整。在此基础上，通过shortcut为常用 Tool 绑定快捷键、用autofocus提升进入页面的效率、用holder灵活挂载到任意 DOM、用placeholder引导用户输入、用logLevel控制日志噪音，即可把编辑器深度融入自己的站点。所有配置项的默认值与约束（如 holder 默认'editorjs'、logLevel 默认VERBOSE、autofocus 在只读模式下不生效）都能在 src/components/core.ts 的 configuration setter 与validate()中直接验证。
【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考