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

React 组合模式

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

何时应用

在以下情况下参考这些指南：

• 重构包含大量布尔类型 prop 的组件
• 构建可复用的组件库
• 设计灵活的组件 API
• 审查组件架构
• 使用复合组件或上下文提供者

按优先级划分的规则类别

快速参考

1. 组件架构（高）

• architecture-avoid-boolean-props - 不要添加布尔类型 prop 来自定义行为；使用组合
• 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 props

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