Slate v2 跨块删除能力补齐Op-family 第二十五切片collapsed delete 跨相邻顶级块实现解析【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本指南基于仓库内 docs/plans/2026-04-07-slate-v2-op-family-twenty-fifth-slice.md 这一支撑性开发计划深入讲解 Slate v2 中delete(...)变换如何从「块内删除」扩展到「跨相邻受支持顶级块边界的折叠选区删除」。读者将掌握delete的Point、折叠选区、reverse、distance等参数语义理解mergeNodes与shouldMergeNodes构成的合并缝并能在packages/slate中对照测试用例验证行为。计划背景Op-family 切片方法论在 Slate v2 的重构过程中核心操作族op-family按「最小诚实切片」的方式逐步补齐。每个切片遵循固定的五阶段流程2026-04-07-slate-v2-op-family-first-slice.md 已确立该模式确认确切的缺口与当前代码接缝编写聚焦的失败测试实现最小的诚实核心/API 切片同步包内与公共文档验证所涉及的包与文档。第二十五切片即是在这一方法论下专门针对collapsed折叠delete(...)跨相邻受支持顶级块边界的补齐计划。计划全文仅 29 行属于典型的「支撑性计划」supporting plan其当前队列与路线图真值见 docs/slate-v2/master-roadmap.md。切片目标与范围边界该切片的目标非常聚焦拓宽折叠delete(...)在相邻受支持顶级块边界上的删除能力。范围约束如下仅保留 collapsed-delete 语义不涉及展开expandedRange 的跨块删除支持四种输入形式显式Point、当前折叠选区默认、reverse反向删除、distance删除距离仅支持相邻受支持顶级块之间的跨越本切片要求同类型、同 props 的块合并明确回避多块删除与跨块显式Range删除留待后续切片处理。计划中的五个阶段均已完成全部勾选[x]说明该切片已落地语义确认 → 失败测试 → 实现 → 文档同步 → 验证。对应实现集中在packages/slate包内。delete 变换的公开参数契约实现位于 packages/slate/src/internal/transforms/deleteText.ts其公开选项类型DeleteTextOptions定义在 packages/slate/src/interfaces/editor/editor-transforms.ts#L50-L57export type DeleteTextOptions { distance?: number; hanging?: boolean; reverse?: boolean; unit?: TextUnit; } QueryAt QueryVoids QueryTextUnit;各参数的语义与默认值如下参数默认值作用at来自QueryAteditor.selection删除起点可为Point、Range或Path不传则使用当前选区distance1删除的步数配合unit决定删除长度reversefalse为true时向光标之前反向删除等价于 Backspace否则向前删除等价于 Deleteunitcharacter删除单位取值见QueryTextUnitoffset、character、word、line、blockhangingfalse是否允许选区悬挂到块边界之外用于跨块场景voids来自QueryVoidsfalse为true时允许删除进入 void 节点其中QueryTextUnit在 packages/slate/src/interfaces/editor/editor-api.ts#L763-L785 中有详细文档注释character以 Unicode 字符为单位对 Emoji 等代理对可能按 2 个字符计word在反向模式下移动到前一个单词之前line/block则以整个块为边界。QueryAt的默认值注释为editor.selection见 editor-api.ts#L734-L737。实现剖析deleteText 的折叠删除主流程deleteText的核心流程deleteText.ts可拆解为以下步骤1. 确定at并识别折叠状态let at: any getAt(editor, options?.at) ?? editor.selection;随后若at是Range且isCollapsed则记录isCollapsed true并将at降级为其anchor点。这正是「折叠选区」统一为Point处理的接缝。2. Point 分支构造删除区间当at为Point时先检查其所在的最深 voidconst furthestVoid editor.api.void({ at, mode: highest }); if (!voids furthestVoid) { const [, voidPath] furthestVoid; at voidPath; // 整块删除转为 Path 分支 } else { const target reverse ? editor.api.before(at, opts) || editor.api.start([]) : editor.api.after(at, opts) || editor.api.end([]); at { anchor: at, focus: target }; hanging true; }不越过 void 时voids: false光标落在 void 内会转为整节点删除Path分支调用removeNodes否则用before/after按{ distance, unit }计算目标点构造一个anchor → focus的区间并置hanging true为跨块做准备。3. 跨块判定与合并触发这是本切片的核心语义所在const isAcrossBlocks startBlock endBlock !PathApi.equals(startBlock[1], endBlock[1]); const isSingleText PathApi.equals(start.path, end.path);在完成首尾文本裁剪与中间节点移除后若满足「跨块且非单文本」则触发块合并if (!isSingleText isAcrossBlocks endRef.current startRef.current) { editor.tf.mergeNodes({ at: endRef.current, hanging: true, reverse: !reverse, voids, }); }注意reverse: !reverse向前删除Delete时末尾块的剩余内容需要与前一个兄弟块合并因此合并方向取反。这与测试merges blocks when deleting an expanded cross-block selection的期望输出一致——删除后wo与other留在同一块内光标落在合并点。4. 选择恢复const point reverse ? startUnref || endUnref : endUnref || startUnref; if (options?.at null point) { editor.tf.select(point); }仅当调用方未显式传入at时才将光标恢复到合并后的位置反向删除停在起点正向删除停在终点。合并缝mergeNodes 与 shouldMergeNodes跨块删除最终依赖mergeNodes完成块的粘合实现位于 packages/slate/src/internal/transforms/mergeNodes.ts。其关键约束与本切片「同类型/同 props 合并」的要求一一对应同类型检查Text与Text、Element与Element才能合并否则抛出TypeError} else { throw new TypeError( Cannot merge the node at path [${path}] with the previous sibling because it is not the same kind: ... ); }属性合并对元素节点properties取待合并节点除去children后的其余属性即{ children, ...rest }中的rest合并时通过merge_node操作施加从而天然约束「同 props」——不同 props 的块合并行为由上层策略决定。空祖先清理合并后若某祖先只剩单一子链hasSingleChildNest会识别该空壳祖先并用removeNodes携带event: { type: mergeNodes }移除。合并前的守卫由 packages/slate/src/internal/editor/shouldMergeNodes.ts 提供if ( (ElementApi.isElement(prevNode) editor.api.isEmpty(prevNode)) || (TextApi.isText(prevNode) prevNode.text prevPath.at(-1) ! 0) ) { editor.tf.removeNodes({ at: prevPath }); return false; }即合并目标前一个节点为空时删除它而非合并——这是富文本编辑器防止悬挂选区删除整块时丢失格式的常见行为唯一的例外是父节点的第一个子节点prevPath.at(-1) ! 0避免把父节点清空。测试验证聚焦失败测试到绿切片要求「先写聚焦的失败测试再实现」对应测试文件为 packages/slate/src/internal/transforms/deleteText.spec.tsx。该文件覆盖了本切片范围内的全部关键路径单字符前向删除deletes one character forward from a collapsed text selectionwocursor/rd删除后光标前移验证默认distance: 1与折叠选区语义Path 删除removes the node at a path locationeditor.delete({ at: [1] })直接移除整块跨块展开选区合并merges blocks when deleting an expanded cross-block selectionwoanchor/rdanfocus/other删除后合并为wocursor/other验证isAcrossBlocks合并路径void 与只读 inline 处理前向穿越imginline void、从 void 内部删除、只读mention前向删除时先向后微移nudges backward around a read-only inline泰文脚本re-inserts remaining Thai code points after backward character deletiondelete({ distance: 2, reverse: true, unit: character })按码点而非字形簇删除剩余码点回插——对应实现中THAI_SCRIPT_REGEX /[\u0E00-\u0E7F]/分支文档末尾 no-opno-ops when deleting forward from the end of the documenteditor.api.after(...) || editor.api.end([])的兜底保证边界安全。shouldMergeNodes自身也有独立测试 packages/slate/src/internal/editor/shouldMergeNodes.spec.tsx与 mergeNodes.spec.tsx 一起覆盖合并缝的空节点守卫行为。边界与后续切片本切片刻意回避的两类场景——多块删除与跨块显式Range删除——意味着当前delete在跨块方向上只保证「相邻、同型、折叠」这一最小诚实子集。从deleteText.ts源码结构看isAcrossBlocks分支已为后续扩展预留一旦放开多块支持只需扩展matches收集与mergeNodes的多次调用逻辑而无需改动DeleteTextOptions契约。验证方式沿用包内标准命令参见 master-roadmap.md 中 tranche 3 的落地标准bun test ./packages/slate/test、bunx turbo build --filter./packages/slate、bunx turbo typecheck --filter./packages/slate。对希望深入研读的读者建议按「计划 → 类型定义 → 实现 → 合并缝 → 测试」的顺序阅读本文列出的五个文件即可完整还原第二十五切片的演进轨迹。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考