Ant Design

Ant-Design

#tech / dev / library #type / concept #status / growing

Ant-Design

[!info] related notes

基础概念

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

  1. 设计价值观：一致（Consistency）、确定（Certainty）、有效（Efficiency）、可控（Controllability）
  2. 设计变量体系（Color / Spacing / Typography / Motion / Elevation）
  3. 原子到模式：Token -> 基础控件 -> 复合组件 -> 模板 -> 页面
  4. 组件分类：数据录入、数据展示、导航、反馈、布局、通用
  5. 可访问性（a11y）：语义化、焦点管理、键盘操作、ARIA 属性
  6. 国际化（i18n）与 RTL 支持
  7. 主题定制：Less 变量 / CSS-in-JS Token（v5）/ 动态算法（Seed -> Map -> Token）

版本演进要点：

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

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

使用指南

安装

pnpm add antd @ant-design/icons react react-dom

按需加载：

  1. 使用 babel-plugin-import（v4 及以前）
  2. v5 推荐直接使用 ESM + TreeShaking + antd/dist/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';
export function LoginForm() {
  const [form] = Form.useForm();
  return (
    <Form form={form} onFinish={values => console.log(values)} 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>
  );
}

主题定制 (v5 Token)

<ConfigProvider
  theme={{
    token: {
      colorPrimary: '#1677ff',
      borderRadius: 6,
    },
    components: {
      Button: { controlHeight: 38 }
    }
  }}
/>

性能优化

  • 使用按需导入 & ESM 构建（避免整包）
  • 大数据场景：Table pagination + virtual scroll / rowKey 避免重渲染
  • Form 避免过多受控字段：Form.Item shouldUpdate 精细控制
  • 使用 React.memo + useCallback 包裹频繁 re-render 子组件
  • 样式隔离：同域多微前端避免样式冲突可使用 :where(.scope) .ant- 前缀策略

与 CSS 方案集成

  • Tailwind：可以通过 @layer components 重写 .ant-btn 部分样式，但注意优先级
  • CSS Modules：组件外层包一层容器，避免直接覆盖深层 .ant- 类名
  • SSR (Next.js)：v5 内置 CSS-in-JS，可在 _document 中注入 StyleServer 集合

实战经验

  1. 复杂表单：分区折叠 + Form.List 动态字段；提交前用 form.validateFields() 并在后端做二次校验。
  2. 动态主题：结合 ConfigProvider + useState 存储主题 token，支持用户切换暗色/紧凑模式。
  3. 国际化：<ConfigProvider locale={xx}> + 业务文案统一 i18n 函数（如 t('user.login')）。
  4. 表格：后端分页统一接口 { list, total }；排序/筛选统一映射参数；行选择避免使用 index 作 key。
  5. 图标：按需 @ant-design/icons，过多图标可抽离本地 SVG Sprite。
  6. 权限渲染：封装 <Auth visible={perm}> 内部做鉴权，减少到处写条件判断。
  7. 低代码/配置化：组件属性抽象成 JSON Schema -> 动态驱动表单/表格列展示。
  8. 与微前端：使用命名空间前缀 body[data-app='subA'] .ant-xxx{} 防止样式互串。

常见坑：

  • 样式覆盖优先级：v5 使用 CSS-in-JS，需要通过 ConfigProvider 或者 Token，而不是强行写 .ant-btn 覆盖。
  • Modal 嵌套滚动穿透：设置 modalRender 或者全局 getContainer={false} 并处理 body 滚动控制。
  • 表格列宽跳动：给常驻列加 width + tableLayout="fixed"。
  • Form 初始值不更新：改变初始值需 form.resetFields() 或使用受控 fields。

经验总结

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

最佳实践清单：

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

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

信息参考

创建于 2025/1/1 更新于 2026/5/27