useImperativeHandle：自定义实例值

将引用直接转发到 DOM 元素时，父组件会收到原始 DOM 节点，并可以访问其所有原生方法和属性。这通常会暴露超出需求的操作范围。

有时，您可能更希望向父组件提供一个小而经过筛选的对象，而不是完整的 DOM 节点，从而有意保持组件公共接口的精简。

useImperativeHandle 允许您自定义父组件引用所指向的值。父组件收到的不是 DOM 节点，而是您返回的任意对象，因此您可以准确决定要暴露哪些方法和值。

这样，转发的引用就变成了定义明确的命令式接口，而不是底层元素的泄漏式直通通道。

该钩子将转发的引用作为第一个参数，将工厂函数作为第二个参数。工厂函数返回的句柄对象会成为父组件中的 ref.current。

您可以这样调用它：useImperativeHandle(ref, () => ({ ... }))，在工厂函数内部构建要提供的各种方法和值。

一种常见模式是创建一个只暴露 focus 和 clear 的自定义输入框。在工厂函数内部返回一个包含这两个方法的对象，每个方法都作用于指向真实输入框的内部引用。

现在，父组件可以聚焦或清除字段，但无法读取其原始 value 属性，也不能触发任意 DOM 行为，从而让使用方式更加可预测。

命令式句柄非常适合对话框。Modal 组件可以暴露 open 和 close 方法来切换内部可见性状态，让父组件能够以命令式方式控制它，而不必自行管理 open 布尔值。

对于需要从多个位置触发对话框的代码，这非常方便，例如在异步操作完成后显示确认对话框。

只返回您打算支持的方法，就能创建清晰的契约。使用者依赖的是一组精简且有文档说明的操作，而不是庞杂的 DOM 接口，这会让未来的重构更加安全。

范围精简的命令式接口更容易测试、更容易推理，而且在修改内部实现时不容易破坏。

useImperativeHandle 接受一个可选的第三个参数，即依赖数组。当任何依赖发生变化时，工厂函数会再次运行，并重新创建句柄对象，其工作方式类似于 useMemo 和 useEffect。

如果您暴露的方法闭包捕获了可能变化的值，请将这些值列为依赖项，以便父组件始终获得绑定到当前状态的句柄。

useImperativeHandle 只有在用 forwardRef 包装的组件内部才有意义，因为它需要转发的引用来附加自定义句柄。单独使用它时，并不存在可以填充的父组件引用。

因此二者需要配合使用：forwardRef 负责传入引用，useImperativeHandle 负责定义该引用最终指向的内容。

要测试句柄，请使用引用渲染组件，然后在 act 代码块内通过 ref.current 调用方法，并断言由此产生的行为或 DOM 变化。

由于暴露的接口范围小且定义明确，这些测试可以集中验证每个文档所述的方法是否履行其契约，而不是探查内部细节。

在 TypeScript 中，您可以定义一个描述句柄的接口，例如包含 focus 和 clear 方法的接口，然后使用它为 forwardRef 泛型和父组件持有的引用分别添加类型。

这样，调用位置就能获得自动补全和编译时检查，使用者可以准确看到有哪些方法，而错误使用会在运行时之前被发现。

请确认 useImperativeHandle 的实际用途。

useImperativeHandle 可以自定义转发的引用所暴露的内容：它接收引用和一个返回句柄对象的工厂函数。您可以用它暴露一个精简接口，例如 focus 和 clear，或模态框上的 open 和 close。

它始终与 forwardRef 配对使用，支持通过依赖数组刷新句柄，也适合与 TypeScript 接口和专注的测试配合使用。接口范围有限是有意为之，也是一种良好设计。