企业官网建设流程全解析

Supabase 仓库实践指南：React 组合模式——用复合组件与状态依赖注入摆脱布尔 Prop 蔓延

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

本篇技术文章基于 Supabase 仓库内置的.claude/skills/vercel-composition-patterns/技能文档（由 Vercel 编写的可复用 AI 技能），系统讲解一整套可规模化扩展的 React 组合模式：避免布尔 prop 蔓延、复合组件（Compound Components）、状态提升与state/actions/meta三段式 Context 接口、显式变体、children 优于 render props，以及 React 19 的use()与 ref-as-prop 变更。读完本文，你将掌握一套完整的组件架构方法，并能在当前仓库的 React 19 代码库中识别、套用这些模式。

一、这套模式的定位与适用场景

该技能文档（SKILL.md）开篇即点明目标：构建灵活、可维护的 React 组件，通过复合组件、状态提升与内部组件组合来避免布尔 prop 蔓延。文档同时强调这些模式“让代码库对人类和 AI Agent 都更友好”——这与 Supabase 仓库将文档组织为 Agent 技能（skill）的初衷一致。

文档明确给出了五种应参考这些准则的场景：

• 重构带有很多布尔 prop 的组件；
• 构建可复用的组件库；
• 设计灵活的组件 API；
• 评审组件架构；
• 处理复合组件或 Context Provider。

规则优先级分类

SKILL.md 将全部 8 条规则按优先级分为四类，这个优先级表本身就是文章的核心骨架：

每条规则对应rules/目录下的一个独立文件，文件结构统一为：简述为何重要、错误示例及解释、正确示例及解释、附加上下文与参考。8 个规则文件分别位于 rules/architecture-avoid-boolean-props.md、rules/architecture-compound-components.md、rules/state-decouple-implementation.md、rules/state-context-interface.md、rules/state-lift-state.md、rules/patterns-explicit-variants.md、rules/patterns-children-over-render-props.md、rules/react19-no-forwardref.md。

二、组件架构（HIGH）：从布尔 Prop 到复合组件

这是优先级最高的一类规则，包含两条：architecture-avoid-boolean-props（影响等级 CRITICAL）与architecture-compound-components（影响等级 HIGH）。

2.1 避免布尔 Prop 蔓延

核心论断是：不要为定制组件行为而添加isThread、isEditing、isDMThread这类布尔 prop。每一个布尔 prop 都会使可能状态数翻倍，制造不可维护的条件分支。

文档给出的反例是一个典型的"巨型 Composer"——用 4 个布尔 prop 控制 2 组条件渲染，状态组合已经指数化：

function Composer({ onSubmit, isThread, channelId, isDMThread, dmId, isEditing, isForwarding, }: Props) { return ( <form> <Header /> <Input /> {isDMThread ? ( <AlsoSendToDMField id={dmId} /> ) : isThread ? ( <AlsoSendToChannelField id={channelId} /> ) : null} {isEditing ? ( <EditActions /> ) : isForwarding ? ( <ForwardActions /> ) : ( <DefaultActions /> )} <Footer onSubmit={onSubmit} /> </form> ) }

正确做法是：每个变体显式声明自己渲染什么，共享内部件（Composer.Input、Composer.Footer等）而不共享单一庞大父组件：

// Channel composer function ChannelComposer() { return ( <Composer.Frame> <Composer.Header /> <Composer.Input /> <Composer.Footer> <Composer.Attachments /> <Composer.Formatting /> <Composer.Emojis /> <Composer.Submit /> </Composer.Footer> </Composer.Frame> ) } // Thread composer - adds "also send to channel" field function ThreadComposer({ channelId }: { channelId: string }) { return ( <Composer.Frame> <Composer.Header /> <Composer.Input /> <AlsoSendToChannelField id={channelId} /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.Submit /> </Composer.Footer> </Composer.Frame> ) } // Edit composer - different footer actions function EditComposer() { return ( <Composer.Frame> <Composer.Input /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.CancelEdit /> <Composer.SaveEdit /> </Composer.Footer> </Composer.Frame> ) }

文档对此的总结值得直接引用："每个变体都明确知道自己渲染什么。我们可以共享内部件，而无需共享单一的庞大父组件。"

2.2 使用复合组件（Compound Components）

规则architecture-compound-components给出结构性方案：将复杂组件结构化为共享 Context 的复合组件，每个子组件通过 Context 而非 props 访问共享状态，消费者只组合自己需要的部分。

先看反例——一个混合了 render props 和布尔开关的单体组件：

function Composer({ renderHeader, renderFooter, renderActions, showAttachments, showFormatting, showEmojis, }: Props) { return ( <form> {renderHeader?.()} <Input /> {showAttachments && <Attachments />} {renderFooter ? ( renderFooter() ) : ( <Footer> {showFormatting && <Formatting />} {showEmojis && <Emojis />} {renderActions?.()} </Footer> )} </form> ) }

正确实现拆为"Provider + Frame + 各内部件"，并以命名空间对象的形式对外导出：

const ComposerContext = createContext<ComposerContextValue | null>(null) function ComposerProvider({ children, state, actions, meta }: ProviderProps) { return ( <ComposerContext value={{ state, actions, meta }}> {children} </ComposerContext> ) } function ComposerFrame({ children }: { children: React.ReactNode }) { return <form>{children}</form> } function ComposerInput() { const { state, actions: { update }, meta: { inputRef }, } = use(ComposerContext) return ( <TextInput ref={inputRef} value={state.input} onChangeText={(text) => update((s) => ({ ...s, input: text }))} /> ) } function ComposerSubmit() { const { actions: { submit }, } = use(ComposerContext) return <Button onPress={submit}>Send</Button> } // Export as compound component const Composer = { Provider: ComposerProvider, Frame: ComposerFrame, Input: ComposerInput, Submit: ComposerSubmit, Header: ComposerHeader, Footer: ComposerFooter, Attachments: ComposerAttachments, Formatting: ComposerFormatting, Emojis: ComposerEmojis, }

调用侧的组合方式：

<Composer.Provider state={state} actions={actions} meta={meta}> <Composer.Frame> <Composer.Header /> <Composer.Input /> <Composer.Footer> <Composer.Formatting /> <Composer.Submit /> </Composer.Footer> </Composer.Frame> </Composer.Provider>

文档强调两点收益：消费者显式地只组合需要的部分、没有隐藏的条件分支；state/actions/meta由父级 Provider 依赖注入，因此同一套组件结构可以被多处复用。

仓库源码印证：Supabase 自己的 UI 包中已经存在这种"复合组件 + 共享 Context"的真实实现。例如 MenuContext.tsx 中，Menu组件用createContext建立MenuContext（带{ type: 'text' }默认值），MenuContextProvider负责下发value，并额外导出一个useMenuContext辅助 Hook——在消费者侧若脱离 Provider 使用会直接抛出MenuContext must be used within a MenuContextProvider.错误。从源码结构看，这就是文档所述"子组件通过 Context 而非 props 获取共享状态"模式的落地形态：Provider 是状态/配置的单一来源，内部件各自订阅所需切片。该仓库的packages/ui通过 pnpm-workspace.yaml 的 catalog 锁定react: ^19.2.6，因此文档第 4 类 React 19 规则在本仓库是可直接套用的。

三、状态管理（MEDIUM）：提升、解耦与泛型 Context 接口

第二类规则共三条：state-lift-state（HIGH，影响"让组件边界之外的状态可共享"）、state-decouple-implementation（MEDIUM，"Provider 是唯一知道状态如何管理的地方"）、state-context-interface（HIGH，"定义 state/actions/meta 三段式泛型接口实现依赖注入"）。三者构成一条完整推导链：先把状态提升进 Provider，再定义泛型接口，最终让 UI 与状态实现彻底解耦。

3.1 把状态提升进 Provider（state-lift-state）

问题场景：ForwardMessageComposer内部持有useState，而对话框里的MessagePreview需要读输入内容、ForwardButton需要调用提交——状态被"困"在组件内部。文档列举了三种常见而糟糕的绕过方式，值得逐一对照检查：

错误一：状态被困在组件内部

function ForwardMessageComposer() { const [state, setState] = useState(initialState) const forwardMessage = useForwardMessage() return ( <Composer.Frame> <Composer.Input /> <Composer.Footer /> </Composer.Frame> ) } // Problem: How does this button access composer state? function ForwardMessageDialog() { return ( <Dialog> <ForwardMessageComposer /> <MessagePreview /> {/* Needs composer state */} <DialogActions> <CancelButton /> <ForwardButton /> {/* Needs to call submit */} </DialogActions> </Dialog> ) }

错误二：用 useEffect 把状态"同步"给父级

function ForwardMessageDialog() { const [input, setInput] = useState('') return ( <Dialog> <ForwardMessageComposer onInputChange={setInput} /> <MessagePreview input={input} /> </Dialog> ) } function ForwardMessageComposer({ onInputChange }) { const [state, setState] = useState(initialState) useEffect(() => { onInputChange(state.input) // Sync on every change }, [state.input]) }

错误三：提交时从 ref 读状态

function ForwardMessageDialog() { const stateRef = useRef(null) return ( <Dialog> <ForwardMessageComposer stateRef={stateRef} /> <ForwardButton onPress={() => submit(stateRef.current)} /> </Dialog> ) }

正确做法是把状态整体提升到专门的 Provider：

function ForwardMessageProvider({ children }: { children: React.ReactNode }) { const [state, setState] = useState(initialState) const forwardMessage = useForwardMessage() const inputRef = useRef(null) return ( <Composer.Provider state={state} actions={{ update: setState, submit: forwardMessage }} meta={{ inputRef }} > {children} </Composer.Provider> ) } function ForwardMessageDialog() { return ( <ForwardMessageProvider> <Dialog> <ForwardMessageComposer /> <MessagePreview /> {/* Custom components can access state and actions */} <DialogActions> <CancelButton /> <ForwardButton /> {/* Custom components can access state and actions */} </DialogActions> </Dialog> </ForwardMessageProvider> ) } function ForwardButton() { const { actions } = use(Composer.Context) return <Button onPress={actions.submit}>Forward</Button> }

文档提炼出的关键洞见（Key insight）是：需要共享状态的组件不必在视觉上嵌套于彼此内部，只要位于同一个 Provider 之内即可。ForwardButton位于Composer.Frame之外，仍能拿到submit动作。

3.2 定义 state / actions / meta 三段式泛型 Context 接口（state-context-interface）

这条规则把复合组件的模式抽象成一个类型契约：

// Define a GENERIC interface that any provider can implement interface ComposerState { input: string attachments: Attachment[] isSubmitting: boolean } interface ComposerActions { update: (updater: (state: ComposerState) => ComposerState) => void submit: () => void } interface ComposerMeta { inputRef: React.RefObject<TextInput> } interface ComposerContextValue { state: ComposerState actions: ComposerActions meta: ComposerMeta } const ComposerContext = createContext<ComposerContextValue | null>(null)

三个部分的分工很清晰：state是只读数据快照，actions是受控的变更入口（注意update采用函数式 updater 签名，等价于setState的语义），meta承载ref等非状态性的元数据。UI 组件只消费这个接口：

function ComposerInput() { const { state, actions: { update }, meta, } = use(ComposerContext) // This component works with ANY provider that implements the interface return ( <TextInput ref={meta.inputRef} value={state.input} onChangeText={(text) => update((s) => ({ ...s, input: text }))} /> ) }

该规则进一步展示了两个 Provider 实现同一接口的能力——ForwardMessageProvider用useState（临时表单的本地状态），ChannelProvider用useGlobalChannel(channelId)（全局同步状态）——而同一段组合式 UI 对两者通吃：

// Works with ForwardMessageProvider (local state) <ForwardMessageProvider> <Composer.Frame> <Composer.Input /> <Composer.Submit /> </Composer.Frame> </ForwardMessageProvider> // Works with ChannelProvider (global synced state) <ChannelProvider channelId="abc"> <Composer.Frame> <Composer.Input /> <Composer.Submit /> </Composer.Frame> </ChannelProvider>

文档还专门讨论了Provider 边界而非视觉嵌套这一点：ForwardMessageDialog里，MessagePreview与ForwardButton都位于Composer.Frame之外、ForwardMessageProvider之内，却能分别读取state.input/state.attachments并调用submit。原文的总结一针见血："UI 是你组合起来的可复用积木，状态由 Provider 依赖注入。换掉 Provider，UI 保持不变（Swap the provider, keep the UI）。"

3.3 将状态管理与 UI 解耦（state-decouple-implementation）

这条规则是前述两点的收束：Provider 组件应当是唯一知道状态如何管理的地方；UI 组件只消费 Context 接口——它们不知道状态来自useState、Zustand 还是服务端同步。

反例展示了 UI 与全局状态实现直接耦合的样子：

function ChannelComposer({ channelId }: { channelId: string }) { // UI component knows about global state implementation const state = useGlobalChannelState(channelId) const { submit, updateInput } = useChannelSync(channelId) return ( <Composer.Frame> <Composer.Input value={state.input} onChange={(text) => sync.updateInput(text)} /> <Composer.Submit onPress={() => sync.submit()} /> </Composer.Frame> ) }

正例则把useGlobalChannel的调用完全收进ChannelProvider，UI 侧的ChannelComposer只剩纯结构声明：

// Provider handles all state management details function ChannelProvider({ channelId, children, }: { channelId: string children: React.ReactNode }) { const { state, update, submit } = useGlobalChannel(channelId) const inputRef = useRef(null) return ( <Composer.Provider state={state} actions={{ update, submit }} meta={{ inputRef }} > {children} </Composer.Provider> ) } // UI component only knows about the context interface function ChannelComposer() { return ( <Composer.Frame> <Composer.Header /> <Composer.Input /> <Composer.Footer> <Composer.Submit /> </Composer.Footer> </Composer.Frame> ) } // Usage function Channel({ channelId }: { channelId: string }) { return ( <ChannelProvider channelId={channelId}> <ChannelComposer /> </ChannelProvider> ) }

这条规则的工程价值在于替换成本被限制在 Provider 一层：从useState迁到外部状态库时，Composer.Input、Composer.Submit等内部件零改动。

四、实现模式（MEDIUM）：显式变体与 children 优先

4.1 创建显式变体组件（patterns-explicit-variants）

与 2.1 节的布尔 prop 问题互为表里：与其维护"一个组件 + N 个布尔模式"，不如为每种场景建立显式变体组件。对比一下调用侧的可读性差异：

// What does this component actually render? <Composer isThread isEditing={false} channelId='abc' showAttachments showFormatting={false} />

// Immediately clear what this renders <ThreadComposer channelId="abc" /> // Or <EditMessageComposer messageId="xyz" /> // Or <ForwardMessageComposer messageId="123" />

每个变体的实现同时自带对应的 Provider，一次性显式声明三件事：使用哪个 Provider/状态、包含哪些 UI 元素、提供哪些动作。以三个完整变体为例：

function ThreadComposer({ channelId }: { channelId: string }) { return ( <ThreadProvider channelId={channelId}> <Composer.Frame> <Composer.Input /> <AlsoSendToChannelField channelId={channelId} /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.Submit /> </Composer.Footer> </Composer.Frame> </ThreadProvider> ) } function EditMessageComposer({ messageId }: { messageId: string }) { return ( <EditMessageProvider messageId={messageId}> <Composer.Frame> <Composer.Input /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.CancelEdit /> <Composer.SaveEdit /> </Composer.Footer> </Composer.Frame> </EditMessageProvider> ) } function ForwardMessageComposer({ messageId }: { messageId: string }) { return ( <ForwardMessageProvider messageId={messageId}> <Composer.Frame> <Composer.Input placeholder="Add a message, if you'd like." /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <Composer.Mentions /> </Composer.Footer> </Composer.Frame> </ForwardMessageProvider> ) }

文档的结论：没有需要推理的布尔组合，也就不存在"不可能的状态"。

4.2 children 优于 render props（patterns-children-over-render-props）

组合静态结构时，优先用children而不是renderXprop。反例中renderHeader/renderFooter/renderActions三个回调 prop 使调用侧冗长且必须理解每个回调签名：

// Usage is awkward and inflexible return ( <Composer renderHeader={() => <CustomHeader />} renderFooter={() => ( <> <Formatting /> <Emojis /> </> )} renderActions={() => <SubmitButton />} /> )

正例改为让ComposerFrame与ComposerFooter都接收children，调用侧回归直观的声明式嵌套：

function ComposerFrame({ children }: { children: React.ReactNode }) { return <form>{children}</form> } function ComposerFooter({ children }: { children: React.ReactNode }) { return <footer className='flex'>{children}</footer> } // Usage is flexible return ( <Composer.Frame> <CustomHeader /> <Composer.Input /> <Composer.Footer> <Composer.Formatting /> <Composer.Emojis /> <SubmitButton /> </Composer.Footer> </Composer.Frame> )

规则同时给出了 render props 的适用边界——当父组件需要向子项回传数据时，render props 反而更合适：

// Render props work well when you need to pass data back <List data={items} renderItem={({ item, index }) => <Item item={item} index={index} />} />

判定标准可以概括为：父组件要向子组件提供数据或状态 → render props；组合静态结构 → children。

五、React 19 API 变更（react19-no-forwardref）

文档以醒目提示声明此条规则仅适用于 React 19+，React 18 及更早版本应跳过。Supabase 仓库的前端 catalog 在 pnpm-workspace.yaml 中统一锁定react: ^19.2.6（各包如 packages/ui/package.json 通过catalog:引用该版本），因此本仓库的 React 代码可以直接按此条规则编写。两条变更：

1.ref成为普通 prop，不再需要forwardRef包裹：

// Incorrect (forwardRef in React 19) const ComposerInput = forwardRef<TextInput, Props>((props, ref) => { return <TextInput ref={ref} {...props} /> }) // Correct (ref as a regular prop) function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) { return <TextInput ref={ref} {...props} /> }

2. 用use()替代useContext()：

// Incorrect (useContext in React 19) const value = useContext(MyContext) // Correct (use instead of useContext) const value = use(MyContext)

文档补充了一个关键差异：use()可以条件调用，而useContext()不行——这在"按需订阅 Context 切片"的场景中是实际能力差异。

从源码结构看，仓库现有 UI 组件（如上文 MenuContext.tsx 的useMenuContext辅助 Hook）目前仍采用createContext+useContext的传统写法，并且通过"脱离 Provider 即抛错"的辅助函数保证了 Context 契约的严格性——这套结构本身与文档推荐的复合组件模式完全兼容；在将这类组件逐步迁移到 React 19 新 API 时，只需把消费侧的useContext(X)替换为use(X)、并在函数组件中直接以refprop 接收引用，即可对齐文档给出的目标形态。

六、模式选型速查与落地建议

将 8 条规则压缩为一份可操作的决策清单：

落地时的三个判断点值得强调：其一，Provider 边界是逻辑边界而非视觉边界——只要位于 Provider 子树内，组件无论渲染在 DOM 的哪个位置都能访问状态与动作；其二，meta通道（如inputRef）让 Provider 可以持有并分发 ref 这类元数据，避免为"焦点管理"再开一条 prop 通道；其三，render props 与 children 并非对立，而是按"是否需要父级回传数据"分工。完整规则文本见各rules/*.md文件，每个文件都包含错误示例、正确示例与上下文说明，可单独引用为团队评审清单。

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase