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组件的组合模式。通过使用复合组件、状态提升和内部组合来避免布尔属性泛滥。随着代码库规模扩大，这些模式能让人类和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

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

重构带有大量布尔属性的组件时
构建可复用组件库时
设计灵活的组件API时
评审组件架构时
使用复合组件或Context Provider时

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
```
- 不要通过添加布尔属性来自定义行为；请使用组合模式
```
architecture-compound-components
```
- 通过共享Context构建复杂组件的结构

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、actions、meta的通用接口，用于依赖注入
```
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