React / 系统课时

复合组件模式

复合组件模式

复合组件把一个复杂控件拆成职责明确、可自由组合的子组件,同时通过共享上下文保持统一状态。本课将实现一个可运行的标签页组件,并说明菜单、弹窗等组件如何复用同一设计思路。

学习目标

  • 理解复合组件如何兼顾封装性与组合自由度
  • 使用 Context 在子组件之间共享状态和操作
  • 识别复合组件的适用场景与边界

核心结构与共享协议

把标签页设计成一个接收大量配置的单体组件,开始时很方便,但当标题需要图标、角标或自定义布局时,配置对象会迅速膨胀。复合组件改为让调用者直接组合 Root、List、Trigger 和 Panel,组件内部只维护公共协议。

这类设计包含多个协作对象:根组件持有状态,触发器修改状态,内容面板读取状态。用结构图先建立关系,比只阅读接口更容易理解。

Tabs 复合组件关系图

复合组件的核心不是把组件挂在同一个对象上,而是先定义稳定的共享协议。这里的协议只有两个字段:当前活动页签 activeValue,以及切换页签的 setActiveValue。所有子组件都通过自定义 Hook 读取它,避免重复编写空值检查。

根组件负责状态所有权,子组件只处理自身职责。这样既能保证同一组标签页状态一致,又允许调用者调整子组件顺序、包裹样式或插入其他内容。

完整实现

下面代码可直接替换 Vite React TypeScript 项目的 src/App.tsx。示例包含必要导入、完整组件定义和页面入口。

tsx
import {
  createContext,
  useContext,
  useState,
  type PropsWithChildren,
  type ReactNode,
} from "react";

type TabsContextValue = {
  activeValue: string;
  setActiveValue: (value: string) => void;
};

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

function useTabs(): TabsContextValue {
  const context = useContext(TabsContext);

  if (!context) {
    throw new Error("Tabs 子组件必须放在 Tabs.Root 内部");
  }

  return context;
}

function Root({
  defaultValue,
  children,
}: PropsWithChildren<{ defaultValue: string }>) {
  const [activeValue, setActiveValue] = useState(defaultValue);

  return (
    <TabsContext.Provider value={{ activeValue, setActiveValue }}>
      <section>{children}</section>
    </TabsContext.Provider>
  );
}

function List({ children }: PropsWithChildren) {
  return <div role="tablist">{children}</div>;
}

function Trigger({
  value,
  children,
}: {
  value: string;
  children: ReactNode;
}) {
  const { activeValue, setActiveValue } = useTabs();
  const selected = activeValue === value;

  return (
    <button
      type="button"
      role="tab"
      aria-selected={selected}
      onClick={() => setActiveValue(value)}
    >
      {children}
      {selected ? " ✓" : ""}
    </button>
  );
}

function Panel({
  value,
  children,
}: {
  value: string;
  children: ReactNode;
}) {
  const { activeValue } = useTabs();

  if (activeValue !== value) {
    return null;
  }

  return <div role="tabpanel">{children}</div>;
}

const Tabs = { Root, List, Trigger, Panel };

export default function App() {
  return (
    <Tabs.Root defaultValue="account">
      <Tabs.List>
        <Tabs.Trigger value="account">账户</Tabs.Trigger>
        <Tabs.Trigger value="notice">通知</Tabs.Trigger>
      </Tabs.List>
      <Tabs.Panel value="account">账户设置内容</Tabs.Panel>
      <Tabs.Panel value="notice">通知设置内容</Tabs.Panel>
    </Tabs.Root>
  );
}

预期结果:

text
页面首次显示“账户 ✓”和“账户设置内容”。
点击“通知”后,选中标记移动到“通知 ✓”,页面只显示“通知设置内容”。

关键边界

Trigger 与 Panel 通过相同的 value 建立关联,因此业务值应保持唯一且稳定。若子组件被放到 Tabs.Root 外部,自定义 Hook 会立即抛出明确错误,避免静默读取到无效状态。

Context 适合共享同一复合组件实例内的状态,但不要把所有视觉样式也塞入 Context。样式、尺寸和禁用态通常应继续通过 Props 传递,否则上下文会变得难以复用,并扩大不必要的更新范围。

菜单、手风琴、步骤条和弹窗都可以采用相同模式:根组件管理公共状态,触发型子组件发出操作,展示型子组件根据状态决定渲染。只有当子组件必须协作时才需要 Context;简单的父子传值继续使用 Props 更直接。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

复合组件模式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通