HOW - 经典详情页表单内容数据填充（基于 Antd 组件库）

背景

在 Ant Design 中，对于详情页或详情抽屉面板，如果其内容是一组 Form.Item 组成的表单，且数据是异步获取的。可以按照以下推荐方式进行填充。

方案

标准做法：使用 form.setFieldsValue 填充表单

示例代码（以 Drawer + Form 为例）：

import { Drawer, Form, Input, Spin } from 'antd'
import { useEffect, useState } from 'react'

const DetailDrawer = ({ open, onClose, id }: { open: boolean; onClose: () => void; id?: string }) => {
  const [form] = Form.useForm()
  const [loading, setLoading] = useState(false)

  // 模拟异步获取详情
  const fetchData = async (id: string) => {
    setLoading(true)
    try {
      const res = await fetchDetail(id) // 替换为你的请求函数
      form.setFieldsValue(res)
    } finally {
      setLoading(false)
    }
  }

  useEffect(() => {
    if (open && id) {
      form.resetFields() // 清空旧数据，避免闪现
      fetchData(id)
    }
  }, [open, id])

  return (
    <Drawer title="详情" open={open} onClose={onClose} width={480}>
      <Spin spinning={loading}>
        <Form form={form} layout="vertical">
          <Form.Item label="名称" name="name">
            <Input disabled />
          </Form.Item>
          <Form.Item label="描述" name="description">
            <Input.TextArea rows={4} disabled />
          </Form.Item>
        </Form>
      </Spin>
    </Drawer>
  )
}

export default DetailDrawer

要点总结

步骤	说明
form.setFieldsValue(data)	将异步数据填充到表单中。字段名必须与 name 匹配。
form.resetFields()	切换 ID 或打开抽屉前重置，防止旧数据残留
<Spin spinning={loading}>	数据加载时添加 loading 效果
disabled	如果是只读详情页，将表单项设置为 disabled

常见坑

• 必须等 Form 挂载后再执行 setFieldsValue；
• setFieldsValue 只更新已有字段，字段名必须完全匹配；
• 若使用 initialValues，它只在组件初始渲染时生效，不能用于异步数据填充。

方法 2：使用 initialValues 搭配 key 强制刷新

适用于字段不多、数据加载时机确定的场景

• initialValues 只在表单首次渲染时生效
• 通过给 Form 添加唯一 key 强制重新渲染

<Form
  key={record?.id} // 用 key 控制刷新
  initialValues={record}
>
  <Form.Item name="name" />
</Form>

缺点是整张表单会重建，不适合保留某些用户输入状态。

方法 3：数据不放入 Form，直接展示为只读字段

适用于只读详情页而非“伪表单”

<Descriptions>
  <Descriptions.Item label="姓名">{data.name}</Descriptions.Item>
</Descriptions>

或者：

<p><b>姓名：</b> {data.name}</p>

这种方式不使用 Form，适用于仅展示数据而无交互需求的“详情”面板。

总结：各方法对比

方法	是否推荐	说明
setFieldsValue	✅ 强烈推荐	表单组件原生方式，适用于任何异步填充
initialValues+key	🟡 可选	对字段少、数据小、一次性加载可用
直接展示数据	🟡 可选	对于纯展示详情页，更轻量