React Composition Patterns

React Composition Patterns 是什么

这是 Vercel 发布的 React 组件架构规则集，目标是让组件 API 随功能增长仍可理解、可组合和可测试。它重点处理布尔属性不断增加、单体组件承担过多模式、状态与界面紧耦合等问题，并给出 compound components、provider 与显式变体的替代设计。

适用场景与不适用场景

适合设计组件库、重构复杂业务组件或评审公共 React API。小型一次性组件不必套用全部结构；当状态只在局部使用时，也无需强行建立 Context。规则包含 React 19 专属建议，React 18 项目必须跳过相关部分。

核心能力与工作机制

核心规则包括：用组合组件替代布尔模式组合；通过共享 Context 协调子组件；把状态实现封装在 provider 中，让 UI 只依赖通用 state/actions/meta 接口；需要外部兄弟组件访问状态时上提 provider；不同产品形态使用显式变体组件；优先 children，只在父组件必须提供数据时使用 render prop。

实际工作流与产物

先列出当前组件的模式和布尔属性组合，识别哪些代表真正不同的产品变体；定义最小 Context 契约，再把状态管理注入 provider，把可视部分拆成可组合子组件。迁移时保留旧 API 兼容层，逐个调用点替换，并用交互测试验证焦点、受控状态和错误处理。

安装、依赖与权限

需要现有 React 工程和测试环境，不依赖外部服务。React 19 可把 ref 当普通 prop，并用 use() 读取 Context；React 18 仍应使用 forwardRef 与 useContext。仓库接口未提供许可证，但 SKILL frontmatter 明确声明 MIT。

限制、风险与使用建议

过度组合会制造层级和样板；过于通用的 Context 也会隐藏数据流。显式变体应共享真正稳定的底层部件，而不是复制实现。迁移公共组件时，布尔属性的默认值、键盘行为、ARIA 和样式选择器都可能是隐性契约，需要回归。

上手建议

从一个布尔属性最多、调用方式最难解释的组件试点。画出旧 API 的有效组合与非法组合，再设计能让非法状态难以表达的新 API。先保持行为不变，再改善内部结构；发布组件库时提供迁移示例和弃用周期。

来源、版本与许可

依据 vercel-labs/agent-skills 固定提交的完整 Skill、README 与规则集合整理；Skill frontmatter 声明 MIT。

常见问题

1. 什么是布尔属性爆炸？

当一个组件用多个 isX、showY、compact 等布尔值表达不同产品模式时，组合数量指数增长，许多组合无意义。规则建议把稳定模式设计成显式变体或可组合子组件。

2. 什么时候使用 compound components？

当一组子元素共享状态和语义、但调用者需要自由安排布局时很合适，例如菜单、标签页和对话框。若只有一个简单视图，复合组件可能增加不必要的 Context 与层级。

3. 为什么状态实现要与 UI 解耦？

UI 依赖通用 state、actions、meta 契约后，可以替换本地状态、远程状态或测试实现，而不重写展示层。provider 负责具体机制，组件只消费它承诺的接口。

4. 何时需要上提 provider？

当控制按钮、摘要或其他兄弟组件也要读取或修改同一状态时，应把 provider 放到它们共同祖先。不要仅为理论复用把所有状态放到应用根部，应保持最小作用域。

5. children 与 render prop 如何选择？

静态组合和布局优先 children，API 更接近普通 JSX。只有父组件必须把内部计算数据交给调用者渲染时，render prop 才有明显价值；不要把它当作默认插槽形式。

6. React 18 能直接使用这些规则吗？

大部分组合原则可以，但 ref 作为普通 prop、use() 读取 Context 等是 React 19 建议。React 18 项目仍需 forwardRef 和 useContext，并以项目实际版本为准。

7. 显式变体会不会造成代码重复？

变体组件可以复用稳定的基础部件和状态契约，只把真正不同的结构或行为显式化。若只是复制整套组件，则没有获得组合优势，应继续下沉公共原语。

8. 重构时如何避免破坏现有调用方？

先记录旧属性默认值和合法组合，建立行为测试，再提供兼容适配层与弃用提示。逐个迁移调用点并检查键盘、ARIA、受控状态和样式，而不是一次删除旧 API。