Ant Design Drawer 实现列表信息预览抽屉（User Profile）实战指南

本文以仓库内 user-profile 演示 为线索，讲解如何用 Ant Design 的 Drawer 组件在列表页中实现"点击对象条目 → 快速预览概要信息 → 点击遮罩关闭"的经典信息预览交互。读完你将掌握 Drawer 的受控开关、size 宽度设置、遮罩关闭行为，以及 List/Avatar/Row/Col 与 CSS 变量组合搭建结构化资料卡片的完整方法。

一、演示定位：何时使用"信息预览抽屉"

该演示对应的说明文档（components/drawer/demo/user-profile.md）只有一句话："需要快速预览对象概要时使用，点击遮罩区关闭"。这与 Drawer 组件的总体设计理念一致——在 Drawer 官方文档（中文） 的"何时使用"中明确：当需要在当前任务流中插入临时任务，创建或预览附加内容（如展示协议条款、查看列表条目详情）时使用抽屉，用户不必离开当前任务，操作完成后可平滑回到原列表。

它的典型落地场景是管理后台的列表 → 详情预览：

• 用户在人员列表中发现一个感兴趣的成员，无需跳转新页面即可查看其完整档案；
• 预览内容包括 Personal（个人信息）、Company（公司信息）、Contacts（联系方式） 三组结构化字段；
• 看完之后点击遮罩（Mask）即可关闭，返回列表继续浏览。

该演示在文档站中注册为"信息预览抽屉"，位于 Drawer 代码演示列表（<code src="./demo/user-profile.tsx">信息预览抽屉</code>），且拥有对应的渲染快照测试（见 demo.test.ts.snap 第 917 行），说明它在组件测试体系中被持续验证，代码结构具有代表性。

二、整体结构拆解：从列表入口到抽屉内容

user-profile.tsx 的组件结构可以概括为"一个列表 + 一个受控抽屉"，其中抽屉内部又细分为"结构化字段区 + 分组分隔"：

1. 外层 List 渲染两条人员数据（Lily），每条数据提供 View Profile 操作；
2. 点击操作触发 showDrawer，把 open 置为 true；
3. Drawer 从屏幕右缘滑出（placement="right"），展示该对象的完整资料；
4. 点击遮罩区触发 onClose，把 open 置为 false 完成关闭。

核心状态只有一对：

const [open, setOpen] = useState(false);

const showDrawer = () => setOpen(true);
const onClose = () => setOpen(false);

Drawer 是受控组件。open 由业务侧状态决定可见性，onClose 负责把外部状态收回 false。这决定了你在任何场景中接入 Drawer，都必须维护这一对开关逻辑。

三、列表入口设计：List + Avatar 组织"对象概要"

演示用 List（bordered 带边框）承载两条示例数据，每条数据通过 List.Item.Meta 展示头像、姓名与职位描述，操作区放一个 View Profile 链接：

<List
  bordered
  dataSource={[{ id: 1, name: 'Lily' }, { id: 2, name: 'Lily' }]}
  renderItem={(item) => (
    <List.Item
      key={item.id}
      actions={[<a onClick={showDrawer} key={`a-${item.id}`}>View Profile</a>]}
    >
      <List.Item.Meta
        avatar={<Avatar src="..." />}
        title={item.name}
        description="Progresser XTech"
      />
    </List.Item>
  )}
/>

需要注意的实操细节：

• key 必须稳定且唯一，列表项与操作按钮都使用 item.id（按钮使用 key={a-${item.id}} 防止与行 key 冲突）；
• List.Item.Meta 的 avatar、title、description 分别负责头像、主标题、副标题，是组织"对象概要"的标准写法；
• View Profile 触发的是同一个 showDrawer。真实业务中更常见的是在操作里携带 item 数据（如 onClick={() => showProfile(item)}），让抽屉展示当前选中对象的内容。

四、Drawer 核心配置解读：size / placement / closable / open / onClose

演示中的 Drawer 配置是全篇的核心，仅用一行就把关键属性交代清楚：

<Drawer size={640} placement="right" closable={false} onClose={onClose} open={open}>

下面结合 Drawer 组件源码 与 API 文档 逐个解读其原理与取值：

4.1 size：用像素精确控制抽屉宽度

size={640} 表示抽屉面板宽度为 640px。在源码 Drawer.tsx 的 drawerSize 计算逻辑中：

• 当 size 为数字时直接透传（isNumber(size) 命中，返回该数字）；
• size="default" 被映射为常量 DEFAULT_SIZE = 378（源码 components/drawer/Drawer.tsx）；
• size="large" 被映射为 736；
• 自 6.2.0 起 size 还支持传入字符串，纯数字字符串会被转换为数值，其他字符串作为单位值（如百分比）透传。

因此，如果你希望抽屉"比默认宽一点"，既可以直接用 size={640}，也可以配合 placement 理解其语义：size 在 top/bottom 方向代表高度，在 left/right 方向代表宽度。示例 placement="right" + size={640} 即"右侧滑出、宽 640px"。

4.2 placement：滑出方向

placement="right" 指定抽屉从右缘滑入，这也是默认值。可选值为 top / right / bottom / left。信息预览类场景通常固定使用 right，让面板贴合阅读视线右侧，同时保留左侧列表上下文。

4.3 closable={false}：隐藏右上角关闭按钮

信息预览场景为了界面极简，刻意隐藏了右上角"×"关闭按钮（closable 默认 true），关闭动作完全交给遮罩点击与键盘 Esc。注意：closable={false} 只会隐藏关闭按钮，并不会禁止关闭——Drawer 关闭的三种标准途径（遮罩点击、Esc 键、onClose）依然有效。

4.4 受控开关与回调

• open={open}：布尔值控制是否可见（默认 false）；
• onClose={onClose}：点击遮罩层或左上角关闭按钮（若显示）时的回调，接收事件对象。业务侧在此将 open 复位即可。

4.5 该 Demo 未显式声明的关键默认值（源码佐证）

• mask（遮罩）：默认 true。从 useMergedMask.ts 的实现看，遮罩最终合并逻辑为 mergedConfig.enabled !== false，即未显式关闭时遮罩生效，让预览聚焦于面板内容；
• 点击遮罩关闭：合并遮罩配置时 closable 的默认值为 true（源码第 49 行 closable: ... ?? contextMaskConfig.closable ?? true）。这正是 user-profile.md 中"点击遮罩区关闭"的实现来源——遮罩默认可点击关闭，无需任何额外配置；
• keyboard：默认 true，支持按 Esc 关闭。

五、抽屉内容编排：Row/Col 栅格 + DescriptionItem 组件

抽屉正文是资料卡片，演示引入了一个精心设计的私有子组件 DescriptionItem，把"字段名 + 字段值"抽象成可复用单元：

const DescriptionItem: React.FC<DescriptionItemProps> = ({ title, content }) => (
  <div className={styles.descriptionItem}>
    <p className={styles.label}>{title}:</p>
    {content}
  </div>
);

内容区通过 Row / Col 栅格做双栏排版：

• Col span={12}：左右各占半行，适合 Full Name / Account、City / Country 这类成对短字段；
• Col span={24}：整行独占，适合 Message、Skills、GitHub 这类长文本字段；
• Divider 把内容分为 Personal、Company、Contacts 三个语义分组，长档案在视觉上层次分明。

<Row>
  <Col span={12}>
    <DescriptionItem title="Full Name" content="Lily" />
  </Col>
  <Col span={12}>
    <DescriptionItem title="Account" content="[e-mail]" />
  </Col>
</Row>
<Divider />
<p className={styles.profileTitle}>Company</p>
<Row>
  <Col span={24}>
    <DescriptionItem title="Skills" content="C / C++, ..." />
  </Col>
</Row>

content 被声明为 React.ReactNode，因此字段值不仅可以放纯文本，也可以放任意 React 节点（演示中 GitHub 字段即嵌套了带 target="_blank" 与 rel="noopener noreferrer" 的外部链接元素），扩展性极强。

六、样式方案：antd-style 的 cssVar 设计令牌

演示使用 createStyles（antd-style）声明样式，并全部引用 CSS 变量令牌（cssVar），保证样式随主题自动切换（暗色模式、品牌色定制等场景无需改动代码）：

const useStyles = createStyles((props) => {
  const { css, cssVar } = props;
  return {
    descriptionItem: css`
      margin-bottom: ${cssVar.marginXS};
      color: ${cssVar.colorTextLabel};
      font-size: ${cssVar.fontSize};
      line-height: ${cssVar.lineHeight};
    `,
    label: css`
      display: inline-block;
      margin-inline-end: ${cssVar.marginXS};
      color: ${cssVar.colorTextHeading};
    `,
  };
});

值得关注的令牌用法与对应 UI 语义：

令牌	用途
colorTextLabel	字段名称的弱化文本色（标签）
colorTextHeading	标题/字段值的强调文本色
fontSize / fontSizeLG / lineHeight	正文与区块标题的字号行高体系
marginXS / margin	字段间距与标题下间距
marginInlineEnd	标签与内容之间的行内间距（天然支持 RTL）

同时 profileTitle 用 fontSizeLG + colorTextHeading 区分"分组标题"，配合内部 <p> 与行内 style={{ marginBottom: 24 }} 微调首屏留白。整体思路是：布局用栅格、间距与色彩用语义令牌、文案层级用字号区分，这是 Ant Design 生态中搭建信息展示面板的推荐姿势。

七、交互与增强：在演示基础上继续演进

演示覆盖了最小闭环（打开 → 预览 → 遮罩关闭），从 Drawer API 文档 与仓库测试看，信息预览抽屉可按需叠加以下能力：

1. 多级上下文：若从预览中再打开更深层操作（如"编辑资料"子抽屉），可用 push（默认 { distance: 180 }）让父层抽屉自动让位，源码见 Drawer.tsx 中 DEFAULT_PUSH_STATE；
2. 关闭后销毁内容：使用 destroyOnHidden（自 5.25.0，替代已废弃的 destroyOnClose）在关闭时卸载子树，适合内容重、状态多的场景，避免残留内部状态；
3. 加载态：使用 loading 让抽屉内容显示骨架屏（Skeleton），适配"点击后异步拉取对象概要"的真实链路；
4. 可调宽：仓库当前版本已支持 resizable 与 maxSize，允许用户拖拽面板边缘调整预览宽度，对长资料场景很实用；
5. 遮罩精细化：6.0.0 起 mask 支持对象形态 { enabled, blur, closable }，例如 mask={{ blur: true }} 可对背景做模糊处理进一步聚焦面板，closable: false 则禁止点击遮罩关闭（强制用户主动关闭）。

八、要点总结

• 交互范式：Drawer 信息预览 = 列表触发（open 置真）+ 结构化面板展示 + 遮罩/Esc 关闭（onClose 复位），完整闭环只需一个 useState；
• 尺寸控制：size 传数字即为精确像素宽，default=378、large=736，方向决定宽或高；
• 关闭语义：closable={false} 只隐藏关闭按钮；点击遮罩默认即可关闭，无需额外配置；
• 内容组织：Row/Col 双栏 + 可复用 DescriptionItem + Divider 分组，是打造信息密度高、层次清晰的资料卡片的通用模板；
• 样式一致性：通过 antd-style createStyles + cssVar 令牌接入主题体系，避免硬编码颜色与间距。

阅读本文后，你可以直接参考 user-profile.tsx 演示源码 在任意 List（或 Table）页面中复刻该模式，再结合 destroyOnHidden、loading、resizable 等属性做产品化增强。