Plate Input Rules 文档审计对齐显式激活的 inputRules API 与 Kit 接线【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate这篇技术指南围绕 Plate 仓库中的 Input Rules 文档审计计划 展开系统讲解 Plate 富文本编辑器中 input rules输入规则从隐式默认/字符串键激活迁移到显式规则实例 inputRules: [...]激活的 API 变化以及文档审计的目标、检查清单、验证命令与底层源码实现。读者阅读后将掌握CodeBlockRules.markdown({ on })、MathRules.markdown({ variant, on })的正确用法、如何审计文档中过时的 input rules 示例并能结合createRuleFactory源码理解规则工厂的执行原理。审计背景input rules 从隐式默认走向显式激活Plate 的输入规则体系input rules负责把用户输入转换为结构节点#前缀变成标题、三反引号围栏变成代码块、URL 变成链接、-变成→。随着 API 演进这套体系经历了关键迁移而文档审计计划正是为了确保所有公开文档与新的 API 保持一致。迁移的核心结论是输入规则永远是显式的。注册一个插件不会自动激活任何规则规则必须由调用方显式传入插件的inputRules数组不存在隐藏的默认规则集合也不存在字符串键string-key形式的激活层。这一点在 Plugin Input Rules 指南/plugin-input-rules.mdx) 中被明确为 Callout 提示也正是审计计划中不得再用陈旧措辞把 input rules 描述为隐藏默认值或字符串键激活这一检查项的来源。该 API 迁移的另一个里程碑是platejs/autoformat的弃用packages/autoformat/CHANGELOG.md 记录到Markdown 快捷键与文本替换现在以inputRules形式编写在各自的 feature 插件上AutoformatPlugin仅保留为惰性兼容导出。这意味着文档中所有依赖 autoformat 字符串匹配表如{ match: # , mode: block }的示例都需要改写为对应的规则工厂调用。审计范围Scope审计计划明确了需要逐一检查的文档面共五个层级层级说明guide 页面如 plugin-input-rules.mdx/plugin-input-rules.mdx) 这类系统性指南plugin 页面各 feature 插件的使用页element 页面如 code-block.mdx/(elements)/code-block.mdx) 这类元素级文档registry-facing 示例会出现在文档构建中的 registry 示例代码content/components/changelog.mdx变更日志条目从仓库现状看inputRules的使用点主要分布在 plugin-input-rules.mdx/plugin-input-rules.mdx)1035 行指南覆盖快速开始、feature 规则、本地替换、自定义规则、执行顺序与 API 参考以及 code-block.mdx/(elements)/code-block.mdx) 等元素页面中这些正是审计的核心对象。检查项一CodeBlockRules.markdown() 必须携带 on 选项审计清单的第一条是不得再出现不带on的CodeBlockRules.markdown()示例。这一要求直接对应代码块的围栏输入规则实现。packages/code-block/src/lib/CodeBlockRules.ts 中CodeBlockRules.markdown通过createRuleFactory声明为blockFence类型规则export const CodeBlockRules { markdown: createRuleFactory { on: break | match }, { block: string; fence: string }, BlockFenceInputRuleMatch ({ type: blockFence, fence: , block: KEYS.p, enabled: ({ editor }) !isCodeBlockInputBlocked(editor), priority: 100, apply: ({ editor, on }, match) { insertCodeBlockAtPath(editor, match.path); return true; }, }), };从类型签名可以看出on是必填选项取值只有两种on: match三反引号围栏输入完成闭合时立即提交为代码块on: break围栏完成后按Enter才提交为代码块。正确示例应写作import { CodeBlockPlugin } from platejs/code-block; const plugin CodeBlockPlugin.configure({ inputRules: [CodeBlockRules.markdown({ on: match })], });这一点在元素文档 code-block.mdx/(elements)/code-block.mdx) 中已有明确定义Useon: matchto commit when the fence becomes complete oron: breakto commit onEnter。而测试 packages/code-block/src/lib/BaseCodeBlockPlugin.inputRules.spec.tsx 中on: match与on: break两种路径均有对应用例如inputRules: [CodeBlockRules.markdown({ on: match })]与inputRules: [CodeBlockRules.markdown({ on: break })]可作为文档示例的事实依据。此外该规则的enabled守卫通过isCodeBlockInputBlocked检查当前选择是否已位于代码块内避免在代码块内部再触发围栏转换——这是审计示例时需要保留的语义细节。检查项二MathRules.markdown({ variant: $$ }) 必须携带 on 选项审计清单的第二条针对数学公式规则不得再出现不带on的MathRules.markdown({ variant: $$ })示例。原因同样可从源码找到。packages/math/src/lib/MathRules.ts 中MathRules.markdown的选项类型是一个联合类型export const MathRules { markdown: createRuleFactory { variant: $ } | { on: break | match; variant: $$ } ((options) options.variant $$ ? { type: blockFence, fence: $$, block: KEYS.p, on: options.on, enabled: ({ editor }) !isEquationInputBlocked(editor), priority: 100, apply: ({ editor }, match) { const blockMatch match as BlockFenceInputRuleMatch; editor.tf.removeNodes({ at: blockMatch.path }); insertEquation(editor, { at: blockMatch.path, select: true }); return true; }, } : { type: insertText, enabled: ({ editor }) !isEquationInputBlocked(editor), trigger: $, resolve: (context) { if (context.text ! $ || context.options?.at) return; return getInlineEquationMatch(context); }, apply: ({ editor }, match) { const inlineMatch match as { deleteRange: TRange; texExpression: string; }; editor.tf.delete({ at: inlineMatch.deleteRange }); editor.tf.select(inlineMatch.deleteRange.anchor); insertInlineEquation(editor, inlineMatch.texExpression); return true; }, } ), };类型层面已经强制约束了写法MathRules.markdown({ variant: $ })不需要on它是行内公式规则基于insertText目标输入$触发通过matchDelimitedInline匹配行内 TeX 表达式MathRules.markdown({ variant: $$, on: break | match })必须带on它是块级公式规则基于blockFence目标$$围栏闭合后按on策略提交为块级公式。因此任何MathRules.markdown({ variant: $$ })不带on的文档示例在类型检查阶段就会失败这正是审计清单要求清理它们的直接原因。测试 packages/math/src/lib/inputRules.spec.tsx 中同时覆盖了三种形态blockMathRule MathRules.markdown({ on: break, variant: $$ })、inlineMathRule MathRules.markdown({ variant: $ })、以及on: match的块级变体可作为文档与实现的对照基准。检查项三清除隐藏默认值 / 字符串键激活的陈旧措辞审计清单的第三条要求不得再用陈旧措辞把 input rules 描述为隐藏默认值或字符串键激活。这是文档措辞层面的清理对应新旧两代 API 的表述差异旧表述暗示注册插件后输入规则自动生效或通过字符串键如#、在配置中直接激活规则新表述规则是具体的实例对象调用方把它们原样传入inputRules数组规则实例可以重复使用、可以按需挑选注册插件本身不激活任何规则。在 plugin-input-rules.mdx/plugin-input-rules.mdx) 中这一模型被总结为三层所有权分工LaneOwnerExample核心层CorecreateMarkInputRule、createBlockStartInputRule、createBlockFenceInputRule、createTextSubstitutionInputRule、createRuleFactory、defineInputRuleFeature 规则族Feature 包HeadingRules、BlockquoteRules、CodeBlockRules、BulletedListRules、MathRules、LinkRules激活层Kit / 应用把规则实例传入inputRules: [...]feature 包负责语义规则族的定义Kit 与应用负责激活。文档中凡是出现默认开启自动注册字符串键匹配表等旧范式描述都应改写为显式的规则实例接线方式。审计时还需注意 plugin-components.mdx/plugin-components.mdx) 等 guide 页面中的示例如inputRules: [CodeRules.markdown()]确保它们与新模型一致。检查项四changelog 条目必须讲清面向文档的迁移审计清单的最后一条要求changelog 条目需要清楚解释这次面向文档的迁移。content/components/changelog.mdx是文档构建中对外展示变更记录的面板。审计要求该条目至少回答三个问题为什么变input rules 从platejs/autoformat的字符串匹配表迁移到各 feature 插件的inputRules怎么迁移旧示例{ match: , mode: block, type: KEYS.codeBlock }改写为CodeBlockPlugin.configure({ inputRules: [CodeBlockRules.markdown({ on: match })] })对读者意味着什么阅读旧文档时若看到无on的CodeBlockRules.markdown()或无on的MathRules.markdown({ variant: $$ })属于过期示例应以带on的写法为准。仓库侧的证据见 packages/autoformat/CHANGELOG.md其中给出了一批新旧映射例如标题{ match: # ..###### , mode: block, type: KEYS.h1..h6 }→HxPlugin.configure({ inputRules: [HeadingRules.markdown()] })加粗{ match: **, mode: mark, type: KEYS.bold }→BoldRules.markdown({ variant: * })围栏{ match: , mode: block, type: KEYS.codeBlock }→CodeBlockRules.markdown({ on: match })。这些映射表可直接用于审核 changelog 条目的完整性。底层原理createRuleFactory 如何把选项并入规则文档审计之所以如此强调on与variant选项是因为它们不是装饰性的参数而是直接决定规则行为的核心配置。packages/core/src/lib/plugins/input-rules/createRuleFactory.ts 的实现展示了选项的合并机制createRuleFactory接受一个配置对象或一个返回配置的工厂函数返回一个接收options的工厂函数调用时通过getMergedInput(context, factoryOptions)把调用方传入的选项与运行时上下文合并enabled守卫按insertText/insertBreak/insertData/ selection 四类上下文分别提取priority则优先取调用方显式传入的值其次取配置中的默认值。从源码结构可以推断CodeBlockRules.markdown({ on })中的on会被并入规则上下文在apply回调中通过({ editor, on }, match)解构出来使用而MathRules.markdown的variant则是在工厂构建阶段就决定了返回blockFence还是insertText形态。也就是说variant决定规则是什么类型on决定规则何时提交两者组合出的行为矩阵正是文档必须逐字写准的原因。对应的测试 packages/core/src/lib/plugins/input-rules/createRuleFactory.spec.ts 与 packages/core/src/react/utils/inputRules.spec.tsx 覆盖了工厂函数与各规则族的组合行为审计新增示例时可以参照这些测试保证代码可运行。验证命令文档改动的三类检查审计计划给出了三步验证分别覆盖构建、类型与代码风格pnpm turbo build --filter./apps/www pnpm turbo typecheck --filter./apps/www pnpm lint:fix命令作用兜底的问题pnpm turbo build --filter./apps/www构建文档站点apps/www文档示例若引用了不存在的导出或错误路径会在构建期暴露pnpm turbo typecheck --filter./apps/www对文档站点做 TypeScript 类型检查无on的CodeBlockRules.markdown()、无on的MathRules.markdown({ variant: $$ })这类类型错误会被直接拦截pnpm lint:fix执行仓库 lint 并自动修复保证示例代码风格与仓库规范一致其中 typecheck 是审计计划最关键的防线因为on在createRuleFactory的类型签名中是必填项任何漏写on的文档示例都无法通过类型检查这正是检查清单与验证命令互为表里的设计——前者指导人工排查后者用类型系统机器化兜底。仓库中的相关资源想深入理解本次审计主题的读者可继续阅读以下仓库文件审计计划本体docs/plans/2026-04-15-input-rules-doc-audit-plan.md输入规则系统指南content/docs/(guides)/plugin-input-rules.mdx/plugin-input-rules.mdx)规则工厂核心实现packages/core/src/lib/plugins/input-rules/createRuleFactory.ts代码块围栏规则packages/code-block/src/lib/CodeBlockRules.ts配套测试 BaseCodeBlockPlugin.inputRules.spec.tsx数学公式规则packages/math/src/lib/MathRules.ts配套测试 inputRules.spec.tsxautoformat 迁移记录packages/autoformat/CHANGELOG.md元素文档示例content/docs/(plugins)/(elements)/code-block.mdx/(elements)/code-block.mdx)小结本次 Input Rules 文档审计的核心目标是让仓库中所有展示inputRules用法的文档与新 API 完全对齐CodeBlockRules.markdown()必须携带on: match | breakMathRules.markdown({ variant: $$ })必须携带on文档措辞不得再暗示隐藏默认值或字符串键激活changelog 需完整解释面向文档的迁移。审计范围覆盖 guide 页面、plugin 页面、element 页面、registry 示例与 changelog最终通过pnpm turbo build、pnpm turbo typecheck与pnpm lint:fix三道命令机械验证。对文档读者和插件作者而言这条审计主线传达的实践原则只有一条input rules 永远是显式的规则实例由你挑选、由你接线类型系统会替你守住每一处漏写。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考