Editor.js 使用指南从基础操作到快捷键、Holder 与日志配置【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.jsEditor.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也提供了简单的 APItools.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 上 | |SHIFTTAB| 回翻 Toolbox | Toolbox 打开时 | |ENTER| 创建 Block | Toolbox 打开且选中了某个 Tool 时 | |CMDB| 加粗样式 | 有选中文本时 | |CMDI| 斜体样式 | 有选中文本时 | |CMDK| 插入链接 | 有选中文本时 |TAB 与 Slash/的底层逻辑在 src/components/modules/blockEvents.ts 的tabPressed()中可以看到TAB按下时若 Inline Toolbar 已打开则直接返回避免与 Flipper 冲突否则尝试Caret.navigateNext(true)SHIFTTAB则为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: CMDSHIFTH }, list: { class: List, shortcut: CMDSHIFTL } } //... });快捷键的注册机制位于 src/components/utils/shortcuts.ts其底层基于codexteam/shortcuts库。Tool 侧的实现见 src/components/tools/base.tsshortcutgetter 优先返回用户配置this.config[UserSettings.Shortcut]否则回退到 Tool 类自身声明的内部快捷键CommonInternalSettings.Shortcut。也就是说用户配置永远可以覆盖 Tool 内部默认快捷键。初始化配置项详解Editor.js 的实例化通常形如new EditorJS(config)。除tools、data外官方使用文档重点讲解了以下几个配置项。Autofocus页面加载后自动聚焦如果希望在页面加载完成后自动聚焦到编辑器可在初始配置中传入autofocus: truevar 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 ideditorjs/div因此也存在零配置用法new EditorJS()。此外src/components/core.ts 的validate()方法会在初始化时校验 holder同时传入holderId与holder会抛出错误holderId是已废弃的旧属性将被移除传入的字符串 id 必须在页面中真实存在$.get(holder)找不到即抛错传入的对象必须是 DOM Element 节点。类型定义见 types/configs/editor-config.d.tsholder类型为string | HTMLElement同时标注了旧属性holderId已废弃。Placeholder空编辑器占位提示默认情况下Editor.js 的 placeholder 是空的。可通过placeholder字段传入自定义占位文案var editor new EditorJS({ //... placeholder: My awesome placeholder //... });需要注意的是如果你使用了自定义的Initial Block即defaultBlock见 types/configs/editor-config.d.tsplaceholder属性会通过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.tsERROR级别只放行error类型WARN放行error与warnINFO仅放行常规的info/log类型。生产环境建议设为WARN或ERROR减少控制台噪音。结合初始化与数据保存的完整示例把以上配置组合起来一个完整的 Editor.js 初始化示例大致如下前置条件参见 docs/installation.md更多示例见 example/example.htmldiv ideditorjs/divvar editor new EditorJS({ holder: editorjs, autofocus: true, placeholder: 写点什么…, logLevel: WARN, tools: { header: { class: Header, shortcut: CMDSHIFTH, inlineToolbar: true }, list: { class: List, shortcut: CMDSHIFTL } }, 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），仅供参考