Supabase React 19 组件实战：ref 作为普通 Props 与 use() 替代 useContext() 的迁移指南

Supabase React 19 组件实战ref 作为普通 Props 与 use() 替代 useContext() 的迁移指南【免费下载链接】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 仓库内 Vercel 组件组合模式技能包中的规则文件 react19-no-forwardref.md系统讲解 React 19 带来的两项 API 变化ref成为普通 prop不再需要forwardRef包装以及use()钩子取代useContext()。Supabase 的 Studio 前端与 UI 组件包packages/ui、packages/ui-patterns运行在 React 19 之上读完本文你将能在自己的 React 19 项目中直接完成组件定义与 Context 消费方式的现代化改造。规则定位与适用范围这条规则出自仓库中为 AI 编码助手组织的技能文档 SKILL.md。该技能包定义了四大类 React 组件组合模式按优先级组织为优先级类别影响程度规则前缀1组件架构Compound Components 等HIGHarchitecture-2状态管理Provider、状态提升等MEDIUMstate-3实现模式显式变体、children 组合等MEDIUMpatterns-4React 19 APIsMEDIUMreact19-react19-no-forwardref属于第四类影响程度impact标注为MEDIUM描述为“更简洁的组件定义与 Context 使用方式”标签涵盖react19、refs、context、hooks。适用前提原文档的核心警告本规则仅适用于 React 19。如果你的项目仍在 React 18 或更早版本应跳过这条规则继续保留forwardRef与useContext()的既有写法。Supabase 仓库当前满足该前提。从 pnpm-workspace.yaml 的 catalog 定义可以看到react: ^19.2.6 react-dom: ^19.2.6 types/react: ^19.2.14 types/react-dom: ^19.2.3各应用与组件包如 apps/studio/package.json、packages/ui/package.json通过react: catalog:引用这一定义Studio 的 AGENTS.md 也明确写明技术栈为 “Next.js pages router TanStack Start迁移中React 19”。因此仓库内的组件代码应当逐步向 React 19 的新 API 收敛。变化一ref 成为普通 prop不再需要 forwardRef问题写法forwardRef 包装在 React 18 及更早版本中函数组件要接收ref必须通过forwardRef高阶函数把 ref 从 props 中“剥出来”// 不推荐React 19 下的遗留写法 const ComposerInput forwardRefTextInput, Props((props, ref) { return TextInput ref{ref} {...props} / })forwardRef带来的代价是组件签名变成高阶函数形式类型参数顺序反直觉forwardRefT, P中 ref 类型在前、props 在后对外导出的组件与内部实现函数割裂displayName、HOC 包装等处理变繁琐无法像普通 props 一样在解构、展开、泛型约束中自然地处理 ref。正确写法ref as a regular propReact 19 中ref被提升为普通 prop函数组件可以直接在参数里声明并接收它// 推荐React 19 function ComposerInput({ ref, ...props }: Props { ref?: React.RefTextInput }) { return TextInput ref{ref} {...props} / }关键点在于类型声明在 props 类型上交叉一个可选的ref?: React.RefTextInput组件既保持普通函数签名又显式表达了 ref 的目标类型。组件内部把ref继续透传给底层的TextInput行为与forwardRef版本完全等价但定义更干净。仓库源码中的印证从源码结构看Supabase 的 UI 模式包中已经存在“把 ref 作为普通 prop 传递”的实现。例如 FilterBarContext.tsx 中FilterBarHandle相关的类型定义里直接以 props 形式声明了ref: React.RefFilterBarHandle这正是规则所倡导的模式ref 不再经过forwardRef通道而是像value、onChange一样在 props 接口中声明与流转。同时应当注意仓库的迁移现状packages/ui下大量源自 shadcn/ui 的组件如 button.tsx仍是forwardRef写法。这属于历史代码并非 React 19 项目的目标形态——forwardRef在 React 19 中依然被保留以保证向后兼容不会报错只是不再必要。判断标准是新编写或重构的组件应使用 ref-as-prop存量代码在触及该组件时顺带迁移即可。变化二use() 取代 useContext()问题写法useContext传统方式下消费 Context 使用useContext()钩子// 不推荐React 19 下的遗留写法 const value useContext(MyContext)正确写法use()React 19 引入的通用use()钩子可以直接读取 Context// 推荐React 19 const value use(MyContext)两者在“读取 Context 当前值”这一场景下功能等价但use()有一个决定性优势原文档明确指出的能力差异useContext()必须无条件调用受 React Hooks 规则约束写在if分支里会破坏 hooks 调用顺序use()可以被条件调用。因为它不是按调用顺序维护内部槽位的传统 hook而是在渲染过程中“按需读取”所以可以安全地放在条件分支内。这意味着诸如“仅在子组件挂载某一层时才消费某个 Context”的逻辑过去需要拆分组件或用useContext的null返回值绕行现在可以用条件式use(MyContext)直接表达。此外use()还统一了对 Promise 和 Context 两种异步数据的读取入口这是 React 19 的通用设计因此从useContext切换到use也是面向未来 API 收敛的顺势迁移。组合迁移实践一次改到位的组件模板把一个典型的“包装输入框 消费某个 Context”的组件迁移到 React 19 风格完整模板如下import { use } from react type Props { disabled?: boolean placeholder?: string } function ComposerInput({ ref, ...props }: Props { ref?: React.RefTextInput }) { // 变化二use() 取代 useContext()且允许条件调用 const settings use(ComposerSettingsContext) if (settings.enabled) { // use() 可以出现在条件分支中 } // 变化一ref 是普通 prop直接透传 return TextInput ref{ref} disabled{settings.disabled ?? props.disabled} {...props} / }迁移时的检查清单对应规则文件的 impact 与 tags组件是否使用了forwardRef改为普通函数 refprop 类型声明是否存在useContext(...)调用替换为use(...)替换后检查ref的类型参数是否与底层 DOM 元素/句柄类型一致如React.RefTextInput确认项目 React 版本 ≥ 19否则第 3 步的refprop 与条件式use()均不可用。与其他组合规则的配合react19-no-forwardref不是孤立规则它与 SKILL.md 中同目录的规则协同构成完整的组件设计体系architecture-compound-components.md复合组件通常依赖共享 Context 传递内部状态——Provider 一侧的createContext保持不变而消费侧统一改用use()state-context-interface.md定义state/actions/meta通用接口做依赖注入读取接口时同样走use()patterns-children-over-render-props.md用 children 组合替代renderX属性避免组件 API 随功能增长而膨胀。换句话说React 19 的两项 API 变化降低了“组合模式”的实施成本ref 透传无需高阶函数、Context 读取可条件化这让architecture-与state-类别中那些强调组合与解耦的模式在 React 19 项目中更加自然。小结维度React 18 及更早React 19本规则推荐函数组件接收 refforwardRefT, P((props, ref) ...)普通函数ref作为 props 声明读取 ContextuseContext(MyContext)必须无条件调用use(MyContext)可条件调用组件签名复杂度高阶函数 反直觉的类型参数顺序普通函数签名类型直观适用版本全部仅 React 19低版本项目跳过对于 Supabase 这类整体运行在 React 19.2 上的仓库这条 MEDIUM 级别的规则是组件新代码与重构的默认约定新组件一律用 ref-as-prop 定义、用use()消费 Context存量的forwardRef/useContext写法可见于 packages/ui/src/components/shadcn/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），仅供参考