核心问题：React 的“单向数据流”限制
React 设计的核心原则是单向数据流（父组件通过 props 给子组件传值/方法），默认情况下：
-
子组件的 DOM 节点/组件实例是私有的，父组件无法直接访问
-
父组件不能直接调用子组件的方法、操作子组件的 DOM 但实际开发中，我们偶尔会有“父组件需要直接控制子组件”的场景（比如：让子组件的输入框聚焦、手动触发子组件的重置逻辑），这就是
forwardRef和useImperativeHandle要解决的核心问题。 -
antd等组件库的 Modal/Drawer 等组件本质是封装后的自定义组件，默认遵循 React 单向数据流，但为了让开发者更便捷地控制组件（比如手动触发打开 / 关闭、销毁实例），需要对外暴露特定方法，这就需要：-
forwardRef：让开发者传递的 ref 能穿透 antd 组件的外层封装，指向内部的核心实例 / 方法；
-
useImperativeHandle：只暴露开发者需要的方法（如 close、update），隐藏内部的 DOM 节点、私有状态等，避免暴露过多无关内容。
-
1. forwardRef：解决“Ref 穿透”问题
问题背景
当你给一个自定义子组件绑定 ref 时，默认情况下，函数组件不仅不能通过 props 接收 ref，React 甚至不会把 ref 当作普通 props 传递给函数组件，而是会直接忽略（更准确的是 “丢弃”）这个 ref，同时还会在控制台给出警告。
举个例子（问题场景）
// 子组件
const Input = (props) => {
return <input type="text" />;
};
// 父组件
const Parent = () => {
const inputRef = useRef(null);
// 想让输入框聚焦，但 ref 指向的是 Input 组件本身，不是内部的 input 节点
const focusInput = () => {
console.log(inputRef.current) // 函数组件本身没有实例，所以是undefined
inputRef.current.focus(); // 报错：focus is not a function
};
return (
<div>
<Input ref={inputRef} />
<button onClick={focusInput}>聚焦输入框</button>
</div>
);
};
forwardRef 的解决方案
forwardRef 可以把父组件传递过来的 ref 转发到子组件内部的 DOM 节点/组件实例上，让 ref 能“穿透”自定义组件，指向真正的目标。
// 子组件：用 forwardRef 接收 ref 并转发给内部 input
const Input = forwardRef((props, ref) => {
return <input type="text" ref={ref} />;
});
// 父组件：此时 ref 直接指向 input 节点，能正常调用 focus 方法
const Parent = () => {
const inputRef = useRef(null);
const focusInput = () => {
inputRef.current.focus(); // 正常生效
};
return (
<div>
<Input ref={inputRef} />
<button onClick={focusInput}>聚焦输入框</button>
</div>
);
};
2. useImperativeHandle：解决“暴露过多”的问题
问题背景
- 如果仅用
forwardRef，父组件拿到的是子组件完整的 DOM 节点/组件实例，会暴露很多不必要的属性/方法（比如 input 节点的value、style、blur等），违反“最小暴露原则”，也增加了耦合风险。 - 甚至可能会调用子组件不期望被调用的DOM方法，破坏子组件的封装。
- 期望暴露更高级别的自定义API
useImperativeHandle 的解决方案
useImperativeHandle 可以自定义父组件能访问到的属性/方法，只暴露需要的部分，让代码更安全、更可控。
完整示例
useImperativeHandle 的三个参数核心要点：
ref：接收forwardRef转发过来的父组件ref，是要自定义的目标；createHandle：返回自定义的暴露对象，控制父组件能访问的内容；deps：依赖项数组，控制createHandle的重新执行时机，优化性能。
useImperativeHandle 必须和 forwardRef 配合使用，单独使用无意义；依赖项数组的规则和 useEffect 完全一致，传对依赖才能保证功能正确且性能最优。
import { forwardRef, useRef, useImperativeHandle } from 'react';
// 子组件：仅暴露 focus 和 clear 方法给父组件
const Input = forwardRef((props, ref) => {
// 内部真正的 ref
const innerInputRef = useRef(null);
const [value, setValue] = useState('初始值');
// 自定义要暴露给父组件的方法/属性
useImperativeHandle(ref, () => ({
// 暴露聚焦方法
focus: () => {
innerInputRef.current.focus();
},
// 暴露清空方法
clear: () => {
innerInputRef.current.value = '';
},
// 暴露内部属性
value: value
// 不暴露 value、blur、style 等其他属性/方法
}));
return <input type="text" ref={innerInputRef} />;
});
// 父组件：只能调用子组件暴露的 focus 和 clear 方法
const Parent = () => {
const inputRef = useRef(null);
const focusInput = () => {
inputRef.current.focus(); // 正常调用
};
const clearInput = () => {
inputRef.current.clear(); // 正常调用
};
// 尝试调用未暴露的 blur 方法会报错
const errorTest = () => {
inputRef.current.blur(); // 报错：blur is not a function
};
return (
<div>
<Input ref={inputRef} />
<button onClick={focusInput}>聚焦</button>
<button onClick={clearInput}>清空</button>
<button onClick={errorTest}>测试报错</button>
</div>
);
};
总结
- forwardRef：解决“父组件无法访问子组件内部 DOM/实例”的问题，实现 ref 的“穿透”转发。
- useImperativeHandle：配合 forwardRef 使用，解决“暴露过多子组件属性/方法”的问题，自定义暴露的内容，保证代码安全和低耦合。相当于新增了一层API定制层。
- 最小暴露原则，提升代码安全性（如果只使用 forwardRef 把子组件的 DOM 节点直接暴露给父组件，父组件能拿到完整的 DOM 实例，可随意修改所有属性 / 方法，容易引发意外问题。只暴露父组件真正需要的方法 / 属性，隐藏所有无关内容，限制父组件的操作范围）
- 解耦父子组件，提升可维护性（子组件如果重构，只要保证API不变就能不影响父组件）
- 集中管理暴露的接口，提升代码可读性（复杂组件中，useImperativeHandle 可以把所有对外暴露的方法 / 属性集中在一处，方便开发者快速查看 “这个组件对外提供了哪些能力”，相比分散的 ref 转发，可读性更高）
- 核心场景：父组件需要直接控制子组件的特定行为（如聚焦、重置、滚动），但又不想破坏 React 单向数据流的设计原则。
注意：这两个 API 属于“逃生舱”，应尽量少用——优先通过 props/state 实现父子通信，只有在必须操作子组件 DOM/实例时才使用。