WordPress 块编辑器 Notes协作侧边栏架构深度解析从线程数据模型到浮动定位引擎【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergNotes 侧边栏又名 collab sidebar是 Gutenberg 块编辑器内置的协作批注功能用户可以为单个块附加带回复的评论线程并在画布中以全部笔记面板或浮动气泡两种形态浏览与处理。本文以 packages/editor/src/components/collab-sidebar/README.md 为核心骨架结合该目录下的 index.jsx、board-store.js、hooks.js、utils.js 等实现源码展开讲解。读完你将对 Notes 的数据模型WordPress 评论 metadata.noteId、组件分层、以及不重新渲染线程也能实时跟随滚动的浮动定位引擎Floating Board有源码级的完整认知。功能概览与两种渲染形态Notes 侧边栏允许用户在单个块上挂载带回复的评论线程threaded notes并支持将线程标记为已解决resolved或重新打开reopened。它有两种渲染形态All notes全部笔记从编辑器 More 菜单打开的完整侧边栏列出当前文章上的所有笔记线程。在 index.jsx 中通过PluginSidebaridentifier 为ALL_NOTES_SIDEBAR渲染标题为 All notes图标为评论图标。Floating notes浮动笔记在较大视口useViewportMatch( medium )见 index.jsx下未解决的笔记会以浮动卡片的形式悬浮在画布中对应块的旁边自动跟踪滚动并避免与相邻线程重叠。对应 index.jsx 中的FLOATING_NOTES_SIDEBAR侧边栏。两个形态复用同一个Notes组件唯一的视觉差异由isFloating布尔值驱动浮动态将线程叠加在画布上面板态则纵向堆叠在线程列表中。数据模型评论 metadata.noteId笔记以WordPress 评论commentstype: note形式存储在文章下一个线程有一个顶层笔记parent 0加若干回复replyparent指向顶层笔记 id。块通过其块属性的metadata.noteId可同时持有多个 id 的数组引用对应的笔记线程。线程状态未解决存为status: hold已解决存为status: approved解决后也可重新打开为hold。数据读取由 hooks.js 中的useNoteThreads( postId )完成它用useEntityRecords( root, comment, { post, type: note, status: all, per_page: -1 } )拉取全部笔记再结合 block-editor 的getClientIdsWithDescendants()和getBlockAttributes()构建块 → 笔记 id的正向映射与笔记 id → 块 clientId的反向映射最终组装出线程树并区分notes全部与unresolvedNotes未解决。值得注意的是对孤儿笔记orphans的处理如果某个顶层笔记对应的块已被删除它仍会保留在活跃笔记区未解决列表上方因为其可能仍需处理——这一点在 hooks.js 中有明确注释。组件分层与文件结构文档给出了完整的目录树结合源码可归纳为四个层次collab-sidebar/ ├── README.md 本文档 ├── index.jsx 入口NotesSidebarContainer → NotesSidebar含工具栏 slot fill ├── notes.jsx Notes协调器外层 Stack、aria-label、actions、键盘导航 ├── note-thread.jsx NoteThread单线程选中态、浮动注册、回复表单 ├── note.jsx Note单卡片状态编辑/删除模式、菜单、确认对话框 ├── note-card.jsx NoteCard纯展示外壳署名 actions 槽 children ├── note-byline.jsx NoteByline头像 名字 相对时间 ├── note-form.jsx NoteForm富文本输入 提交/取消 ├── add-note.jsx AddNote新建笔记界面浮动 模板锁定两种情况 ├── add-note-menu-item.jsx AddNoteMenuItem块工具栏Add note触发器 ├── note-indicator-toolbar.jsx NoteAvatarIndicator工具栏参与者头像 ├── floating-container.jsx FloatingContainer浮动模式应用 top 的 Stack 包装 ├── hooks.js useNoteThreads / useNoteActions / useFloatingBoard / useEnableFloatingSidebar ├── utils.js 纯函数工具集定位、摘录、格式化、元数据操作等 ├── board-store.js createBoardStoreResizeObserver ref 注册表驱动浮动布局 ├── constants.js 侧边栏标识字符串 ├── style.scss └── test/ └── utils.js入口与能力门控index.jsx 中的NotesSidebarContainer负责门控无postId非数字时不渲染代码编辑器模式editorMode text与修订模式revisionsMode下隐藏使用PostTypeSupportCheck supportKeyseditor.notes做文章类型支持检查index.jsx——即只有声明支持editor.notes特性的文章类型才会启用 Notes。NotesSidebar本身还处理当前选中块的metadata.noteId读取与笔记选择状态同步**免打扰模式distraction free**下只渲染AddNoteMenuItem不渲染侧边栏index.jsx快捷键core/editor/new-noteShiftAltC之类注册到 keyboard-shortcuts store从块工具栏触发新建笔记在经典块core/freeform上禁用index.jsx。Notes两种界面的共享协调器notes.jsx 是核心协调组件负责调用useNoteActions()取得增删改动作调用useFloatingBoard()取得浮动定位结果维护外键状态当前选中块、选中笔记、noteFocused焦点标记无线程或selectedNote new时渲染AddNote新建表单在All notes视图中通过查找第一个status approved且块仍存在的线程索引在其上方渲染Resolved 分隔符notes.jsx浮动视图只列未解决笔记无需分隔符用roletree 各线程roletreeitem组织无障碍语义并提供方向键键盘导航Enter/ArrowRight 展开Enter/ArrowLeft/Escape 折叠ArrowUp/ArrowDown 上下移动Home/End 跳转首尾见 notes.jsx。单线程与单卡片NoteThreadnote-thread.jsx挂载时调用registerThread( note.id, relatedBlockElement, floatingEl )向浮动板注册块与浮动节点note-thread.jsx卸载时反注册选中时滚动到视口鼠标悬停/聚焦时通过 50ms 防抖调用toggleBlockHighlight高亮关联块回复折叠显示 X more replies 与最后一条回复。当顶层块已删除时展示 Original block deleted. 提示。Notenote.jsx维护每张卡片的编辑/删除模式状态与菜单Edit / Reopen / Delete其中Reopen 只对已解决线程status approved显示、Edit 对已解决线程隐藏删除顶层笔记会连带删除其全部回复确认对话框文案明确说明内容超限时用scrollHeight clientHeight实测决定是否显示 Show more / Show less 折叠按钮解决/重开状态通过meta._wp_note_statusresolved/reopen展示 Marked as resolved/Reopened 徽标文本。NoteFormnote-form.jsx富文本表单限定格式白名单[core/bold, core/italic, core/link, core/code]支持用户提及补全Cmd/CtrlEnter提交、Escape取消提交失败时保持草稿不丢失。线程的增删改useNoteActions 的动作管线hooks.js 的useNoteActions()封装了全部笔记动作均通过wordpress/core-data的saveEntityRecord/deleteEntityRecord与评论 REST 接口交互onCreate新建/回复先在异步保存前捕获目标块与内联选区防止请求往返期间选区漂移导致笔记挂到错误块上然后以status: hold、type: note保存记录。顶层笔记创建成功后用addNoteIdToMetadata把返回的笔记 id 写回块的metadata.noteId若存在内联选区还会用wrapInlineNote把选中文本包上core/note富文本标记marker。源码注释特别指出并发编辑下metadata.noteId的读-改-写存在竞态两个同时添加的请求可能各自写出双元素数组导致后者覆盖前者对应 GitHub issue #74751。onEdit编辑/解决/重开解决或重开时会先更新线程状态再以相同parent创建一条携带meta._wp_note_statusresolved/reopen的新评论作为状态变更记录解决时还会调用clearInlineNoteMarker清除内容中的内联高亮标记让笔记退化为块级笔记。对纯文本编辑则直接saveEntityRecord更新 content/status。onDelete删除同样在异步删除前捕获目标块成功后从metadata.noteId中移除该 idremoveNoteIdFromMetadata并剥离内联 markerremoveNoteFormat两步合并在同一次updateBlockAttributes中以保持撤销栈为单步。内联笔记的锚点与高亮机制笔记分为块级笔记无内联锚点作用于整块与内联笔记作用于块内容中的一段文本。内联笔记通过富文本core/note格式序列化为mark classwp-note contenteditable="false">【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WordPress 块编辑器 Notes（协作侧边栏）架构深度解析：从线程数据模型到浮动定位引擎
WordPress 块编辑器 Notes协作侧边栏架构深度解析从线程数据模型到浮动定位引擎【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergNotes 侧边栏又名 collab sidebar是 Gutenberg 块编辑器内置的协作批注功能用户可以为单个块附加带回复的评论线程并在画布中以全部笔记面板或浮动气泡两种形态浏览与处理。本文以 packages/editor/src/components/collab-sidebar/README.md 为核心骨架结合该目录下的 index.jsx、board-store.js、hooks.js、utils.js 等实现源码展开讲解。读完你将对 Notes 的数据模型WordPress 评论 metadata.noteId、组件分层、以及不重新渲染线程也能实时跟随滚动的浮动定位引擎Floating Board有源码级的完整认知。功能概览与两种渲染形态Notes 侧边栏允许用户在单个块上挂载带回复的评论线程threaded notes并支持将线程标记为已解决resolved或重新打开reopened。它有两种渲染形态All notes全部笔记从编辑器 More 菜单打开的完整侧边栏列出当前文章上的所有笔记线程。在 index.jsx 中通过PluginSidebaridentifier 为ALL_NOTES_SIDEBAR渲染标题为 All notes图标为评论图标。Floating notes浮动笔记在较大视口useViewportMatch( medium )见 index.jsx下未解决的笔记会以浮动卡片的形式悬浮在画布中对应块的旁边自动跟踪滚动并避免与相邻线程重叠。对应 index.jsx 中的FLOATING_NOTES_SIDEBAR侧边栏。两个形态复用同一个Notes组件唯一的视觉差异由isFloating布尔值驱动浮动态将线程叠加在画布上面板态则纵向堆叠在线程列表中。数据模型评论 metadata.noteId笔记以WordPress 评论commentstype: note形式存储在文章下一个线程有一个顶层笔记parent 0加若干回复replyparent指向顶层笔记 id。块通过其块属性的metadata.noteId可同时持有多个 id 的数组引用对应的笔记线程。线程状态未解决存为status: hold已解决存为status: approved解决后也可重新打开为hold。数据读取由 hooks.js 中的useNoteThreads( postId )完成它用useEntityRecords( root, comment, { post, type: note, status: all, per_page: -1 } )拉取全部笔记再结合 block-editor 的getClientIdsWithDescendants()和getBlockAttributes()构建块 → 笔记 id的正向映射与笔记 id → 块 clientId的反向映射最终组装出线程树并区分notes全部与unresolvedNotes未解决。值得注意的是对孤儿笔记orphans的处理如果某个顶层笔记对应的块已被删除它仍会保留在活跃笔记区未解决列表上方因为其可能仍需处理——这一点在 hooks.js 中有明确注释。组件分层与文件结构文档给出了完整的目录树结合源码可归纳为四个层次collab-sidebar/ ├── README.md 本文档 ├── index.jsx 入口NotesSidebarContainer → NotesSidebar含工具栏 slot fill ├── notes.jsx Notes协调器外层 Stack、aria-label、actions、键盘导航 ├── note-thread.jsx NoteThread单线程选中态、浮动注册、回复表单 ├── note.jsx Note单卡片状态编辑/删除模式、菜单、确认对话框 ├── note-card.jsx NoteCard纯展示外壳署名 actions 槽 children ├── note-byline.jsx NoteByline头像 名字 相对时间 ├── note-form.jsx NoteForm富文本输入 提交/取消 ├── add-note.jsx AddNote新建笔记界面浮动 模板锁定两种情况 ├── add-note-menu-item.jsx AddNoteMenuItem块工具栏Add note触发器 ├── note-indicator-toolbar.jsx NoteAvatarIndicator工具栏参与者头像 ├── floating-container.jsx FloatingContainer浮动模式应用 top 的 Stack 包装 ├── hooks.js useNoteThreads / useNoteActions / useFloatingBoard / useEnableFloatingSidebar ├── utils.js 纯函数工具集定位、摘录、格式化、元数据操作等 ├── board-store.js createBoardStoreResizeObserver ref 注册表驱动浮动布局 ├── constants.js 侧边栏标识字符串 ├── style.scss └── test/ └── utils.js入口与能力门控index.jsx 中的NotesSidebarContainer负责门控无postId非数字时不渲染代码编辑器模式editorMode text与修订模式revisionsMode下隐藏使用PostTypeSupportCheck supportKeyseditor.notes做文章类型支持检查index.jsx——即只有声明支持editor.notes特性的文章类型才会启用 Notes。NotesSidebar本身还处理当前选中块的metadata.noteId读取与笔记选择状态同步**免打扰模式distraction free**下只渲染AddNoteMenuItem不渲染侧边栏index.jsx快捷键core/editor/new-noteShiftAltC之类注册到 keyboard-shortcuts store从块工具栏触发新建笔记在经典块core/freeform上禁用index.jsx。Notes两种界面的共享协调器notes.jsx 是核心协调组件负责调用useNoteActions()取得增删改动作调用useFloatingBoard()取得浮动定位结果维护外键状态当前选中块、选中笔记、noteFocused焦点标记无线程或selectedNote new时渲染AddNote新建表单在All notes视图中通过查找第一个status approved且块仍存在的线程索引在其上方渲染Resolved 分隔符notes.jsx浮动视图只列未解决笔记无需分隔符用roletree 各线程roletreeitem组织无障碍语义并提供方向键键盘导航Enter/ArrowRight 展开Enter/ArrowLeft/Escape 折叠ArrowUp/ArrowDown 上下移动Home/End 跳转首尾见 notes.jsx。单线程与单卡片NoteThreadnote-thread.jsx挂载时调用registerThread( note.id, relatedBlockElement, floatingEl )向浮动板注册块与浮动节点note-thread.jsx卸载时反注册选中时滚动到视口鼠标悬停/聚焦时通过 50ms 防抖调用toggleBlockHighlight高亮关联块回复折叠显示 X more replies 与最后一条回复。当顶层块已删除时展示 Original block deleted. 提示。Notenote.jsx维护每张卡片的编辑/删除模式状态与菜单Edit / Reopen / Delete其中Reopen 只对已解决线程status approved显示、Edit 对已解决线程隐藏删除顶层笔记会连带删除其全部回复确认对话框文案明确说明内容超限时用scrollHeight clientHeight实测决定是否显示 Show more / Show less 折叠按钮解决/重开状态通过meta._wp_note_statusresolved/reopen展示 Marked as resolved/Reopened 徽标文本。NoteFormnote-form.jsx富文本表单限定格式白名单[core/bold, core/italic, core/link, core/code]支持用户提及补全Cmd/CtrlEnter提交、Escape取消提交失败时保持草稿不丢失。线程的增删改useNoteActions 的动作管线hooks.js 的useNoteActions()封装了全部笔记动作均通过wordpress/core-data的saveEntityRecord/deleteEntityRecord与评论 REST 接口交互onCreate新建/回复先在异步保存前捕获目标块与内联选区防止请求往返期间选区漂移导致笔记挂到错误块上然后以status: hold、type: note保存记录。顶层笔记创建成功后用addNoteIdToMetadata把返回的笔记 id 写回块的metadata.noteId若存在内联选区还会用wrapInlineNote把选中文本包上core/note富文本标记marker。源码注释特别指出并发编辑下metadata.noteId的读-改-写存在竞态两个同时添加的请求可能各自写出双元素数组导致后者覆盖前者对应 GitHub issue #74751。onEdit编辑/解决/重开解决或重开时会先更新线程状态再以相同parent创建一条携带meta._wp_note_statusresolved/reopen的新评论作为状态变更记录解决时还会调用clearInlineNoteMarker清除内容中的内联高亮标记让笔记退化为块级笔记。对纯文本编辑则直接saveEntityRecord更新 content/status。onDelete删除同样在异步删除前捕获目标块成功后从metadata.noteId中移除该 idremoveNoteIdFromMetadata并剥离内联 markerremoveNoteFormat两步合并在同一次updateBlockAttributes中以保持撤销栈为单步。内联笔记的锚点与高亮机制笔记分为块级笔记无内联锚点作用于整块与内联笔记作用于块内容中的一段文本。内联笔记通过富文本core/note格式序列化为mark classwp-note contenteditable="false">【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考