# 从forwardRef迁移到Ref作为Prop * 用户提及 `forwardRef`、refs 或 ref 转发 * 查看使用 `React.forwardRef` 的代码 * 组件升级至React 19 * 需要从自定义组件公开 DOM 引用 * 关于 ref props 的 TypeScript 错误 **为什么改变：** 1. **更简单的 API** \- Refs 只是 props，不需要特殊的包装器 2. **更好的 TypeScript** \- 更轻松的类型推断和输入 3. **一致性** \- 所有道具都以相同的方式处理 4. **更少的样板** \- 更少的导入和包装函数 **迁移路径：** * `forwardRef` 在 React 19 中仍然有效（已弃用，未删除） * 新代码应该使用 ref 作为 prop * 建议对现有代码库逐步迁移 **主要区别：** // 旧：forwardRef（已弃用） const Button =forwardRef((props, ref) => ...); // 新：ref 作为 prop（React 19）函数按钮({ ref, ...props }) { ... } **第 1 步：识别forwardRef 用法** 在代码库中搜索“forwardRef”： # 使用 Grep 工具模式：“forwardRef” 输出模式：“文件匹配” **第 2 步：了解当前模式** 之前（反应 18）：从'react'导入{forwardRef}； const MyButton =forwardRef((props, ref) => { 返回（ <按钮 ref={ref} className={props.className}> {props.children} ）； }); **第 3 步：转换为 Ref 作为 Prop** 之后（反应 19）：函数 MyButton({ 子级, 类名, ref }) { 返回（ <按钮 ref={ref} className={className}> {孩子} ）； } **步骤 4：更新 TypeScript 类型（如果适用）** 之前：从'react'导入{forwardRef}；接口 ButtonProps { 变体：“主要” | “次要”；孩子：React.ReactNode； } const Button =forwardRef( ({ 变体, 子级 }, ref) => { 返回（ <按钮 ref={ref} className={variant}> {孩子} ）； } ）；之后：从 'react' 导入 { Ref } ；接口 ButtonProps { 变体：“主要” | “次要”；孩子：React.ReactNode； ref?: Ref; } 函数 Button({ 变量, 子元素, ref }: ButtonProps) { 返回（ <按钮 ref={ref} className={variant}> {孩子} ）； } **步骤 5：测试组件** 验证引用转发仍然有效：函数父级（）{ const buttonRef = useRef(null); 使用效果（（）=> { ButtonRef.current?.focus(); }, []); return ; } **如果组件使用useImperativeHandle:** 之前： const FancyInput =forwardRef((props, ref) => { const inputRef = useRef(); useImperativeHandle(参考, () => ({ 焦点: () => inputRef.current.focus(), 清除：() => { inputRef.current.value = ''; } })); 返回 ; }); 之后：函数 FancyInput({ ref }) { const inputRef = useRef(); useImperativeHandle(参考, () => ({ 焦点: () => inputRef.current.focus(), 清除：() => { inputRef.current.value = ''; } })); 返回 ; } **如果组件有多个引用：** 函数 ComplexComponent({ ref, innerRef, ...props }) { 返回（

）； } **如果使用通用组件：** 接口 GenericProps { 值：T； ref?: Ref; } 函数 GenericComponent({ value, ref }: GenericProps) { 返回

{String(value)}

; } 详细信息： * **参考清理函数** ：参见`../../../research/react-19-compressive.md`（第1013-1033行） * **useImperativeHandle** ：参见`../../../research/react-19-compressive.md`（第614-623行） * **TypeScript 迁移** ：参见 `../../../research/react-19-compressive.md`（第 890-916 行） * **完整迁移指南** ：参见`../../../research/react-19-compressive.md`（第978-1011行）当需要特定模式时加载参考。 **之前（带有forwardRef的React 18）：** 从'react'导入{forwardRef}； const Button =forwardRef((props, ref) => ( <按钮 ref={ref} {...props}> {props.children} ））； Button.displayName = '按钮'; 导出默认按钮； **之后（带有 ref 属性的 React 19）：** 函数按钮({children, ref, ...props }) { 返回（ <按钮 ref={ref} {...props}> {孩子} ）； } 导出默认按钮； **所做的更改：** 1. ✅ 删除了 `forwardRef` 导入 2. ✅ 删除了 `forwardRef` 包装器 3. ✅ 在 props 解构中添加 `ref` 4. ✅ 删除了不必要的 `displayName` 5. ✅ 简化的函数签名 ## 示例 2：具有多个 Props 的 TypeScript 组件 **之前：** 从'react'导入{forwardRef，HTMLAttributes}；接口 CardProps 扩展 HTMLAttributes { 标题：字符串；描述？：字符串；变体？： '默认' | “概述”； } const Card =forwardRef( ({ 标题、描述、变体 = '默认', ...props }, ref) => { 返回（

{标题}

{描述&&

{描述}

}

）； } ）； Card.displayName = '卡片'; 导出默认卡； **之后：** 从 'react' 导入 { Ref, HTMLAttributes }; 接口 CardProps 扩展 HTMLAttributes { 标题：字符串；描述？：字符串；变体？： '默认' | “概述”； ref?: Ref; } 功能卡({ 标题，描述，变体='默认'，参考， ...道具 }: CardProps) { 返回（

{标题}

{描述&&

{描述}

}

）； } 导出默认卡； **所做的更改：** 1. ✅ 将导入从 `forwardRef` 更改为 `Ref` 类型 2. ✅ 在界面中添加 `ref?: Ref` 3. ✅ 删除了 `forwardRef` 包装器 4. ✅ 在 props 解构中添加了 `ref` 5. ✅ 删除了 `displayName` ## 示例 3：使用 useImperativeHandle 输入 **之前：** 从'react'导入{forwardRef，useRef，useImperativeHandle}； const SearchInput =forwardRef((props, ref) => { const inputRef = useRef(); useImperativeHandle(参考, () => ({ 焦点（）{ inputRef.current?.focus(); }, 清除（）{ inputRef.current.value = ''; }, 获取值() { 返回 inputRef.current?.value || ''; } })); 返回（ <输入参考={输入参考} 类型=“文本” 占位符=“搜索...” {...道具} /> ）； }); 导出默认的SearchInput； **之后：** 从 'react' 导入 { useRef, useImperativeHandle }; 函数 SearchInput({ ref, ...props }) { const inputRef = useRef(); useImperativeHandle(参考, () => ({ 焦点（）{ inputRef.current?.focus(); }, 清除（）{ inputRef.current.value = ''; }, 获取值() { 返回 inputRef.current?.value || ''; } })); 返回（ <输入参考={输入参考} 类型=“文本” 占位符=“搜索...” {...道具} /> ）； } 导出默认的SearchInput； **用法（不变）：** 函数搜索栏（）{ const searchRef = useRef(); 常量handleClear = () => { searchRef.current?.clear(); }; 返回（ <> ）； } ## 示例 4：组件库模式 **之前：** 从'react'导入{forwardRef，ComponentPropsWithoutRef，ElementRef}；类型 ButtonElement = ElementRef<'按钮'>; 类型 ButtonProps = ComponentPropsWithoutRef<'button'> & { 变体？： '主要' | “次要”； }; const Button =forwardRef( ({ 变体 = 'primary', className, ...props }, ref) => { 返回（ <按钮参考={参考} 类名={`btn btn-${变体} ${类名|| ''}`} {...道具} /> ）； } ）； Button.displayName = '按钮'; **之后：** 从 'react' 导入 { Ref, ComponentPropsWithoutRef, ElementRef }; 类型 ButtonElement = ElementRef<'按钮'>; 类型 ButtonProps = ComponentPropsWithoutRef<'button'> & { 变体？： '主要' | “次要”； ref?: Ref; }; 功能按钮({ 变体='主要'，类名, 参考， ...道具 }: 按钮属性) { 返回（ <按钮参考={参考} 类名={`btn btn-${变体} ${类名|| ''}`} {...道具} /> ）； } * 使用 TypeScript 时将 `ref` 添加到 props 接口 * 使用 React for TypeScript 中的 `Ref` 类型 * 测试迁移后引用转发是否有效 * 准确地维护组件行为（仅语法更改） ## 应该 * 逐步迁移组件（forwardRef 仍然有效） * 更新测试以验证引用行为 * 使用一致的道具排序（参考其他元素道具附近） * 如果公共 API 的一部分，则记录重大更改 ## 从不 * 如果仍在 React 18 上，请删除 `forwardRef` * 在迁移过程中更改组件行为 * 打破父组件中现有的引用用法 * 跳过 ref 属性的 TypeScript 类型更新 1. **验证参考转发**： const ref = useRef(null); // ref.current 应该是 DOM 元素 2. **检查 TypeScript 编译**： npx tsc --noEmit 没有关于 ref props 的错误 3. **测试组件行为**： * 组件正确渲染 * Ref 访问正确的 DOM 元素 * useImperativeHandle 方法有效（如果使用） * 没有关于已弃用 API 的控制台警告 4. **验证向后兼容性**： * 现有用法仍然有效 * 组件 API 没有重大变化 * 测试通过 ** ** ## 迁移清单从forwardRef迁移组件时： * 删除`forwardRef`导入 * 删除 `forwardRef` 包装函数 * 在 props 解构中添加 `ref` * 将 `ref` 类型添加到 TypeScript 接口（如果适用） * 如果仅用于forwardRef，则删除`displayName` * 测试参考转发工作 * 更新组件测试 * 检查 TypeScript 编译 * 验证 API 没有重大更改 ## 常见迁移模式 ### 模式 1：简单引用转发 // 之前 const Comp =forwardRef((props, ref) =>

); // 之后函数 Comp({ ref }) { return

; } ### 模式 2：使用 useImperativeHandle // 之前 const Comp =forwardRef((props, ref) => { useImperativeHandle(ref, () => ({ method() {} })); 返回

； }); // 之后函数 Comp({ ref }) { useImperativeHandle(ref, () => ({ method() {} })); 返回

； } ### 模式 3：带有泛型的 TypeScript // 之前 const Comp =forwardRef((props, ref) => ...); // 之后 function Comp({ ref, ...props }: Props & { ref?: Ref }) { ... } 有关完整的forwardRef迁移文档，请参阅：“research/react-19-compressive.md”第978-1033行。 ## 引用清理函数（React 19 中的新增功能） React 19 支持 ref 回调中的清理函数：

{ console.log('已连接：', 节点); 返回（）=> { console.log('断开连接：', 节点); }; }} /> **当清理运行时：** * 组件卸载 * 引用更改为不同的元素这适用于 ref-as-prop 和旧的forwardRef 模式。

从 Forwardref 迁移

包含技能