composition-patterns

组合模式

属于 Agent Skills™，由 googleadsagent.ai™ 提供

描述

组合模式教会 Agent 使用复合组件、状态提升、内部组合以及消除布尔属性泛滥，构建灵活且易于维护的 React 组件。这些模式以可组合的接口取代僵化、属性繁多的 API，使其能够随着需求变化而平滑扩展。

Agent 在 React 中最常见的错误，是构建带有几十个布尔属性的庞大组件：showHeader、showFooter、isCompact、isLoading、hasSearch、enableDarkMode。每个布尔值都会使组件的状态空间翻倍，从而形成指数级增长的测试范围，也让组件难以扩展，因为任何修改都必须触及其内部实现。组合模式用结构化组合取代这些布尔值，由使用者通过较小的部分组装组件。

此技能介绍四种互补模式：用于相关 UI 系列的复合组件、用于跨组件共享状态的状态提升、用于封装子渲染的内部组合，以及实现最大使用者灵活性的渲染委托。综合应用这些模式，可以构建易于使用、便于定制且易于测试的组件。

适用场景

• 组件有超过 3 个布尔配置属性
• 相关组件需要共享隐式状态（选项卡、折叠面板、选择器）
• 使用者需要控制子元素的布局或顺序
• 组件需要支持设计时未预见的用例
• 将“上帝组件”重构为可组合的部分
• 构建组件库或设计系统

工作原理

graph TD
    A[Component Design Request] --> B{Pattern Selection}
    B --> C[Compound: Related UI Family]
    B --> D[State Lifting: Shared State]
    B --> E[Internal Composition: Sub-render]
    B --> F[Render Delegation: Consumer Control]
    C --> G[Parent provides context]
    G --> H[Children consume context]
    D --> I[State lives in nearest common ancestor]
    E --> J[Component composes internally]
    F --> K[Consumer passes render function]

Agent 会根据组件之间的关系、所需的使用者控制程度以及共享状态的复杂性，选择合适的模式。

实现

复合组件

const TabsContext = createContext<TabsState | null>(null);

function Tabs({ defaultValue, children }: TabsProps) {
  const [active, setActive] = useState(defaultValue);
  return (
    <TabsContext.Provider value={{ active, setActive }}>
      <div role="tablist">{children}</div>
    </TabsContext.Provider>
  );
}

function Tab({ value, children }: TabProps) {
  const { active, setActive } = useContext(TabsContext)!;
  return (
    <button
      role="tab"
      aria-selected={active === value}
      onClick={() => setActive(value)}
    >
      {children}
    </button>
  );
}

function TabPanel({ value, children }: TabPanelProps) {
  const { active } = useContext(TabsContext)!;
  if (active !== value) return null;
  return <div role="tabpanel">{children}</div>;
}

Tabs.Tab = Tab;
Tabs.Panel = TabPanel;

// Usage: consumer controls structure
<Tabs defaultValue="a">
  <Tabs.Tab value="a">Tab A</Tabs.Tab>
  <Tabs.Tab value="b">Tab B</Tabs.Tab>
  <Tabs.Panel value="a">Content A</Tabs.Panel>
  <Tabs.Panel value="b">Content B</Tabs.Panel>
</Tabs>

消除布尔属性

// BAD: Boolean prop explosion
<Card
  showHeader={true}
  showFooter={false}
  isCompact={true}
  hasAvatar={true}
  showActions={true}
/>

// GOOD: Compositional API
<Card compact>
  <Card.Header>
    <Avatar src={user.avatar} />
    <Card.Title>{user.name}</Card.Title>
  </Card.Header>
  <Card.Body>{content}</Card.Body>
  <Card.Actions>
    <Button>Edit</Button>
    <Button>Delete</Button>
  </Card.Actions>
</Card>

最佳实践

• 子元素共享隐式状态时，使用复合组件
• 为新功能提供可组合的 API，而不是添加布尔标志
• 保持上下文提供程序范围精简——每个关注点一个上下文，而不是一个庞大的上下文
• 提供合理的默认值，让简单用例保持简单
• 通过用法示例说明组合式 API，而不仅是列出属性表
• 使用 TypeScript 可辨识联合类型取代布尔属性组合

平台兼容性

平台	支持情况	备注
Cursor	完全支持	组件生成 + 重构
VS Code	完全支持	支持 TypeScript 的重构
Windsurf	完全支持	React 模式识别
Claude Code	完全支持	组件设计指导
Cline	完全支持	基于模式生成
aider	部分支持	组合意识有限

相关技能

• React 最佳实践
• 视图过渡
• Web 设计指南
• 边缘渲染

关键词

composition compound-components react-patterns state-lifting boolean-props render-delegation design-system composable-api

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT 许可证