CKEditor 5 Bookmark 功能详解为富文本内容创建可链接的锚点【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5CKEditor 5 的 Bookmark书签功能允许在编辑器内容中插入、重命名和删除书签锚点并可与 Link 功能联动为长文档提供快速导航与段落级交叉引用。本文基于官方文档packages/ckeditor5-bookmark/docs/features/bookmarks.md与ckeditor5-bookmark包源码完整覆盖安装、配置、锚点标记转换规则、工具栏定制和命令级 API帮助你把内容锚点这一能力落地到实际项目中。功能定位为什么需要内容锚点书签Bookmark是为编辑器内容中的关键位置创建命名锚点的功能。它解决了长文档编辑中的两个实际痛点快速导航给重要章节打上书签如Rights编辑时点击即可定位内容交叉引用通过链接指向书签如#Rights实现参见正文第 X 节这类站内锚点跳转。需要注意在官方文档的元信息中Bookmark 被标记为premiumbadges: [ premium ]功能源码中BookmarkEditing也声明了licenseFeatureCode BKM和isPremiumPlugin: true见 bookmarkediting.ts。使用时需通过licenseKey解锁这是适用前提。核心使用流程点击工具栏的Add bookmark按钮或菜单 Insert → Bookmark弹出表单输入一个唯一且不含空格的名称例如Rights内容中出现带书签图标的 widget点击图标可重命名或删除在Add link面板的 Bookmarks 列表中选择该书签即可插入#Rights形式的目标链接。安装与基本配置在安装编辑器之后将Bookmark加入插件列表、bookmark加入工具栏import { ClassicEditor, Bookmark } from ckeditor5; ClassicEditor .create( { licenseKey: YOUR_LICENSE_KEY, // Or GPL. plugins: [ Bookmark, /* ... */ ], toolbar: [ bookmark, /* ... */ ] } ) .then( /* ... */ ) .catch( /* ... */ );从源码结构看Bookmark是一个聚合插件它通过requires声明依赖 BookmarkEditing模型、命令与转换逻辑、BookmarkUI按钮、表单、气泡面板以及 Widget 插件见 bookmark.ts。包入口 index.ts 同时导出了这两个子插件与BookmarkFormView方便高级定制并在导入时挂载了index-editor.css/index-content.css样式。锚点标记的处理规则数据导入时发生这是使用 Bookmark 最容易踩坑的部分也是文档中Handling the anchor markup一节的核心。空段落中的书签不必担心把书签放在空段落里——带a标签的块在最终内容如打印输出中不会被渲染。HTML 锚点自动转换在编辑器初始化setData阶段或调用setData()替换数据时以下a元素写法都会被转换为bookmark模型元素带id属性、无href的a元素最典型a idfoo/a带name属性、无href的a元素name与id相同或不同的a元素只要没有href。反过来编辑器内创建的书签在getData()输出中只保留id...属性不会输出name。这条规则在源码中由 upcastMatcher 精确实现先确认元素是a且在数据转换管线中为空再按有id且无href→ 取id否则有name且无href→ 取name的优先级匹配。dataViewModelAnchorInsertion 随后创建bookmark模型元素并调用conversionApi.convertChildren()把原锚点内部的子节点转换到书签之后而不是内部——这正是下方包裹式锚点转换的输出原理。此外BookmarkEditing在数据管线注册了 inline object matcher防止书签周围的空格被转换成nbsp;见 bookmarkediting.ts 的注释。配置项详解Bookmark 的配置位于config.bookmark命名空间由 BookmarkConfig 定义共两个可选属性enableNonEmptyAnchorConversion默认true开启时非空的包裹式锚点也会被转换为书签。例如输入a idfooFoo bar baz/a会被转换为a idfoo/aFoo bar baz即锚点变成空元素、内容后移。如需禁用该自动转换在编辑器配置中设为falseClassicEditor .create( { // ... Other configuration options ... bookmark: { enableNonEmptyAnchorConversion: false } } ) .then( /* ... */ ) .catch( /* ... */ );源码印证isEnabledNonEmptyAnchorConversion 显示该选项未定义时按true处理与default true的文档声明一致关闭后dataViewModelAnchorInsertion会在元素非空时直接跳过转换。toolbar默认[bookmarkPreview, |, editBookmark, removeBookmark]控制书签被选中时出现的上下文工具栏中的条目。可用项工具栏项作用bookmarkPreview以标签形式显示书签名称绑定updateBookmark命令的valueeditBookmark打开表单重命名书签removeBookmark删除书签实际执行的是内置delete命令默认值在 BookmarkEditing 构造函数 中通过editor.config.define写入。你可以整体覆盖ClassicEditor .create( { bookmark: { toolbar: [ bookmarkPreview, |, editBookmark, removeBookmark ] } } ) .then( /* ... */ ) .catch( /* ... */ );这些按钮也可以在编辑器主工具栏中使用。上下文工具栏本身的注册发生在 BookmarkUI.afterInit它通过WidgetToolbarRepository注册名为bookmark的 widget 工具栏items直接读取config.bookmark.toolbar。自定义工具栏项通过 ComponentFactory 注册自定义组件即可扩展该工具栏。官方文档给出的示例class MyCustomPlugin extends Plugin { init() { const editor this.editor; editor.ui.componentFactory.add( myCustomBookmarkInfo, locale { const button new ButtonView( locale ); const bookmarkCommand editor.commands.get( insertBookmark ); button.bind( isEnabled ).to( bookmarkCommand, value, href !!href ); button.bind( label ).to( bookmarkCommand, value ); button.on( execute, () { // Add your custom component logic here } ); return button; } ); } }注册后即可在配置中使用ClassicEditor .create( { plugins: [ MyCustomPlugin, /* ... */ ], bookmark: { toolbar: [ myCustomBookmarkInfo, |, editBookmark, removeBookmark ] } } ) .then( /* ... */ ) .catch( /* ... */ );与 Link 功能的集成这是文档中Integration with the link feature一节描述的能力当内容中存在书签时链接插入面板会出现Bookmarks列表展示编辑内容中所有可用的书签选中某一项即把它作为链接目标。若列表为空则显示 No bookmarks available.。该集成由 BookmarkUI._registerLinkProvider 实现仅当编辑器中同时存在LinkUI插件时才会注册见 init 中的条件判断即只有启用 Link 功能时才有 Bookmarks 面板。列表项由BookmarkEditing.getAllBookmarkNames()收集并按localeCompare排序每项的href形如#Rights。选中后执行navigate内部调用 _scrollToBookmark通过getElementForBookmarkId()找到模型元素、把模型选区设到该元素上并scrollToTheSelection实现点击书签链接即滚动定位。书签集合的维护方式BookmarkEditing用一个MapModelElement, string追踪所有书签editing downcast 时写入并监听change:data事件在元素进入$graveyard时清理见 _trackBookmarkElements保证列表始终与文档实际内容一致。命令与常见 APIBookmark插件注册了bookmarkUI 按钮以及两个命令类型声明见 augmentation.tsinsertBookmark由 InsertBookmarkCommand 实现——在当前折叠选区或选区起始处插入书签editor.execute( insertBookmark, { bookmarkId: foo_bar } );执行逻辑值得注意若bookmarkId非法空或含空格只会输出错误码为insert-bookmark-command-executed-with-invalid-name的 warning 并中止不会写入模型若当前位置不允许插入bookmark但允许插入段落会先执行insertParagraph再在段落内插入见 execute所以把书签放进空段落是自动完成的选区在表格单元格等外部选中的场景下命令会遍历范围寻找第一个可容纳书签的块级元素。updateBookmark由 UpdateBookmarkCommand 实现——更新当前选中书签的bookmarkIdeditor.execute( updateBookmark, { bookmarkId: newId } );非法名称会触发update-bookmark-command-executed-with-invalid-namewarning。该命令还暴露了一个可观察的value属性当前选中书签的 IDUI 中的名称预览bookmarkPreview和Insert/Save按钮文案都绑定在它之上。书签 ID 的校验规则isBookmarkIdValid 要求 ID 是非空字符串且不含任何空白字符正则/\s/。表单层面另有三条校验见 getFormValidators名称不能为空、不能含空格、不能与文档中已有书签重名——重名提示为 Bookmark name already exists.这是保证#锚点链接语义正确的关键约束。模型侧bookmark元素在 schema 中继承自$inlineObject唯一允许的属性是bookmarkId见 _defineSchema并显式禁止linkHref与htmlA属性使书签与链接在模型上保持正交。已知限制块级元素上的书签官方文档明确说明当前的行为边界书签挂载到块级元素block上时渲染位置在该块之前且团队计划在未来扩展此方案原文邀请社区参与相关讨论反馈入口为 CKEditor 官方 issue此处不给出外部链接。如果你的内容依赖块后锚点或自动生成 ID需要在产品层面自行评估或改用 Link/文档大纲等替代手段。相关功能对照文档还给出了三个可替代或互补的方案便于按场景选择功能定位Link 功能添加本地/全局 URL 链接可与 Bookmark 组合实现锚点跳转Document Outline在编辑器旁显示文档章节标题列表Table of Contents插入一个反映文档结构标题列表的 widget总结Bookmark 功能的价值在于稳定的内容锚点 原生链接集成 可定制的交互 UI数据层a id|name无href锚点在导入时自动转换为bookmark模型元素输出时统一为a id.../aenableNonEmptyAnchorConversion控制包裹式锚点的自动拆散交互层工具栏按钮、气泡表单、上下文 widget 工具栏bookmarkPreview/editBookmark/removeBookmark均可通过bookmark.toolbar定制或替换为自定义组件集成层启用 Link 后链接面板自动列出全部书签并支持点击滚动定位编程层insertBookmark/updateBookmark命令 严格的 ID 校验非空、无空格、文档内唯一。完整源码位于 packages/ckeditor5-bookmark/测试用例如 bookmarkediting.js 和 bookmarkui.js可作为各条转换与交互规则的可执行验证参考。【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考