关键设计决策、权衡与 Issue 证据 ​

1. 决策 A：<Slate /> 更偏“非受控”语义 ​

现象 ​

• value 语义逐步转为 initialValue 语义
• 外部直接“覆盖内部状态”不再是推荐路径

依据 ​

• PR #4540：value 仅作为初始状态
• PR #4922：文档与示例转向 uncontrolled 叙事
• Issue #4992
• Issue #5281
• Issue #4612

权衡 ​

• 优点：减少“外部状态晚到/错序覆盖内部编辑态”的复杂度
• 代价：业务想完全 controlled 时需要自建同步协议与重挂载策略

2. 决策 B：Normalization 强约束 + 可扩展 ​

现象 ​

• 内建不可关闭的结构约束
• 支持业务追加 normalizeNode
• 多轮修复 + 迭代保护

依据 ​

• docs/concepts/11-normalizing.md
• packages/slate/src/core/normalize-node.ts
• packages/slate/src/editor/normalize.ts
• packages/slate/src/core/should-normalize.ts
• Issue #3465
• Issue #5222

权衡 ​

• 优点：结构可预测，selection 与 transforms 逻辑稳定
• 代价：大文档与错误 normalizer 可能引发性能或死循环风险

3. 决策 C：事件层重度兼容，尤其 IME/Android ​

现象 ​

• 使用原生 beforeinput，绕开 React 事件缺陷
• Android 走独立 input manager
• composition 与 selection 恢复逻辑非常复杂

依据 ​

• packages/slate-react/src/components/editable.tsx
• packages/slate-react/src/hooks/android-input-manager/*
• Issue #4400
• Issue #5023
• Issue #3150
• Issue #5124

权衡 ​

• 优点：跨平台输入体验可落地
• 代价：代码复杂、维护成本高、回归测试压力大

4. 决策 D：历史系统默认“文本友好合批” ​

现象 ​

• 连续文本输入/删除自动合并
• set_selection 默认不存历史
• 高阶操作需手工控制批次边界

依据 ​

• packages/slate-history/src/with-history.ts
• packages/slate-history/src/history-editor.ts
• Issue #3756
• Issue #3874

权衡 ​

• 优点：普通输入撤销体验好
• 代价：复杂命令（wrap+unwrap+set）如果不手控批次，会出现“撤销粒度怪异”

5. 决策 E：Path 映射依赖 DOM 索引缓存（并持续演进） ​

现象 ​

• findPath 依赖 NODE_TO_PARENT/NODE_TO_INDEX
• 某些时序下可能读到旧索引

依据 ​

• packages/slate-dom/src/plugin/dom-editor.ts
• Issue #5938
• PR #5800

权衡 ​

• 优点：多数路径查询性能可接受
• 代价：渲染时序边界复杂，易出现“偶发 path 不准”

6. 你在技术讨论中怎么体现“理解了权衡” ​

建议模板：

1. 我先说设计目标（可扩展/协作/跨端输入）
2. 再说关键机制（operation、normalize、DOM mapping、history batch）
3. 最后补真实 trade-off（性能、时序、复杂度）和 issue 证据

这样会比“只背 API”更像架构级工程师。