name: vercel-composition-patterns
description: 可扩展的 React 组合模式。适用于重构含有大量布尔属性的组件、构建灵活的组件库或设计可复用 API 的场景。在处理复合组件、渲染属性、上下文提供者或组件架构相关任务时触发。包含 React 19 API 变更。
license: MIT
metadata:
    author: vercel
    version: '1.0.0'

React 组合模式

组合模式用于构建灵活、可维护的 React 组件。通过使用复合组件、状态提升和内部组合，避免布尔属性泛滥。这些模式使代码库在扩展时更容易被人类和 AI 代理协作。

何时应用

在以下场景参考这些指南：

• 重构具有大量布尔属性的组件
• 构建可复用的组件库
• 设计灵活的组件 API
• 审查组件架构
• 处理复合组件或上下文提供者

按优先级划分的规则类别

快速参考

1. 组件架构（高）

• architecture-avoid-boolean-props — 不要添加布尔属性来定制行为；应使用组合
• architecture-compound-components — 使用共享上下文构建复杂组件

2. 状态管理（中）

• state-decouple-implementation — Provider 是唯一知道状态管理方式的地方
• state-context-interface — 定义包含状态、动作、元数据的通用接口，以支持依赖注入
• state-lift-state — 将状态提升到 provider 组件中，以便兄弟组件访问

3. 实现模式（中）

• patterns-explicit-variants — 创建显式的变体组件，而不是使用布尔模式
• patterns-children-over-render-props — 使用 children 进行组合，而不是使用 renderX 属性

4. React 19 API（中）

⚠️ 仅适用于 React 19+。如果使用 React 18 或更早版本，请跳过本节。

• react19-no-forwardref — 不要使用 forwardRef；使用 use() 代替 useContext()

如何使用

阅读各个规则文件以获取详细说明和代码示例：

rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md

每个规则文件包含：

• 为什么它重要（简要说明）
• 错误代码示例及说明
• 正确代码示例及说明
• 额外上下文和参考

完整编译文档

如需包含所有规则扩展的完整指南，请参阅：AGENTS.md