React / 系统课时
复合组件模式
复合组件模式
复合组件把一个复杂控件拆成职责明确、可自由组合的子组件,同时通过共享上下文保持统一状态。本课将实现一个可运行的标签页组件,并说明菜单、弹窗等组件如何复用同一设计思路。
学习目标
- 理解复合组件如何兼顾封装性与组合自由度
- 使用 Context 在子组件之间共享状态和操作
- 识别复合组件的适用场景与边界
核心结构与共享协议
把标签页设计成一个接收大量配置的单体组件,开始时很方便,但当标题需要图标、角标或自定义布局时,配置对象会迅速膨胀。复合组件改为让调用者直接组合 Root、List、Trigger 和 Panel,组件内部只维护公共协议。
这类设计包含多个协作对象:根组件持有状态,触发器修改状态,内容面板读取状态。用结构图先建立关系,比只阅读接口更容易理解。

复合组件的核心不是把组件挂在同一个对象上,而是先定义稳定的共享协议。这里的协议只有两个字段:当前活动页签 activeValue,以及切换页签的 setActiveValue。所有子组件都通过自定义 Hook 读取它,避免重复编写空值检查。
根组件负责状态所有权,子组件只处理自身职责。这样既能保证同一组标签页状态一致,又允许调用者调整子组件顺序、包裹样式或插入其他内容。
完整实现
下面代码可直接替换 Vite React TypeScript 项目的 src/App.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>
);
}预期结果:
页面首次显示“账户 ✓”和“账户设置内容”。
点击“通知”后,选中标记移动到“通知 ✓”,页面只显示“通知设置内容”。关键边界
Trigger 与 Panel 通过相同的 value 建立关联,因此业务值应保持唯一且稳定。若子组件被放到 Tabs.Root 外部,自定义 Hook 会立即抛出明确错误,避免静默读取到无效状态。
Context 适合共享同一复合组件实例内的状态,但不要把所有视觉样式也塞入 Context。样式、尺寸和禁用态通常应继续通过 Props 传递,否则上下文会变得难以复用,并扩大不必要的更新范围。
菜单、手风琴、步骤条和弹窗都可以采用相同模式:根组件管理公共状态,触发型子组件发出操作,展示型子组件根据状态决定渲染。只有当子组件必须协作时才需要 Context;简单的父子传值继续使用 Props 更直接。