vercel-composition-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Composition Patterns

React组合模式

Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.

用于构建灵活、可维护的React组件的组合模式。通过使用复合组件、提升状态和组合内部逻辑来避免布尔型props泛滥。这些模式能让代码库在规模扩大时，对人类和AI Agent都更易维护。

When to Apply

适用场景

Reference these guidelines when:

Refactoring components with many boolean props
Building reusable component libraries
Designing flexible component APIs
Reviewing component architecture
Working with compound components or context providers

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

重构包含大量布尔型props的组件
构建可复用组件库
设计灵活的组件API
评审组件架构
处理复合组件或上下文提供者

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Component Architecture	HIGH	`architecture-`
2	State Management	MEDIUM	`state-`
3	Implementation Patterns	MEDIUM	`patterns-`
4	React 19 APIs	MEDIUM	`react19-`

优先级	类别	影响程度	前缀
1	组件架构	高	`architecture-`
2	状态管理	中	`state-`
3	实现模式	中	`patterns-`
4	React 19 API	中	`react19-`

Quick Reference

快速参考

1. Component Architecture (HIGH)

1. 组件架构（高优先级）

```
architecture-avoid-boolean-props
```
- Don't add boolean props to customize behavior; use composition
```
architecture-compound-components
```
- Structure complex components with shared context

```
architecture-avoid-boolean-props
```
- 不要通过添加布尔型props来定制行为；使用组合模式
```
architecture-compound-components
```
- 用共享上下文构建复杂组件结构

2. State Management (MEDIUM)

2. 状态管理（中优先级）

```
state-decouple-implementation
```
- Provider is the only place that knows how state is managed
```
state-context-interface
```
- Define generic interface with state, actions, meta for dependency injection
```
state-lift-state
```
- Move state into provider components for sibling access

```
state-decouple-implementation
```
- 只有Provider知晓状态的管理方式
```
state-context-interface
```
- 定义包含状态、操作、元数据的通用接口用于依赖注入
```
state-lift-state
```
- 将状态移至Provider组件中，以便兄弟组件访问

3. Implementation Patterns (MEDIUM)

3. 实现模式（中优先级）

```
patterns-explicit-variants
```
- Create explicit variant components instead of boolean modes
```
patterns-children-over-render-props
```
- Use children for composition instead of renderX props

```
patterns-explicit-variants
```
- 创建明确的变体组件，而非使用布尔模式
```
patterns-children-over-render-props
```
- 使用children进行组合，而非renderX属性

4. React 19 APIs (MEDIUM)

4. React 19 API（中优先级）

⚠️ React 19+ only. Skip this section if using React 18 or earlier.

react19-no-forwardref

- Don't use

forwardRef

; use

use()

instead of

useContext()

⚠️ 仅适用于React 19及以上版本。 若使用React 18或更早版本，请跳过此部分。

react19-no-forwardref

- 不要使用

forwardRef

；用

use()

替代

useContext()

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

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

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

每个规则文件包含：

简要说明其重要性
错误代码示例及解释
正确代码示例及解释
额外背景信息和参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有扩展规则的完整指南，请参考：

AGENTS.md