React forwardRef转发ref到子组件DOM元素的用法

在 React 组件开发中，父组件默认无法直接获取子组件内部的 DOM 元素（如 input、button 或 div）。React 会自动封装子组件，导致 ref 属性失效。为了突破这一限制，必须使用 React.forwardRef API 将 ref 从父组件透传到子组件的指定 DOM 节点上。

以下步骤将详细讲解如何在不同场景下实现 ref 转发。

一、 基础用法：创建可转发的子组件

首先需要创建一个能够接收 ref 并将其绑定到内部 DOM 元素的子组件。

1. 引入 forwardRef。
   在组件文件顶部，从 react 库中解构出 forwardRef。

   import React, { forwardRef } from 'react';

2. 定义组件函数并接收第二个参数 ref。
   普通函数组件只接收 props 参数，使用 forwardRef 包裹后，函数会接收第二个参数 ref。

   const MyInput = forwardRef((props, ref) => {
     // 组件逻辑
   });

3. 绑定 ref 到具体的 JSX 元素。
   在返回的 JSX 中，将接收到的 ref 参数传递给目标原生 DOM 元素的 ref 属性。

   const MyInput = forwardRef((props, ref) => {
     return (
       <div className="input-wrapper">
         {/* 将 ref 转发到底层的 input 元素 */}
         <input ref={ref} type="text" {...props} />
       </div>
     );
   });

4. 导出该组件。
   记得导出使用 forwardRef 包裹后的组件，以便其他文件使用。

   export default MyInput;

为了直观理解数据流向，请参考以下流程图：

二、 进阶用法：在父组件中使用转发后的 Ref

子组件准备好后，需要在父组件中创建 ref 并将其传递给子组件。

1. 创建 Ref 对象。
   在父组件中调用 useRef Hook 来初始化一个 ref。

   import React, { useRef } from 'react';
   
   const ParentComponent = () => {
     const inputRef = useRef(null);
   
     return (
       // ...JSX
     );
   };

2. 挂载 Ref 到子组件。
   像传递普通属性一样，将 inputRef 作为 ref 属性传递给子组件标签。

   // 在父组件的 JSX 中
   <MyInput ref={inputRef} placeholder="请输入内容" />

3. 操作 DOM 元素。
   现在，inputRef.current 将直接指向子组件内部的 <input> DOM 节点。可以通过事件处理函数来验证这一点。

   const handleFocus = () => {
     // 直接调用 DOM API
     inputRef.current.focus();
     console.log(inputRef.current.value); // 读取输入值
   };
   
   return (
     <div>
       <MyInput ref={inputRef} />
       <button onClick={handleFocus}>聚焦输入框</button>
     </div>
   );

三、 高阶组件（HOC）中的 Ref 转发

在实际项目中，组件常被高阶组件（如 Redux 的 connect、React Router 的 withRouter 或样式库的 styled）包裹。如果直接包裹，ref 会指向 HOC 返回的容器组件，而不是原始组件，导致转发失效。

假设有一个简单的日志高阶组件 withLog：

function withLog(WrappedComponent) {
  return (props) => {
    console.log('Props:', props);
    return <WrappedComponent {...props} />;
  };
}

如果不做处理，ref 会丢失。正确的做法如下：

1. 使用 forwardRef 包裹 HOC 的返回函数。
   HOC 本身需要接收 ref 参数，并将其传递给被包裹的组件。

   import React, { forwardRef } from 'react';
   
   function withLog(WrappedComponent) {
     // 使用 forwardRef 包裹 HOC 返回的组件
     return forwardRef((props, ref) => {
       console.log('Props:', props);
       // 将 ref 透传给原始组件
       return <WrappedComponent {...props} ref={ref} />;
     });
   }

2. 修改组件显示名称（可选但推荐）。
   为了调试方便，建议设置 displayName。

   withLog.displayName = `withLog(${WrappedComponent.displayName || WrappedComponent.name})`;

3. 组合使用。
   现在可以安全地组合使用：

   const LoggedInput = withLog(MyInput);
   
   // 在父组件中
   const ref = useRef(null);
   <LoggedInput ref={ref} /> // ref 依然能指向 MyInput 内部的 input

四、 TypeScript 类型定义（类型安全）

在 TypeScript 环境下，必须为 forwardRef 定义正确的泛型类型，以确保 ref.current 拥有正确的类型提示。

1. 定义 Props 和 Ref 的泛型参数。
   forwardRef 接受两个泛型：<RefType, PropsType>。

   import React, { forwardRef } from 'react';
   
   // 1. 定义 Props 类型
   interface MyInputProps {
     label?: string;
     defaultValue?: string;
   }
   
   // 2. 定义组件，泛型第一个是 ref 指向的元素类型，第二个是 props 类型
   const MyInput = forwardRef<HTMLInputElement, MyInputProps>((props, ref) => {
     const { label, defaultValue, ...rest } = props;
   
     return (
       <div style={{ marginBottom: '10px' }}>
         {label && <label>{label}</label>}
         {/* ref 现在会被识别为 HTMLInputElement */}
         <input 
           ref={ref} 
           defaultValue={defaultValue} 
           {...rest} 
           style={{ padding: '5px' }}
         />
       </div>
     );
   });
   
   // 必须显式设置 displayName，否则在 devTools 中显示为 ForwardRef
   MyInput.displayName = 'MyInput';
   
   export default MyInput;

2. **在父组件中获取类型提示。
   当创建 ref 时，TypeScript 会自动推断类型，或者你可以显式声明。

   const inputRef = useRef<HTMLInputElement>(null);
   
   const handleClick = () => {
     if (inputRef.current) {
       // 这里会有完整的 HTMLInputElement 方法提示
       inputRef.current.focus(); 
       inputRef.current.select();
     }
   };

五、 常见错误与排查

在使用 forwardRef 时，极易出现因为对 Ref 机制理解不深导致的错误。下表列出了最常见的问题及其解决方案。

注意：在函数组件内部，不要试图从 props 中解构出 ref。ref 不是一个标准的 prop，它会被 React 特殊处理。

// ❌ 错误做法
const MyComponent = (props) => {
  const { ref } = props; // ref 永远是 undefined
  return <div {...props} />;
};

// ✅ 正确做法
const MyComponent = forwardRef((props, ref) => {
  return <div ref={ref} {...props} />;
});