Ant Design

Ant Design 设计体系与 React antd 组件库入口；保留 v5 的主题、表单与 SSR 用法，区分组件行为和应用职责。

#frontend #react #resource #growing

Ant-Design

[!info] related notes

相关体系: React 组件设计原则, UI 设计基础

相关实现: figma, pseudo-class-state-design

本页组件代码按 antd v5 编写，不据此推断其他主版本行为；迁移应查对应版本文档。

基础概念

Ant Design（简称 AntD）源自阿里巴巴蚂蚁金服的中后台设计语言与配套组件库。核心理念：

官方设计价值观：自然（Natural）、确定（Certain）、意义（Meaningful）、生长（Growing）
设计变量体系（Color / Spacing / Typography / Motion / Elevation）
原子到模式：Token -> 基础控件 -> 复合组件 -> 模板 -> 页面
组件分类：数据录入、数据展示、导航、反馈、布局、通用
可访问性（a11y）：语义化、焦点管理、键盘操作、ARIA 属性
国际化（i18n）与 RTL 支持
v5 主题以 Seed Token → Map Token → Alias Token 的推导和组件 Token 为核心；Less 变量属于更早版本的主要定制路径

版本演进要点：

v3: 基于 Less 变量，类名层级较深
v4: Hooks 化 / TreeShaking 改善 / Form 新版 / 静态方法简化
v5: Design Token 体系、CSS-in-JS（@ant-design/cssinjs）、高性能虚拟滚动、紧凑模式、适配 SSR 样式隔离

适用场景：中后台管理系统、数据密集型操作界面、需要统一交互规范的多团队协作项目。

使用指南

安装

pnpm add antd@5 @ant-design/icons@5
# 前提：已有兼容的 React 项目；React/react-dom 版本遵循该项目与 antd peerDependencies

按需加载：

使用 babel-plugin-import（v4 及以前）
v5 可使用 ESM 与构建器 tree shaking；reset.css 是可选的全局重置样式，不是按需加载开关

最小示例

import React from 'react';
import { ConfigProvider, Button, App } from 'antd';
import zhCN from 'antd/locale/zh_CN';

export default function Demo() {
  return (
    <ConfigProvider locale={zhCN}> 
      <App>
        <Button type="primary">提交</Button>
      </App>
    </ConfigProvider>
  );
}

表单要点

import { Form, Input, Button } from 'antd';
type LoginValues = { username: string; password: string };

export function LoginForm({ onSubmit }: { onSubmit: (values: LoginValues) => void }) {
  const [form] = Form.useForm();
  return (
    <Form<LoginValues> form={form} onFinish={onSubmit} layout="vertical">
      <Form.Item name="username" label="用户名" rules={[{ required: true, message: '必填' }]}> 
        <Input placeholder="请输入" allowClear />
      </Form.Item>
      <Form.Item name="password" label="密码" rules={[{ required: true }]}> 
        <Input.Password placeholder="••••••" />
      </Form.Item>
      <Button type="primary" htmlType="submit" block>登录</Button>
    </Form>
  );
}

onSubmit 由应用接入登录请求；示例只做表单校验，不输出密码，也不实现认证。后端仍必须校验输入与权限。

主题定制 (v5 Token)

<ConfigProvider
  theme={{
    token: {
      colorPrimary: '#1677ff',
      borderRadius: 6,
    },
    components: {
      Button: { controlHeight: 38 }
    }
  }}
>
  <Button type="primary">主题按钮</Button>
</ConfigProvider>

性能优化

使用按需导入 & ESM 构建（避免整包）
大数据场景按需分页/虚拟滚动；rowKey 提供稳定行身份，不保证行不重渲染
Form.Item 可用 dependencies 或函数形式的 shouldUpdate 限定更新；shouldUpdate=true 会响应所有表单更新，不能一概视为优化
先测量渲染成本，再按稳定 props/回调条件使用 memo；useCallback 本身不会阻止子组件渲染
微前端先统一 prefixCls、样式容器和弹层挂载点；.ant- 是精确类名选择器，不匹配所有以 ant- 开头的类

与 CSS 方案集成

Tailwind：可以通过 @layer components 重写 .ant-btn 部分样式，但注意优先级
CSS Modules：组件外层包一层容器，避免直接覆盖深层 .ant- 类名
Next.js SSR：v5 的 App Router 使用 @ant-design/nextjs-registry；Pages Router 按官方方案用 @ant-design/cssinjs 的 cache/extractStyle 收集样式。不是通用的 StyleServer API

实战经验

复杂表单：分区折叠 + Form.List 动态字段；提交前用 form.validateFields() 并在后端做二次校验。
动态主题：结合 ConfigProvider + useState 存储主题 token，支持用户切换暗色/紧凑模式。
国际化：<ConfigProvider locale={xx}> + 业务文案统一 i18n 函数（如 t('user.login')）。
表格：后端分页统一接口 { list, total }；排序/筛选统一映射参数；行选择避免使用 index 作 key。
图标：按需 @ant-design/icons，过多图标可抽离本地 SVG Sprite。
权限组件只控制 UI 展示；真实授权必须在服务端执行，隐藏按钮不阻止直接调用 API。
低代码/配置化：组件属性抽象成 JSON Schema -> 动态驱动表单/表格列展示。
微前端的容器选择器只能约束其后代；Modal 等 portal 若挂到 body，需另行处理挂载点与样式范围。

常见坑：

样式覆盖优先级：v5 使用 CSS-in-JS，需要通过 ConfigProvider 或者 Token，而不是强行写 .ant-btn 覆盖。
Modal 的 modalRender 定制内容、getContainer 控制挂载位置；二者都不是通用的滚动穿透修复开关，需验证实际布局与焦点/滚动行为。
表格列宽跳动：给常驻列加 width + tableLayout="fixed"。
异步加载表单值使用 form.setFieldsValue；initialValues 用于初始化/重置，resetFields 会回到初始状态并重新挂载相关字段，不等于应用任意新值。

经验总结

抓手：设计 Token 驱动一致性；高复用拆出基础组件层（如 SearchForm / ProTable 包装）；性能从渲染次数 + 传输数据量 + 样式注入开销三方面优化。

最佳实践清单：

✅ UI 规范先行：色板 / 间距 / 字号 / 交互状态
✅ 抽象 Layout / PageContainer / 操作区域 Toolbar
✅ 表单字段抽象：数据源、显示、校验、交互解耦
✅ 公共反馈：Message / Modal / Notification 二次封装
✅ ESLint + StyleLint 规范 + Storybook 组件沙盒
✅ 基于 @testing-library/react 做关键交互测试

何时不适用：超轻量 Landing Page（选用更轻 UI）；强定制视觉品牌（需 Tailwind 或自研 Token）。

信息参考

官网: https://ant.design
主题 Token: https://ant.design/docs/react/customize-theme-cn
设计价值观: https://ant.design/docs/spec/values-cn
v5 升级指南: https://ant.design/docs/react/migration-v5-cn
v5 Next.js SSR 说明
相关生态：ant-design-pro / ahooks / pro-components / umi