useImperativeHandle：暴露组件方法

useImperativeHandle 是 React 提供的一个 Hook，用于自定义暴露给父组件的实例值或方法。通常与 forwardRef 配合使用，打破函数组件“无法对外暴露内部方法”的限制。

为什么需要它

在 React 中，数据通常通过 Props 自上而下流动，父组件通过状态或回调控制子组件。但有时你需要命令式地调用子组件的内部方法，例如：

手动聚焦到子组件内的输入框
触发子组件的动画或滚动
调用子组件的数据重置/提交方法

直接用 ref 只能拿到子组件的 DOM 节点（如果子组件是原生元素），对于函数组件本身，ref 无法直接访问内部的方法和状态。这时就需要 useImperativeHandle 来自定义要暴露的东西。

基本用法

import { forwardRef, useImperativeHandle, useRef } from 'react';

// 使用 forwardRef 包裹子组件，以便接收父组件传递的 ref
const ChildInput = forwardRef((props, ref) => {
  const inputRef = useRef(null);

  // 自定义暴露给父组件的方法
  useImperativeHandle(ref, () => ({
    focus: () => {
      inputRef.current?.focus();
    },
    clear: () => {
      inputRef.current.value = '';
    },
  }));

  return <input ref={inputRef} type="text" />;
});

// 父组件使用
function Parent() {
  const childRef = useRef(null);

  return (
    <div>
      <ChildInput ref={childRef} />
      <button onClick={() => childRef.current.focus()}>聚焦输入框</button>
      <button onClick={() => childRef.current.clear()}>清空输入框</button>
    </div>
  );
}

关键点：

子组件必须用 forwardRef 包裹，才能接收来自父组件的 ref。
useImperativeHandle 的第一个参数是父组件传入的 ref，第二个参数是一个工厂函数，返回想要暴露的对象。
工厂函数返回的对象会变成 childRef.current 的值。

依赖项控制重新创建

useImperativeHandle 支持第三个参数（依赖数组），类似于 useEffect。只有当依赖项变化时，暴露的对象才会重新创建，避免不必要的重渲染或旧闭包问题。

useImperativeHandle(ref, () => ({
  getValue: () => stateValue, // stateValue 变化时需要重新创建
}), [stateValue]);

建议始终将内部依赖的状态或方法放入依赖数组，保证暴露的函数能访问到最新值。

典型使用场景

封装复合组件

当你封装一个包含多个子元素和复杂逻辑的组件时（例如一个富文本编辑器），你希望父组件能通过简单的命令控制其行为（如获取内容、插入模板），而不是把内部状态和 ref 全部暴露出去。useImperativeHandle 可以对外提供一组清晰、可控的 API。

与第三方 UI 库集成

有些第三方库需要获取 DOM 节点进行操作（如滚动到某个位置、动态计算尺寸），但你的子组件内部可能对 DOM 进行了封装。通过暴露特定方法，可以隐藏实现细节。

表单统一控制

在复杂表单中，你可能希望父组件能统一调用所有子表单字段的校验方法。每个字段组件可以暴露 validate() 方法，父组件通过 ref 依次调用。

注意事项与最佳实践

不要过度使用

React 的哲学是声明式，useImperativeHandle 为你打开了命令式的“后门”。大多数情况下应该通过 Props 和状态来驱动组件，只有在确实无法用声明方式合理实现时才考虑它。

暴露最小化接口

只暴露父组件必需的方法，避免把整个内部状态或 DOM 节点暴露出去。例如只暴露 focus 和 clear，而不是把 inputRef 直接传出去。这有助于保持组件的封装性。

与 forwardRef 强绑定

函数组件本身没有实例，不配合 forwardRef 使用 useImperativeHandle 会报错。React 19 开始可以直接在组件 Props 中使用 ref（不再需要 forwardRef），但心智模型相同。

注意闭包陷阱

如果工厂函数内部使用了组件内的状态或 props，务必把它们加入依赖数组，否则暴露的方法会捕获过期的变量值。

总结

useImperativeHandle 是 React 为函数组件保留的一个高级逃生舱，让你在需要时能向父组件暴露命令式接口。使用时请谨慎权衡，能用声明式解决的优先用声明式，只在必要时刻打开这扇门，并严守“暴露最小化”原则。