Supabase 前端工程实践用复合组件与共享 Context 构建可灵活组合的 React 组件【免费下载链接】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 仓库内沉淀的一条高优先级 React 组件架构规则——复合组件模式——展开如何通过“共享 Context 独立子组件 显式组合”的方式重构臃肿的大型组件消除 render props 与布尔开关带来的复杂度。读完本文你可以掌握该模式的核心结构、配套的状态依赖注入接口设计并在 Supabase 自己的 UI 组件库源码中找到这一模式的真实落地范例。模式解决的问题单体组件的失控原始规则文档首先给出了一个典型的反面示例——一个承担过多职责的单体组件它同时接收renderHeader、renderFooter、renderActions等 render props以及showAttachments、showFormatting、showEmojis等布尔开关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 ) }这个写法的问题在于组件内部用一连串条件分支替消费者做布局决策消费者只能通过“隐藏的逻辑开关”间接影响结构每新增一个可选区域就要增加一个 prop。规则文档将这种模式标记为“Incorrect (monolithic component with render props)”即“带 render props 的单体组件”应当被重构。复合组件模式给出的答案只有两句话把复杂组件拆成一组共享 Context 的复合子组件每个子组件通过 Context 而非 props 访问共享状态消费者按需组合compose自己需要的部件。核心结构Provider、Frame 与子组件规则文档给出的正确实现由三层构成共享 Context一个null初始值的 Context类型承载state、actions、meta三类数据Provider由外部注入依赖负责把这三类数据挂到 Context 上子组件每一个都是独立函数组件通过use(ComposerContext)读取自己需要的部分互不依赖。完整实现摘自原始规则文档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.Frame、Composer.Input这样的命名空间形式对外导出。这是复合组件compound component的标志性 API 形态——类型系统和 IDE 自动补全都能直接反映“这个组件家族里有哪些可用的块”。消费者视角的显式组合使用方得到的是一棵完全受自己控制的 JSX 树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原始规则文档对这一形态的总结值得逐字记住“消费者显式地组合自己恰好需要的东西没有隐藏的条件分支No hidden conditionalsstate、actions、meta 由父级 Provider 依赖注入因此同一套组件结构可以在多处复用。”这正是对单体版本三大痛点的直接回答布局控制权交还消费者Composer.Footer里放什么、放几个Composer.Formatting和Composer.Submit由消费者决定组件内部不再有任何showX X /的分支依赖注入实现复用同一套 UI 结构可以挂在不同的 Provider 之上从而适配本地状态、全局同步状态等完全不同的数据源prop 不再层层下钻子组件之间的协作比如 Submit 读取 input 的 ref全部走 Context父组件无需把 ref、回调在子组件之间穿梭传递。状态接口设计state / actions / meta 三段式契约单靠“拆组件 Context”还不够真正让这套模式可复用的是配套的通用 Context 接口规则。该规则要求把 Context 的值定义为一个“任何 Provider 都可以实现”的通用接口分为三段// 任何 Provider 都可以实现的通用接口 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函数签名使 Provider 既可以包装useState也可以包装全局 store消费方无感知meta不适合归入业务状态的技术性元数据典型如inputRef。关键在于UI 组件消费的是接口而不是某个具体状态实现。错误写法是让ComposerInput直接调用useChannelComposerState()把 UI 绑死在特定 hook 上正确写法是上面接口化之后的use(ComposerContext)。由此同一套Composer.Frame组合可以无缝切换 Provider// Provider A本地状态用于临时表单 ForwardMessageProvider Composer.Frame Composer.Input / Composer.Submit / /Composer.Frame /ForwardMessageProvider // Provider B全局同步状态用于频道消息 ChannelProvider channelIdabc Composer.Frame Composer.Input / Composer.Submit / /Composer.Frame /ChannelProvider该规则还点明了 Provider 边界与视觉嵌套的区别“真正重要的是 Provider 边界而不是视觉嵌套”。只要位于 Provider 内部组件就能访问共享状态哪怕它在视觉上处于Composer.Frame之外——例如对话框底部的ForwardButton依然可以调用actions.submit消息预览区可以读取state.input做实时预览。这是把状态提升到 Providerlift state之后的直接收益同一 Skill 目录下的 state-lift-state 规则 对此有独立论述。Supabase 组件库中的真实落地Menu 复合组件该模式在 Supabase 仓库自身的前端代码中就有完整实例。Supabase 的 UI 组件库packages/ui中的 Menu 组件 正是按“Provider 共享 Context 子组件挂载”的复合组件结构实现的。MenuContext.tsx 定义了共享 Context 与消费辅助 hookinterface ContextProps { type: text | pills | border } // Make sure the shape of the default value passed to // createContext matches the shape that the consumers expect! const MenuContext createContextContextProps({ type: text, }) export const MenuContextProvider (props: Provider) { const { type } props const value { type } return MenuContext.Provider value{value}{props.children}/MenuContext.Provider } // context helper to avoid using a consumer component export const useMenuContext () { const context useContext(MenuContext) if (context undefined) { throw new Error(MenuContext must be used within a MenuContextProvider.) } return context }这个实现里有两处值得对照规则文档注意的细节Context 默认值形状与消费方期望一致源码注释明确强调“确保传给createContext的默认值形状与消费方期望的形状匹配”MenuContext.tsx L13-L17。规则文档采用的createContextComposerContextValue | null(null)是“null 强制 Provider”风格而 Menu 采用“合理默认值”风格二者都是合法选择但默认值形状错误例如默认给{}会导致消费方解构出undefined的类型与运行时陷阱——这一点在 Supabase 的 IconContext.tsx 中被再次强调其默认值{ contextSize: small, className: }完整覆盖了ContextValue的所有字段辅助 hook 做边界守卫useMenuContext在 Context 缺失时抛出明确错误MenuContext must be used within a MenuContextProvider.把“忘记包裹 Provider”这类配置错误提前暴露而不是在渲染时静默退化。再看组合方 Menu.tsx根组件负责渲染语义化的nav rolemenu结构并包裹 ProviderMenu.tsx L17-L32而Item与Group子组件各自通过useMenuContext()读取type用它驱动class-variance-authority的变体样式Menu.tsx L101-L107export function Item({ children, icon, active, onClick, style, className }: ItemProps) { const { type } useMenuContext() return ( li rolemenuitem className{cn(outline-hidden, menuItemVariants({ type, active }), className)} ...最后通过把子组件挂载到根组件上来完成复合组件导出Menu.tsx L155-L156Menu.Item Item Menu.Group Group export default Menu这与规则文档中const Composer { Provider, Frame, Input, ... }的对象字面量写法等价只是采用了“给函数组件动态附加属性”的更传统写法最终对外 API 形态一致Menu typepillsMenu.ItemMenu.Group。从源码结构看Menu 是一个轻量版示范它的 Context 只承载type一个样式维度而非完整的 state/actions 契约因此子组件无需行为协作但当需要跨子组件共享行为如submit读取inputRef时就应当升级到三段式接口。这也印证了SKILL.md 中对规则的分层定位复合组件属于最高优先级的 Component Architecture 类HIGH 影响而三段式 Context 接口、状态提升属于 State Management 类MEDIUM两者叠加才能支撑完整场景。React 19 适配use() 与 ref-as-prop规则文档中的示例使用了use(ComposerContext)而非useContext这不是风格偏好而是 React 19 API 的适配要求。同目录的 react19-no-forwardref 规则 说明了两点仅限 React 19React 18 及更早版本不适用// React 19use() 取代 useContext()且 use() 可以条件调用 const value use(MyContext) // React 19ref 是普通 prop不再需要 forwardRef 包装 function ComposerInput({ ref, ...props }: Props { ref?: React.RefTextInput }) { return TextInput ref{ref} {...props} / }复合组件中meta.inputRef这类“把 ref 放入 Context”的用法在 React 19 下更加顺畅子组件可以直接把 ref 当普通 prop 透传给底层输入框不需要任何forwardRef包装层。如果你的代码库仍在 React 18同样的模式可用useContext与forwardRef等价实现架构层面没有任何差异。模式取舍与落地检查清单回到规则文档的 frontmatter该模式被标注为impact: HIGH收益描述为 “enables flexible composition without prop drilling”实现灵活组合无需 prop 下钻。落地时可以用如下清单自检组件内是否出现showX X /分支或renderXprops有则说明布局决策泄漏进了组件内部应拆为复合子组件把选择权交还消费者的 JSX 树是否存在跨层级传递 ref/回调的 prop 链把这类“技术元数据”收敛进 Provider 注入的meta行为收敛进actions数据快照收敛进stateContext 是否有 Provider 边界守卫参照 MenuContext.tsx 的抛错式 hook 或null初始值 断言避免静默失败子组件是否通过命名空间导出Composer.Frame/Menu.Item这类点号 API 是复合组件对外的契约也是可读文档本身是否需要同一 UI 对接多种状态源若是严格按接口规则定义ComposerContextValue让 Provider 而非 UI 组件承载状态实现的差异——“换 ProviderUI 不动”。需要说明的前提本文所引用的规则文件位于.claude/skills/vercel-composition-patterns/目录是仓库为 AI 编码代理与开发者共同维护的 React 组合模式规范其 frontmatter 标注 author 为 vercel、MIT license、version 1.0.0Menu、Icon等组件则是 Supabase 前端Studio 与 UI 组件库正在使用的真实实现二者相互印证了这套模式在该代码库中的实际地位。【免费下载链接】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），仅供参考 Supabase 前端工程实践：用复合组件与共享 Context 构建可灵活组合的 React 组件
Supabase 前端工程实践用复合组件与共享 Context 构建可灵活组合的 React 组件【免费下载链接】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 仓库内沉淀的一条高优先级 React 组件架构规则——复合组件模式——展开如何通过“共享 Context 独立子组件 显式组合”的方式重构臃肿的大型组件消除 render props 与布尔开关带来的复杂度。读完本文你可以掌握该模式的核心结构、配套的状态依赖注入接口设计并在 Supabase 自己的 UI 组件库源码中找到这一模式的真实落地范例。模式解决的问题单体组件的失控原始规则文档首先给出了一个典型的反面示例——一个承担过多职责的单体组件它同时接收renderHeader、renderFooter、renderActions等 render props以及showAttachments、showFormatting、showEmojis等布尔开关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 ) }这个写法的问题在于组件内部用一连串条件分支替消费者做布局决策消费者只能通过“隐藏的逻辑开关”间接影响结构每新增一个可选区域就要增加一个 prop。规则文档将这种模式标记为“Incorrect (monolithic component with render props)”即“带 render props 的单体组件”应当被重构。复合组件模式给出的答案只有两句话把复杂组件拆成一组共享 Context 的复合子组件每个子组件通过 Context 而非 props 访问共享状态消费者按需组合compose自己需要的部件。核心结构Provider、Frame 与子组件规则文档给出的正确实现由三层构成共享 Context一个null初始值的 Context类型承载state、actions、meta三类数据Provider由外部注入依赖负责把这三类数据挂到 Context 上子组件每一个都是独立函数组件通过use(ComposerContext)读取自己需要的部分互不依赖。完整实现摘自原始规则文档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.Frame、Composer.Input这样的命名空间形式对外导出。这是复合组件compound component的标志性 API 形态——类型系统和 IDE 自动补全都能直接反映“这个组件家族里有哪些可用的块”。消费者视角的显式组合使用方得到的是一棵完全受自己控制的 JSX 树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原始规则文档对这一形态的总结值得逐字记住“消费者显式地组合自己恰好需要的东西没有隐藏的条件分支No hidden conditionalsstate、actions、meta 由父级 Provider 依赖注入因此同一套组件结构可以在多处复用。”这正是对单体版本三大痛点的直接回答布局控制权交还消费者Composer.Footer里放什么、放几个Composer.Formatting和Composer.Submit由消费者决定组件内部不再有任何showX X /的分支依赖注入实现复用同一套 UI 结构可以挂在不同的 Provider 之上从而适配本地状态、全局同步状态等完全不同的数据源prop 不再层层下钻子组件之间的协作比如 Submit 读取 input 的 ref全部走 Context父组件无需把 ref、回调在子组件之间穿梭传递。状态接口设计state / actions / meta 三段式契约单靠“拆组件 Context”还不够真正让这套模式可复用的是配套的通用 Context 接口规则。该规则要求把 Context 的值定义为一个“任何 Provider 都可以实现”的通用接口分为三段// 任何 Provider 都可以实现的通用接口 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函数签名使 Provider 既可以包装useState也可以包装全局 store消费方无感知meta不适合归入业务状态的技术性元数据典型如inputRef。关键在于UI 组件消费的是接口而不是某个具体状态实现。错误写法是让ComposerInput直接调用useChannelComposerState()把 UI 绑死在特定 hook 上正确写法是上面接口化之后的use(ComposerContext)。由此同一套Composer.Frame组合可以无缝切换 Provider// Provider A本地状态用于临时表单 ForwardMessageProvider Composer.Frame Composer.Input / Composer.Submit / /Composer.Frame /ForwardMessageProvider // Provider B全局同步状态用于频道消息 ChannelProvider channelIdabc Composer.Frame Composer.Input / Composer.Submit / /Composer.Frame /ChannelProvider该规则还点明了 Provider 边界与视觉嵌套的区别“真正重要的是 Provider 边界而不是视觉嵌套”。只要位于 Provider 内部组件就能访问共享状态哪怕它在视觉上处于Composer.Frame之外——例如对话框底部的ForwardButton依然可以调用actions.submit消息预览区可以读取state.input做实时预览。这是把状态提升到 Providerlift state之后的直接收益同一 Skill 目录下的 state-lift-state 规则 对此有独立论述。Supabase 组件库中的真实落地Menu 复合组件该模式在 Supabase 仓库自身的前端代码中就有完整实例。Supabase 的 UI 组件库packages/ui中的 Menu 组件 正是按“Provider 共享 Context 子组件挂载”的复合组件结构实现的。MenuContext.tsx 定义了共享 Context 与消费辅助 hookinterface ContextProps { type: text | pills | border } // Make sure the shape of the default value passed to // createContext matches the shape that the consumers expect! const MenuContext createContextContextProps({ type: text, }) export const MenuContextProvider (props: Provider) { const { type } props const value { type } return MenuContext.Provider value{value}{props.children}/MenuContext.Provider } // context helper to avoid using a consumer component export const useMenuContext () { const context useContext(MenuContext) if (context undefined) { throw new Error(MenuContext must be used within a MenuContextProvider.) } return context }这个实现里有两处值得对照规则文档注意的细节Context 默认值形状与消费方期望一致源码注释明确强调“确保传给createContext的默认值形状与消费方期望的形状匹配”MenuContext.tsx L13-L17。规则文档采用的createContextComposerContextValue | null(null)是“null 强制 Provider”风格而 Menu 采用“合理默认值”风格二者都是合法选择但默认值形状错误例如默认给{}会导致消费方解构出undefined的类型与运行时陷阱——这一点在 Supabase 的 IconContext.tsx 中被再次强调其默认值{ contextSize: small, className: }完整覆盖了ContextValue的所有字段辅助 hook 做边界守卫useMenuContext在 Context 缺失时抛出明确错误MenuContext must be used within a MenuContextProvider.把“忘记包裹 Provider”这类配置错误提前暴露而不是在渲染时静默退化。再看组合方 Menu.tsx根组件负责渲染语义化的nav rolemenu结构并包裹 ProviderMenu.tsx L17-L32而Item与Group子组件各自通过useMenuContext()读取type用它驱动class-variance-authority的变体样式Menu.tsx L101-L107export function Item({ children, icon, active, onClick, style, className }: ItemProps) { const { type } useMenuContext() return ( li rolemenuitem className{cn(outline-hidden, menuItemVariants({ type, active }), className)} ...最后通过把子组件挂载到根组件上来完成复合组件导出Menu.tsx L155-L156Menu.Item Item Menu.Group Group export default Menu这与规则文档中const Composer { Provider, Frame, Input, ... }的对象字面量写法等价只是采用了“给函数组件动态附加属性”的更传统写法最终对外 API 形态一致Menu typepillsMenu.ItemMenu.Group。从源码结构看Menu 是一个轻量版示范它的 Context 只承载type一个样式维度而非完整的 state/actions 契约因此子组件无需行为协作但当需要跨子组件共享行为如submit读取inputRef时就应当升级到三段式接口。这也印证了SKILL.md 中对规则的分层定位复合组件属于最高优先级的 Component Architecture 类HIGH 影响而三段式 Context 接口、状态提升属于 State Management 类MEDIUM两者叠加才能支撑完整场景。React 19 适配use() 与 ref-as-prop规则文档中的示例使用了use(ComposerContext)而非useContext这不是风格偏好而是 React 19 API 的适配要求。同目录的 react19-no-forwardref 规则 说明了两点仅限 React 19React 18 及更早版本不适用// React 19use() 取代 useContext()且 use() 可以条件调用 const value use(MyContext) // React 19ref 是普通 prop不再需要 forwardRef 包装 function ComposerInput({ ref, ...props }: Props { ref?: React.RefTextInput }) { return TextInput ref{ref} {...props} / }复合组件中meta.inputRef这类“把 ref 放入 Context”的用法在 React 19 下更加顺畅子组件可以直接把 ref 当普通 prop 透传给底层输入框不需要任何forwardRef包装层。如果你的代码库仍在 React 18同样的模式可用useContext与forwardRef等价实现架构层面没有任何差异。模式取舍与落地检查清单回到规则文档的 frontmatter该模式被标注为impact: HIGH收益描述为 “enables flexible composition without prop drilling”实现灵活组合无需 prop 下钻。落地时可以用如下清单自检组件内是否出现showX X /分支或renderXprops有则说明布局决策泄漏进了组件内部应拆为复合子组件把选择权交还消费者的 JSX 树是否存在跨层级传递 ref/回调的 prop 链把这类“技术元数据”收敛进 Provider 注入的meta行为收敛进actions数据快照收敛进stateContext 是否有 Provider 边界守卫参照 MenuContext.tsx 的抛错式 hook 或null初始值 断言避免静默失败子组件是否通过命名空间导出Composer.Frame/Menu.Item这类点号 API 是复合组件对外的契约也是可读文档本身是否需要同一 UI 对接多种状态源若是严格按接口规则定义ComposerContextValue让 Provider 而非 UI 组件承载状态实现的差异——“换 ProviderUI 不动”。需要说明的前提本文所引用的规则文件位于.claude/skills/vercel-composition-patterns/目录是仓库为 AI 编码代理与开发者共同维护的 React 组合模式规范其 frontmatter 标注 author 为 vercel、MIT license、version 1.0.0Menu、Icon等组件则是 Supabase 前端Studio 与 UI 组件库正在使用的真实实现二者相互印证了这套模式在该代码库中的实际地位。【免费下载链接】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），仅供参考