Outline 编辑器的 ProseMirror 命令层：shared/editor/commands 源码级实战解析

Outline 编辑器的 ProseMirror 命令层shared/editor/commands 源码级实战解析【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline本文以 Outline 知识库项目中 shared/editor/commands/README.md 对命令Command模式的核心定义为主线结合该目录下近二十个命令实现的真实源码讲解 Outline 是如何在 ProseMirror 之上构建一层可复用、可组合、可测试的编辑行为库的。读完后你将能够理解 ProseMirror Command 的函数契约state / dispatch / view 三参数与布尔返回值、掌握 Outline 中文本选区与节点选区双路径命令的编写范式并能参照源码为协作编辑器添加自定义编辑行为。一、Command 的定义与契约README 中的核心约定shared/editor/commands/README.md 全文只交代了两件事但它们是整个目录的设计契约命令是封装单个编辑动作的构建块函数。一个命令函数接收编辑器状态EditorState、一个可选的dispatch函数用于提交事务、以及一个可选的EditorView实例函数应返回一个布尔值指示它是否实际执行了动作。该目录存放的是 prosemirror-commands 官方包未包含、但经常被复用的命令即 Outline 编辑器自己的行为扩展库。用 TypeScript 类型语言表达这个契约对应prosemirror-state中的Command类型签名如下type Command ( state: EditorState, dispatch?: (tr: Transaction) void, view?: EditorView ) boolean;从源码结构看这一契约在目录内所有实现中被严格遵循并衍生出三条工程惯例dispatch是可选的ProseMirror 允许在不传dispatch的情况下调用命令仅用于探测该命令当前是否可用例如菜单项的灰显/启用判断。因此凡是有副作用的操作都必须用dispatch?.(...)守卫。目录内的 comment.ts 中甚至有注释专门强调这一点Commands are also invoked withoutdispatchpurely to check whether they are available, so all side effects must be guarded behind it.返回false表示我不处理交给下一个命令这是命令链chainCommands/chainTransactions能工作的基础。返回true表示我处理了即使实际什么都没改如 clearNodes.ts 在!dispatch时直接返回true仅用于探测可用性。二、命令库全景文件与职责一览shared/editor/commands/目录下的实现按编辑领域组织配合三个单元测试文件codeFence.test.ts、table.test.ts、toggleList.test.ts覆盖了核心路径文件核心命令职责addMark.tsaddMark在选区上叠加一个 Mark内联格式collapseSelection.tscollapseSelection将选区折叠为起点光标toggleMark.tstoggleMark切换 Mark支持光标在词中智能扩词toggleBlockType.tstoggleBlockType在两种块类型间切换如标题↔段落backspaceToParagraph.tsbackspaceToParagraph块首按退格时降级为段落deleteEmptyFirstParagraph.tsdeleteEmptyFirstParagraph删除文档开头空段落clearNodes.tsclearNodes清除选区内节点的内联/块级格式toggleWrap.tstoggleWrap包裹/解包容器节点如引用块toggleList.tstoggleList列表的包裹、提升、类型互转toggleCheckboxItems.tstoggleCheckboxItems勾选/取消勾选清单项支持批量selectAll.tsselectAll选中某类节点如代码块的全部内容link.tstoggleLink等 5 个链接的增删改开文本/节点双路径comment.tsaddComment、addDraftCommentAnchor评论锚点的创建与草稿锚定codeFence.tsenterInCode等 7 个代码块内的换行、缩进、进出、拆分insertFiles.tsinsertFiles文件/图片/视频拖入后的占位符异步上传table.tscreateTable、sortTable等 20 个表格的创建、增删行列、排序、导出toggleBlock.tstoggleBlock、indentBlock等 15 个折叠块Toggle的折叠/缩进/拆分/退出三、最小完整示例addMark 与 collapseSelection理解命令契约最快的方式是最小实现。addMark.ts 是目录中最短的文件之一完整体现了高阶工厂函数返回 Command的惯用写法export const addMark (type: MarkType, attrs?: Attrs | null): Command (state, dispatch) { dispatch?.( state.tr.addMark( state.selection.from, state.selection.to, type.create(attrs) ) ); return true; };注意它没有直接导出命令而是导出一个工厂函数先接收MarkType与属性再返回真正的Command。这样同一份逻辑可以复用于加粗、斜体、行内代码等所有 Mark 类型——这正是 README 所说building block functions的含义。collapseSelection.ts 则展示了另一类命令不修改文档内容只调整选区export const collapseSelection (): Command (state, dispatch) { dispatch?.( state.tr.setSelection( TextSelection.create(state.doc, state.tr.selection.from) ) ); return true; };它把当前选区折叠到起点位置的光标在 comment.ts 中作为添加评论后收拢选区的收尾步骤使用。四、块级命令类型切换、退格降级与格式清除toggleBlockType两种块类型之间的切换toggleBlockType.ts 只有十几行演示了探测是否激活 分派的标准套路export default function toggleBlockType( type: NodeType, toggleType: NodeType, attrs {} ): Command { return (state, dispatch) { const isActive isNodeActive(type, attrs)(state); if (isActive) { return setBlockType(toggleType)(state, dispatch); } return setBlockType(type, attrs)(state, dispatch); }; }当前块已是目标类型时切换回对照类型例如h1↔paragraph否则设为目标类型。内部直接复用官方prosemirror-commands的setBlockTypeOutline 只在其外面包了一层双向语义。backspaceToParagraph块首退格降级为段落backspaceToParagraph.ts 是典型的带view参数的命令README 签名中的第三个参数在这里用上了。它依次做四道守卫选区非空!empty→ 走标准删除行为返回false光标所在父节点不是指定类型如heading→false借助view?.endOfTextblock(backward, state)确认光标在块首 → 否则false通过state.tr.setBlockType(from, to, paragraph)把整个块改写为段落并scrollIntoView()。deleteEmptyFirstParagraph清理空壳文档deleteEmptyFirstParagraph.ts 处理新建文档只有一个空段落的场景仅当当前处于段落节点、光标恰在文档位置1、且该段落textContent为空且无子节点时才执行tr.delete(from - 1, from)删除段落节点本身。四个条件层层收窄保证命令绝不会误删有内容的块。clearNodes把选区洗回纯文本块clearNodes.ts 承担清除格式角色。它遍历每个选区片段selection.ranges对片段内所有非文本节点若是文本块isTextblock用setNodeMarkup把块类型替换为父容器内容匹配所允许的类型通常是段落再用prosemirror-transform的liftTarget计算提升深度调用tr.lift剥掉多余的包装容器。注意它开头if (!dispatch) return true;——探测模式下直接报可用符合 README 中返回布尔值指示能否执行动作的契约。五、Mark 切换命令光标在词中时自动扩词toggleMark.ts 在官方toggleMark之上加了一个实用增强值得逐段看findWordRangeAtCursor当选区是空光标且位于词中间光标两侧都是[\p{L}\p{N}_]词字符时向左右扩展得到整个词的文档位置区间。光标停在词首/词尾时返回null因为此时用户意图不明确可能想影响前词也可能想影响后词。rangeHasMarkWithAttrs判断词范围内是否已存在属性匹配的该类型 Mark。主流程因此有三档行为词中光标 → 对整个词removeMark后按需重新addMark不改用户选区选区已有完全匹配属性的 Mark → 走官方pmToggleMark移除选区有同类型但属性不同的 Mark例如换颜色→ 用chainTransactions(pmToggleMark(type), pmToggleMark(type, attrs))先移除再按新属性加上。六、列表与清单命令toggleList包裹、提升与原地类型转换toggleList.ts 是目录中逻辑最完整的块级命令之一接收listType、itemType与可选listStyle三个参数按以下优先级决策若选区已在同类型列表中调用官方liftListItem(itemType)把项提升即取消列表若是列表类型互转注释里明确to or from a checklist这条路径优先调用私有的convertListType做递归原地转换——它逐个遍历列表项与嵌套子列表用createChecked重建节点保留嵌套结构与checked状态。之所以不直接清空再包裹是因为clearNodeswrapInList会抹平嵌套原地转换抛错时回退到chainTransactions(clearNodes(), wrapInList(...))兜底不在列表中时先探测wrapInList(listType, attrs)(state)是否可行可行则直接包裹不可行则同样走清除格式后包裹的组合路径。该命令有专门的回归测试 toggleList.test.ts。toggleCheckboxItems单选与批量勾选toggleCheckboxItems.ts 区分两种选区批量选区!empty用nodesBetween收集范围内所有清单项命中项返回false阻止递归深入采用任一已勾选则全部取消否则全部勾选的策略并从后往前setNodeMarkup以保证位置偏移不被前序修改破坏单光标通过findParentNode找到所属清单项仅翻转其checked属性。七、代码块命令组codeFence.ts 的七个命令codeFence.ts 是围绕一个编辑场景组织多个命令的范本导出moveToPreviousNewline、moveToNextNewline、newlineInCode、indentInCode、outdentInCode、enterInCode、splitCodeBlockOnTripleBackticks七个命令全部以isInCode查询函数作为第一道守卫不在代码内一律返回false并有配套测试 codeFence.test.ts。几个关键设计点换行对齐newlineInCode会取光标前文本按行拆分用search(/\S|$/)算出前导空白宽度在新行插入等量空格——标准代码编辑器的缩进对齐行为智能 Tab 宽度模块底部的getTabSize依次按三层规则定标languagesWithFourSpaceIndent白名单如 Python 类语言→ 4 空格否则扫描块内所有缩进行仅当每个缩进行都是 4 的整数倍才判为 4 空格注释解释了为何不能用简单的includes( )判断——两空格代码在深层嵌套处会天然出现连续四空格导致 outdent 多删默认 2 空格多行缩进/反缩进indentInCode在选区内每个换行前插入 tab 宽度的空格并按插入量平移选区outdentInCode则从后向前逐行删除行首空格注释指出删除发生在index及之后靠前位置永不移动因此无需偏移补偿最后对选区两端做回移并Math.max钳位防止下溢退出代码块enterInCode检测到光标在代码块末尾且末尾已有换行时转调官方exitCode否则退化为newlineInCode三反引号拆分splitCodeBlockOnTripleBackticks在块内键入第三个反引号时删除刚键入的三个反引号并tr.split拆出新块。八、链接命令文本选区与节点选区的双路径范式link.ts 是整个目录中双路径模式最完整的教学样本。Outline 的编辑器里链接既可以作用于内联文本TextSelection也可以作用于被整体选中的块级节点NodeSelection节点通过marks属性携带内联标记。于是每个链接操作都实现成文本版 节点版两个命令再用chainCommands串起来export const toggleLink (attrs: Attrs): Command chainCommands(toggleLinkTextSelection(attrs), toggleLinkNodeSelection(attrs)); export const addLink (attrs: Attrs): Command chainCommands(addLinkTextSelection(attrs), addLinkNodeSelection(attrs)); export const openLink (onClickLink, onNotice?): Command chainCommands(openLinkTextSelection(onClickLink, onNotice), openLinkNodeSelection(onClickLink, onNotice));updateLink与removeLink同样成对实现共导出五个复合命令。细节上还有两个值得注意的做法URL 净化打开链接前统一过sanitizeUrl来自 shared/utils不可处理的协议会触发onNotice报错提示that type of link is not supported修改后迁移选区updateLinkTextSelection/removeLinkTextSelection在修改 Mark 后用Selection.findFrom(doc.resolve(range.to), 1, true)把光标推到链接之外避免光标停在正在被改写的标记内部。节点路径则通过tr.setNodeAttribute(pos, marks, updatedMarks)直接增删节点属性里的link标记对象结构为{ type: link, attrs }与文本路径的addMark/removeMark各司其职。九、评论锚点命令文档不改锚点先行comment.ts 承载 Outline 行内评论的两种入口且都严格区分了可编辑用户与仅可评论用户addComment(attrs)chainCommands(addCommentTextSelection, addCommentNodeSelection)的复合命令。文本版要求选区非空且范围内不存在未解决resolved: false的评论 Mark然后用addMark加上{ id: uuidv4(), userId, draft: true }的 comment Mark 并collapseSelection()节点版则把同样的 Mark 对象追加进node.attrs.marks数组。注释说明Mark 以草稿形式存在提交时才在服务端落定。addDraftCommentAnchor(options)为能评论不能编辑的用户准备——不修改文档而是把锚点信息通过tr.setMeta(draftCommentAnchorPluginKey, { add: { id, from, to, isNode, userId } })交给 DraftCommentAnchorPlugin 渲染成本地装饰高亮。该文件还定义了与后端 API 对齐的CommentAnchor接口anchorText/anchorPrefix/anchorSuffix/anchorNodeId并内置了锚点消歧策略当锚定文本短于 30 字符unambiguousAnchorLength时额外截取前后各 15 字符anchorContextLength的上下文文本以便服务端在协作编辑导致文本漂移时仍能重新定位。十、文件插入命令占位符 并行上传insertFiles.ts 虽然导出的是一个async函数接收view、事件、插入位置、File[]与选项而非裸 Command但它是拖拽/粘贴文件进入编辑器这一动作的完整实现选项接口Options也值得完整掌握export type Options { isAttachment?: boolean; // 强制图片/视频作为附件 replaceExisting?: boolean; // 替换选区中已有图片 uploadFile?: (file, options?) Promisestring; // 上传回调返回最终 URL onFileUploadStart?: () void; onFileUploadStop?: () void; onFileUploadProgress?: (id: string, fractionComplete: number) void; onNotice?: EditorNotice; attrs?: { width?; height?; alt?; layoutClass?; preview? }; };其执行流程体现了乐观 UI的典型编排事件preventDefault回调onFileUploadStart并行Promise.all分析每个文件按 MIME 判定isImage/isVideo并预取尺寸与 source 属性FileHelper.getImageDimensions/getVideoDimensions/getImageSourceAttr既非图也非视频且 schema 无attachment节点的文件直接跳过对每个文件立即tr.setMeta(uploadPlaceholderPlugin, { add: { pos, ...upload, replaceExisting } })插入占位符——所有占位符一次性进文档而真正的uploadFile上传在后台并行进行上传成功回调中用findPlaceholder(view.state, upload.id)找回占位符区间replaceWith替换为最终的image/video/attachment节点并移除占位元信息图片会先经new Image().onload校验可加载失败路径动态import(sentry/react)上报注释说明懒加载让 Sentry SDK 不进入启动模块图移除占位符、console.error并回调onNotice提示用户finally中计数全部完成后回调onFileUploadStop。全程对view.isDestroyed做了守卫防止编辑器已销毁时继续 dispatch。十一、表格命令组table.ts 的工程化细节table.ts1300 行是目录中体量最大的文件围绕prosemirror-tables的selectedRect/TableMap构建主要命令与行为createTable({ rowsCount, colsCount, colWidth })createTableInner用tableNodeTypes依次创建header_cell首行、cell、row、table节点可选地为除末列外的列写入colwidth: [colWidth]createTable在replaceSelectionWith后把光标放回表格左上角anchor 1。sortTable({ index, direction })最复杂的命令。拒绝含rowspan的表排序会破坏结构按列内容自动识别类型——日期要求所有非空单元格可解析货币/IPv4/数字则要求≥2 个且占多数且 IP 判定必须先于数字否则 IP 会被解析成截断数字比较器是方向感知的乘 -1而非事后反转保证稳定排序从而可以链式多键排序空单元格恒沉底表头行全为th排序时摘出、排完放回内容无变化则直接返回不替换节点。exportTable({ fileName })把当前表导出为 CSV——双引号转义为两个引号、经CSVHelper.sanitizeValue防止公式注入、Blob 临时a download触发下载。行列增删与对齐保护addRowBefore/addColumnBefore在位置 0 且表启用了表头时走chainTransactions(toggleHeader, addRow, toggleHeader, setCursorInCell)的三明治结构避免表头行被卷入新行addRowAndMoveSelection则处理在第一列行首按回车时向上插行的特例。宽度与属性distributeColumns把选中列的总宽均分全宽表格的末列保持null宽度以继续自适应setColumnAttr/setRowAttr/setTableAttr分别以合并方式写列对齐、行对齐注释明确行对齐是逐单元格属性Markdown 序列化只支持列对齐与表级layout。选区模型selectRow/selectColumn/selectTable使用 Outline 自定义的 RowSelection 与 ColumnSelection 扩展选区类型并支持expand参数在锚点与目标行/列之间做拉伸选中操作后还有restoreColumnSelection等辅助函数在结构变化后重建选区。相关行为有 table.test.ts 覆盖。十二、折叠块命令组toggleBlock.ts 的保体操作toggleBlock.ts 服务于 Outline 的折叠容器container_toggle节点标题可折叠、正文可展开。由于折叠状态下正文在文档中仍然存在、只是不渲染所有编辑操作都必须避免把折叠的正文弄丢于是目录里出现了一族...PreservingBody命令toggleBlock在祖先链中nearest出最近的折叠块通过tr.setMeta(toggleFoldPluginKey / toggleEventPluginKey, { type: FOLD|UNFOLD, at: pos })发事件让插件切换折叠状态——命令本身只改元数据视图与协同同步由插件响应deleteSelectionPreservingBody/joinForwardPreservingBody/selectNodeForwardPreservingBody等在折叠块的标题上做删除、合并、跨块选区扩展前先用detachToggleBlockBody(pos, tr)把正文从文档中临时摘下操作完成后再attachToggleBlockBody装回indentBlock/dedentBlocks用ReplaceAroundStep把当前块包进新的container_toggle或反向lift出容器两者都显式让位——在列表里让列表的 Tab 处理器处理在表格里让表格的 Tab 处理器处理exitToggleBlockOnEmptyParagraph正文最后一个空段落按回车时lift出折叠块splitBlockPreservingBody在折叠的标题中间按回车把后半段文本装进新建的同类型块并wrapNodeAt包成新折叠块id用v4()生成再删掉原标题尾段。十三、selectAll 与 toggleWrap两个小而全的命令selectAll.ts 演示了selectAll这一键位的多级接管传入节点类型如code_block用findParentNode定位最近的该类型祖先若选区已经恰好覆盖整个节点start from - 1 end to 1则返回false让位给外层处理器否则把选区设为该节点内容首尾之间的TextSelection.between。toggleWrap.ts 则是与toggleBlockType平行的容器版isNodeActive(type)为真时用官方lift解包否则wrapIn(type, attrs)包裹同样只有十几行。十四、如何为编辑器新增一个合规范式的命令综合目录内 18 个命令文件可以提炼出 Outline 的命令编写规范供扩展时遵循类型即契约函数签名必须可赋值给prosemirror-state的Command类型参数化的命令一律写成工厂返回 CommandtoggleList、toggleMark、toggleWrap等皆是如此使同一逻辑可绑定到多个键位/菜单项。守卫优先尽早返回false每个命令先检查是否处于适用场景isInCode、isInTable、选区类型instanceof判断不适用就交棒。命令链的顺序即优先级。副作用必须被dispatch?.()守卫保证无dispatch调用时命令是纯探测、可安全重复执行。复用查询与工具层命令几乎不做裸遍历而是依赖shared/editor/queries/下的findParentNode、isNodeActive、isMarkActive、isInList等查询函数以及shared/editor/lib/chainTransactions.ts的chainTransactions对事务链的包装可混入返回tr | false的片段函数。位置敏感操作要做偏移管理批量改属性从后往前做toggleCheckboxItems、删除从后往前做outdentInCode、结构变更后重建选区表格命令的restoreColumnSelection。核心路径写测试目录内 codeFence.test.ts、table.test.ts、toggleList.test.ts 对应三个最容易出偏移 bug 的命令组新增类似复杂度的命令时应对照补齐。结语从 shared/editor/commands/README.md 短短几行的定义出发可以完整看到 Outline 协作编辑器的行为层组织方式以 ProseMirror Command 的状态探测 事务提交 布尔让棒三要素为契约把加 Mark、块类型切换、列表转换、代码块编辑、链接、评论锚点、文件上传、表格与折叠块等十余类编辑动作拆成可独立测试、可链式组合的小函数库。这套模式不依赖任何 Outline 私有的全局状态所有上下文都来自state与查询函数因此既是理解该项目编辑器架构的入口也是为任意 ProseMirror 项目设计命令层的可复用参考。【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考