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

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 条规则按优先级分为四类这个优先级表本身就是文章的核心骨架优先级类别影响规则前缀1组件架构Component ArchitectureHIGHarchitecture-2状态管理State ManagementMEDIUMstate-3实现模式Implementation PatternsMEDIUMpatterns-4React 19 APIsMEDIUMreact19-每条规则对应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 createContextComposerContextValue | 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-stateHIGH影响让组件边界之外的状态可共享、state-decouple-implementationMEDIUMProvider 是唯一知道状态如何管理的地方、state-context-interfaceHIGH定义 state/actions/meta 三段式泛型接口实现依赖注入。三者构成一条完整推导链先把状态提升进 Provider再定义泛型接口最终让 UI 与状态实现彻底解耦。3.1 把状态提升进 Providerstate-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 ) }正确做法是把状态整体提升到专门的 Providerfunction 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.RefObjectTextInput } interface ComposerContextValue { state: ComposerState actions: ComposerActions meta: ComposerMeta } const ComposerContext createContextComposerContextValue | 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 channelIdabc Composer.Frame Composer.Input / Composer.Submit / /Composer.Frame /ChannelProvider文档还专门讨论了Provider 边界而非视觉嵌套这一点ForwardMessageDialog里MessagePreview与ForwardButton都位于Composer.Frame之外、ForwardMessageProvider之内却能分别读取state.input/state.attachments并调用submit。原文的总结一针见血UI 是你组合起来的可复用积木状态由 Provider 依赖注入。换掉 ProviderUI 保持不变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的调用完全收进ChannelProviderUI 侧的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} channelIdabc showAttachments showFormatting{false} /// Immediately clear what this renders ThreadComposer channelIdabc / // Or EditMessageComposer messageIdxyz / // Or ForwardMessageComposer messageId123 /每个变体的实现同时自带对应的 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 placeholderAdd a message, if youd like. / Composer.Footer Composer.Formatting / Composer.Emojis / Composer.Mentions / /Composer.Footer /Composer.Frame /ForwardMessageProvider ) }文档的结论没有需要推理的布尔组合也就不存在不可能的状态。4.2 children 优于 render propspatterns-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 classNameflex{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 19React 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 forwardRefTextInput, Props((props, ref) { return TextInput ref{ref} {...props} / }) // Correct (ref as a regular prop) function ComposerInput({ ref, ...props }: Props { ref?: React.RefTextInput }) { 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目前仍采用createContextuseContext的传统写法并且通过脱离 Provider 即抛错的辅助函数保证了 Context 契约的严格性——这套结构本身与文档推荐的复合组件模式完全兼容在将这类组件逐步迁移到 React 19 新 API 时只需把消费侧的useContext(X)替换为use(X)、并在函数组件中直接以refprop 接收引用即可对齐文档给出的目标形态。六、模式选型速查与落地建议将 8 条规则压缩为一份可操作的决策清单你遇到的情况应套用的规则组件 prop 中出现第 3 个以上isXxx/showXxx布尔停止加布尔拆分显式变体architecture-avoid-boolean-propspatterns-explicit-variants需要向组件注入多个可定制区域复合组件 children弃用renderXproparchitecture-compound-componentspatterns-children-over-render-props组件内部状态需要被外部兄弟组件读写状态提升到 Providerstate-lift-state同一 UI 要适配多种状态来源本地 / 全局 / 服务端定义state/actions/meta泛型接口UI 只消费接口state-context-interfacestate-decouple-implementation项目使用 React 19移除forwardRefuseContext换use()react19-no-forwardref落地时的三个判断点值得强调其一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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考