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 NOT to Use

何时不使用

Skip these patterns when: fewer than 3 props, simple variants, or single-use components.

在以下场景跳过这些模式：组件属性少于3个、仅为简单变体或仅单次使用的组件。

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. 组件架构（高优先级）

Avoid boolean props — Don't add boolean props like
```
isThread
```
,
```
isEditing
```
,
```
isDMThread
```
to customize behavior. Each boolean doubles possible states. Use composition instead — see references/architecture-avoid-boolean-props.md
Compound components — Structure complex components with shared context so each subcomponent accesses state via context, not props — see references/architecture-compound-components.md

避免布尔属性 — 不要添加
```
isThread
```
、
```
isEditing
```
、
```
isDMThread
```
这类布尔属性来定制组件行为。每个布尔属性都会使可能的状态数量翻倍。改用组合模式——详见references/architecture-avoid-boolean-props.md
复合组件 — 用共享Context构建复杂组件，让每个子组件通过Context而非属性访问状态——详见references/architecture-compound-components.md

2. State Management (MEDIUM)

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

Decouple implementation — Provider is the only place that knows how state is managed — see references/state-decouple-implementation.md
Context interface — Define generic interface with
```
state
```
,
```
actions
```
,
```
meta
```
for dependency injection — see references/state-context-interface.md
Lift state — Move state into provider components for sibling access — see references/state-lift-state.md

解耦实现 — Provider是唯一知晓状态管理方式的地方——详见references/state-decouple-implementation.md
Context接口 — 定义包含
```
state
```
、
```
actions
```
、
```
meta
```
的通用接口以实现依赖注入——详见references/state-context-interface.md
提升状态 — 将状态移至Provider组件中，以便兄弟组件访问——详见references/state-lift-state.md

3. Implementation Patterns (MEDIUM)

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

Explicit variants — Create explicit variant components instead of boolean modes — see references/patterns-explicit-variants.md
Children over render props — Use
```
children
```
for composition instead of
```
renderX
```
props — see references/patterns-children-over-render-props.md

显式变体 — 创建显式的变体组件，而非使用布尔模式——详见references/patterns-explicit-variants.md
优先使用Children而非渲染属性 — 使用
```
children
```
进行组合，而非
```
renderX
```
属性——详见references/patterns-children-over-render-props.md

4. React 19 APIs (MEDIUM)

4. React 19 API（中优先级）

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

No forwardRef — Don't use
```
forwardRef
```
; pass
```
ref
```
as a regular prop. Use
```
use()
```
instead of
```
useContext()
```
— see references/react19-no-forwardref.md

仅适用于React 19+。 若使用React 18或更早版本，请跳过此部分。

无需forwardRef — 不要使用
```
forwardRef
```
；将
```
ref
```
作为常规属性传递。使用
```
use()
```
替代
```
useContext()
```
——详见references/react19-no-forwardref.md