💡 前言

在日常开发中，我们经常会遇到这样的场景：

• 父组件想直接控制子组件行为（如打开/关闭弹窗、重置表单）。
• 子组件内部逻辑复杂，不希望暴露太多 props。
• 我们想做出**“命令式 API”**（比如 modalRef.current.open()）。

React 官方虽然推崇声明式编程，但有时候命令式控制反而更直观。
这时，forwardRef 与 useImperativeHandle 的组合就是完美的解决方案。

---

🧱 一、基础概念理解

1️⃣ forwardRef 是什么？

forwardRef 的作用是——让父组件可以获取子组件内部的 ref 引用。

简单来说，它“转发”了 ref：

import React, { forwardRef, useRef } from "react"

const MyInput = forwardRef((props, ref) => {
  return <input ref={ref} placeholder="请输入..." />
})

export default function App() {
  const inputRef = useRef<HTMLInputElement>(null)
  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={() => inputRef.current?.focus()}>聚焦</button>
    </>
  )
}

👉 输出效果：点击按钮，输入框获得焦点。

---

2️⃣ useImperativeHandle 是什么？

useImperativeHandle 可以让我们自定义 ref 暴露的内容，而不只是 DOM 引用。

useImperativeHandle(ref, () => ({
  open: () => setOpen(true),
  close: () => setOpen(false),
}))

换句话说：它能把组件内部的方法“暴露”给父组件调用。

---

⚙️ 二、实战：用 forwardRef + useImperativeHandle 封装 Modal 组件

✅ 目标：

• 父组件可以通过 ref 打开/关闭弹窗
• Modal 内部逻辑完全自控，不依赖外部状态
• 支持传参（如设置标题、回调等）

---

🔹 Step 1：封装子组件

// Modal.tsx
import React, { forwardRef, useImperativeHandle, useState } from "react"

export interface ModalRef {
  open: (title?: string) => void
  close: () => void
}

export const Modal = forwardRef<ModalRef>((_, ref) => {
  const [visible, setVisible] = useState(false)
  const [title, setTitle] = useState("")

  useImperativeHandle(ref, () => ({
    open: (t = "默认标题") => {
      setTitle(t)
      setVisible(true)
    },
    close: () => setVisible(false),
  }))

  if (!visible) return null

  return (
    <div style={styles.mask}>
      <div style={styles.box}>
        <h3>{title}</h3>
        <p>这是一段内容</p>
        <button onClick={() => setVisible(false)}>关闭</button>
      </div>
    </div>
  )
})

const styles = {
  mask: {
    position: "fixed" as const,
    top: 0, left: 0, right: 0, bottom: 0,
    background: "rgba(0,0,0,0.4)",
    display: "flex", justifyContent: "center", alignItems: "center"
  },
  box: {
    background: "#fff", padding: "20px 30px", borderRadius: "8px"
  }
}

---

🔹 Step 2：父组件中调用

// App.tsx
import React, { useRef } from "react"
import { Modal, ModalRef } from "./Modal"

export default function App() {
  const modalRef = useRef<ModalRef>(null)

  return (
    <div>
      <h2>forwardRef + useImperativeHandle 实战示例</h2>
      <button onClick={() => modalRef.current?.open("自定义标题")}>打开弹窗</button>
      <button onClick={() => modalRef.current?.close()}>关闭弹窗</button>

      <Modal ref={modalRef} />
    </div>
  )
}

运行效果：
✅ 点击「打开弹窗」 -> 弹窗出现
✅ 点击「关闭弹窗」 -> 弹窗隐藏

---

🧩 三、深入理解：为什么不直接用 props？

如果我们用传统的 props 控制方式：

<Modal visible={visible} onClose={() => setVisible(false)} />

• 每次都要在父组件维护一个状态。
• 复杂嵌套层级下需要层层传递。
• 复用麻烦，尤其是动态创建多个 Modal 时。

而命令式 API 方式：

modalRef.current?.open()

• 独立封装内部逻辑
• 不依赖父组件状态
• 方便复用与动态实例化

🧠 实际上，这是一种**“组件服务化”**的思维方式（类似于 Ant Design 的 Modal.service）。

---

🧠 四、进阶应用：控制 Form 组件

你可以用同样的方式，让父组件主动调用子表单的方法，例如：

// Form.tsx
export interface FormRef {
  submit: () => void
  reset: () => void
}

export const Form = forwardRef<FormRef>((_, ref) => {
  const [value, setValue] = useState("")

  useImperativeHandle(ref, () => ({
    submit: () => alert("提交数据：" + value),
    reset: () => setValue("")
  }))

  return (
    <div>
      <input value={value} onChange={e => setValue(e.target.value)} />
    </div>
  )
})

父组件：

const formRef = useRef<FormRef>(null)
<formRef.current?.submit() />
<formRef.current?.reset() />

💡 这种封装方式在复杂表单（如多步骤表单、动态表单）中特别高效。

---

⚡ 五、性能与设计建议

场景	建议
多层级调用	封装自定义 Hook 暴露命令方法
多实例控制	使用 ref 数组或 Map<string, Ref> 管理
与动画结合	结合 framer-motion 控制 open/close 动画
避免过多重渲染	将可变逻辑放入 useRef，减少 useState 使用

---

🧭 六、与受控/非受控组件的对比

模式	优点	缺点	适用场景
受控组件（props）	数据单向流动、可预测	父层状态臃肿	简单输入框、展示组件
非受控组件（ref）	灵活、命令式操作	不易追踪状态变化	Modal、Drawer、Notification
forwardRef + useImperativeHandle	融合两者优点，可封装复杂行为	稍复杂	动态 UI 控制、全局弹窗管理

---

🧩 七、扩展：结合 Portal 实现全局控制

结合 createPortal 可以把弹窗挂载到全局 DOM 节点，进一步提升体验：

return createPortal(
  visible && <div className="modal">内容</div>,
  document.body
)

这样你可以在任意位置打开一个全局弹窗，而不影响布局层级。

---

📘 八、总结

forwardRef 与 useImperativeHandle 这对组合，堪称 React 中的「黑科技」级 API。

它让我们在声明式的框架中，实现命令式的组件控制逻辑，兼顾了：

• 封装性 ✅
• 灵活性 ✅
• 可复用性 ✅

如果你想让组件具备：

“我想让父组件随时命令我做事”的能力
那这两个 Hook 绝对是你的不二选择 💥

---

🧩 推荐阅读

• React 官方文档：forwardRef
• React 官方文档：useImperativeHandle