Plate 富文本编辑器的 React 19.2 运行时性能验证指南：Activity、Transitions、useEffectEvent 与 Performance Tracks 的边界纪律

Plate 富文本编辑器的 React 19.2 运行时性能验证指南：Activity、Transitions、useEffectEvent 与 Performance Tracks 的边界纪律

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

本篇指南以 .agents/skills/performance/rules/react-19-runtime-proof.md 为骨架，结合 Plate 当前仓库（根依赖锁定react@19.2.4）的源码与既有执行计划，系统讲解在富文本编辑器性能优化车道（perf lane）中如何正确使用 React 19.2 原语。你将掌握：何时用<Activity>处理隐藏/后台面板、哪些工作必须保持 urgent（同步）、useEffectEvent的合法使用边界、如何用 React Performance Tracks 证明"渲染广度"而非"编辑器正确性"，以及为什么cacheSignal与 PPR 与编辑器热路径无关。

何时启用这套验证规则

本规则文档（位于仓库 .agents/skills/performance/rules/react-19-runtime-proof.md）的触发条件是：在性能优化车道中，有人提议使用 React 19.2 原语（<Activity>、transitions、useEffectEvent等）来提升编辑性能。它是一份"边界纪律"清单——不教你如何炫技，而是划定"哪些地方可以用、哪些地方绝对不能用"。

Plate 仓库当前的运行时基线与这份规则完全对齐：仓库根 package.json 将react锁定在19.2.4，apps/www/package.json 同样使用react@19.2.4与react-dom@19.2.4，迁移文档 content/docs/migration/v48.mdx 也明确声明对 React 19 的支持。也就是说，这套规则不是"未来假设"，而是当前代码库真实可执行的性能纪律。

Activity：隐藏/后台 UI 的专用原语，不是编辑器的隐藏可编辑层

适用场景：面板、检查器、预览窗格、可能进入的视图

规则给出的第一优先原语是<Activity>。它适用于：

• 隐藏/后台的 UI 面板（hidden/background UI panels）；
• 检查器（inspectors）；
• 预览窗格（preview panes）；
• 可能即将进入的视图（likely-next views）。

在这些场景下，hidden模式允许 React 卸载效果（unmount effects）并推迟更新（defer updates），从而把不可见 UI 的渲染成本移出用户感知路径。这正是仓库计划文档 docs/plans/2026-04-06-slate-v2-react-19-2-convergence.md 中描述的"可选<Activity>证明车道（proof lane）"：让"隐藏编辑器在隐藏期间保留本地 React 状态、恢复时效果干净地卸载与重绑、并读取最新已提交快照"成为可验证的事实，而不是理论。

绝对禁区：不要用 Activity 充当 Slate 隐藏可编辑内容原语

规则用一句话划出了红线：

Do not treatActivity hiddenas a Slate hidden editable content primitive.

Activity hidden不能解决以下浏览器原生行为：

• 浏览器查找（browser find）；
• 原生选区（native selection）；
• IME（输入法组合）；
• 复制/粘贴（copy/paste）；
• 屏幕阅读器（screen-reader）；
• DOM 点映射（DOM point mapping）。

原因在于：Activity是 React 渲染层的原语，它只影响 React 自身的挂载/卸载与调度；而上述六项能力全部依赖真实 DOM 的存在性、焦点、选区与无障碍树。仓库发布声明 docs/slate-v2/absolute-architecture-release-claim.md 也据此将隐藏/后台 UI 的姿态表述为"与 React Activity 兼容"，同时明确 shell/occlusion 升级路径"在浏览器查找、屏幕阅读器、原生选区、复制/粘贴、IME、移动端、undo/history 与协作证明通过之前，保持显式或 proof-disabled 状态"。

从实现侧看，这也与 Plate 的架构选择一致：核心包的编辑路径并不依赖<Activity>包裹——packages/core/src/react/components/PlateContent.tsx 中编辑内容以常规组件树渲染，编辑器的正确性由快照驱动的订阅层保证（详见下文"Performance Tracks 的证明边界"一节）。

Transitions 与延迟值：只服务于"派生 UI"，绝不碰输入与选区

应当使用的地方

规则建议把 transitions / deferred values 用在以下非紧急投影（non-urgent projections）上：

• 浮层（overlays）；
• 搜索结果（search results）；
• 侧边栏（sidebars）；
• 后台摘要（background summaries）。

这类工作可以被打上低优先级，让出主线程给紧急交互。

必须保持 urgent 的清单

规则明确列出以下行为必须保持 urgent（同步、高优先级）：

• 可见的输入（visible typing）；
• DOM 文本同步（DOM text sync）；
• 选区导入/导出（selection import/export）；
• 光标修复（caret repair）；
• IME。

这五类操作任何一项进入 deferred 车道，都会直接表现为打字延迟、光标跳动或中文/日文输入法组合错乱。仓库执行计划 docs/plans/2026-04-06-slate-v2-react-19-2-convergence.md 将其落成硬性非目标（Non-Goals）：

• 不在 typing、composition、selection repair 或 commit publication 周围使用 transitions；
• 不用useDeferredValue处理活动选区或文本正确性；
• 不把编辑器变更（mutations）包进startTransition；
• 不用Activity隐藏 rerender 或选区 bug。

Effect Events：只用于"effect 所有的事件型回调"

合法用途

useEffectEvent的唯一合法场景是：从 effect 或外部订阅（external subscriptions）触发的、事件型（event-like）的回调。它让这类回调在 effect 重新执行时不需要反复重建，同时能读到最新闭包。

明确禁止的用途

Do not use it to silence dependency warnings.

规则明确禁止用useEffectEvent来"消除依赖数组告警"。仓库对该原语的态度是"很窄的、按需引入"（likely later or very narrow now）：docs/plans/2026-04-06-slate-v2-react-19-2-convergence.md 记载了当时的审计结论——Editable的 effects 大部分是外部 DOM 同步，形态已经合理，尚无充分证据表明存在依赖数组 hack 或 effect-owned 回调抖动需要useEffectEvent；允许的仅限"在Editable中明确简化 DOM 监听器接线且不改变语义"的窄切口。落地时同样遵循该纪律：不围绕useEffectEvent设计任何公开 hook API，不做大规模替换回调的重构。

Performance Tracks：证明"React 工作广度"，而非编辑器正确性

何时采集

当 React 工作广度（work breadth）可疑时，应采集 React Performance Tracks，覆盖以下维度：

证明边界：两条"能"与"不能"

规则给出关键边界：

• 能证明：React 工作广度（React work breadth），即"React 层面渲染了多少、阻塞了多久"；
• 不能证明：编辑器脏程度（editor dirtiness）、选区映射（selection mapping）或原生行为正确性（native behavior correctness）。

也就是说，Tracks 是"渲染层探针"，不是"编辑器语义探针"。要证明编辑器是否正确，需要的是编辑器的快照一致性证据，而不是渲染次数。Plate 的渲染架构恰好为此提供了互补证据：核心包的 packages/core/src/react/stores/element/useElementSelector.ts 基于useSyncExternalStore做快照驱动的选择器订阅——订阅者从runtime读取getState().entry快照，用equalityFn（默认a === b）决定是否重渲染，缓存命中时直接返回已缓存的派生值。这种 selector-first 的 live-read 模式意味着"重渲染广度"与"编辑器数据变更"解耦，与规则中"tracks 证明广度、快照证明正确性"的分工完全一致。

Server APIs：cacheSignal 与 PPR 是页面壳工具，与编辑器热路径无关

规则最后一条边界面向服务端：

cacheSignaland partial pre-rendering are page-shell/server tools. They are usually irrelevant to the editor body hot path.

cacheSignal与部分预渲染（partial pre-rendering, PPR）属于页面外壳（page-shell）/服务端工具，服务于首屏壳层与缓存失效信号，通常与**编辑器正文的热路径（editor body hot path）**无关——编辑器的热路径是浏览器内的输入、选区与 DOM 同步，服务端原语不参与其中。这条规则提醒性能优化者：不要为了"用上 React 19 全家桶"而把服务端工具拉进编辑内核。

实战决策速查表

把整份规则收敛成一张可以在 perf lane 评审时直接对照的速查表：

与既有执行计划的呼应

这套规则并非孤立存在，仓库中已有同主题的执行与证明记录可供追溯：

• docs/plans/2026-04-06-slate-v2-react-19-2-convergence.md：完整记录了 React 19.2 收敛的执行计划——根依赖升级为 19.2、可选<Activity>证明车道、窄切口useEffectEvent、以及"startTransition/useDeferredValue不落地除非有真实派生态"的决策；
• docs/plans/2026-04-02-slate-react-v2-runtime-proof-ralph.md：将 React19.2+锁定为唯一约束，并确立了"selector-first 已提交快照读取、受控替换、无 effect 镜像"的运行期证明目标；
• docs/slate-v2/absolute-architecture-release-claim.md：陈述 React 19.2 运行时证明所依赖的七项基础（selector-first live reads、dirty runtime ids、EditorCommit元数据、source-scoped 投影失效、semantic islands、直接 DOM 文本同步、与 Activity 兼容的隐藏 UI 姿态）；
• packages/core/src/react/stores/element/useElementSelector.ts：快照驱动选择器订阅的源码实现，是"渲染广度与数据正确性解耦"的落地点。

小结

React 19.2 为富文本编辑器带来的不是"魔法加速"，而是一套更精细的调度与渲染边界工具。Plate 仓库的立场可以总结为三句话：

1. 渲染层原语只解决渲染层问题——Activity、transitions、useEffectEvent都属于渲染/调度范畴，不能越界充当编辑器语义或浏览器原生行为的替代品；
2. 输入与选区的紧急路径保持同步——任何把 typing、IME、选区修复推迟到 deferred 车道的方案都应被拒绝；
3. 用对的工具证明对的事情——React Performance Tracks 证明工作广度，快照驱动的订阅与选择器证明编辑器正确性，两者互补，不可互相替代。

在性能优化车道中遇到"提议使用 React 19.2 原语"的方案时，直接对照本文的速查表做边界审查，即可快速判断该提案是值得做的性能改进，还是用新 API 掩盖正确性问题的越界行为。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate