7.7 KiB
7.7 KiB
Ant Design（AntD）设计规范导出（v5）
说明：本文档基于 Ant Design v5 官方文档与设计令牌（Design Token）整理，用于项目内统一 UI 口径。若与线上文档不一致，以官方文档与实际
token输出为准。参考：
- Ant Design 文档：
https://ant.design/docs/react/introduce- 主题定制（Design Token）：
https://ant.design/docs/react/customize-theme- CSS Variables：
https://ant.design/docs/react/css-variables
1. 设计原则（适用于业务后台）
- 清晰：信息层级明确（标题/正文/辅助信息/弱提示），减少不必要装饰。
- 一致：同类型组件在同场景下外观与交互一致（按钮语义、表单校验、弹窗页脚等）。
- 高效：高频任务优先（表格筛选、快捷操作、批量处理），减少路径长度。
- 可控：可预期的反馈（加载/成功/失败/空态），避免“无响应”与不可逆操作。
2. 视觉基础（Design Token 口径）
2.1 色彩（Color）
语义色（常用）
- 主色（Primary）：品牌/主要操作按钮/高亮状态
- AntD v5 默认：
colorPrimary = #1677ff
- AntD v5 默认：
- 成功（Success）：成功态、完成态、正向结果
- 警告（Warning）：需要注意但不阻断流程
- 错误（Error）：失败、阻断、危险操作
- 信息（Info）：中性提示（一般与 Primary 同系或更弱）
文本与背景（建议层级）
- 正文主文本：用于标题、正文关键值
- 次级文本：用于说明、辅助信息
- 弱文本：用于占位、不可用、次要信息
- 容器背景：页面背景、卡片/表格容器背景
- 分割/边框：分割线、边框、表格网格线
落地建议：不要直接手写颜色值，优先使用 AntD token（如
colorText/colorBgContainer/colorBorder/colorPrimary），避免暗色模式或主题切换时失控。
2.2 字体（Typography）
- 基础字号：AntD v5 默认
fontSize = 14px - 字号体系：在正文 14 的基础上，常用
12/14/16/20/24（具体以 token 为准） - 字重：正文 400，标题/强调 500/600（按设计与字体实际支持）
- 行高：正文建议 1.4–1.6 区间；表格/表单密集场景可略收紧但要保证可读性
落地建议：
- 表单 label、辅助说明、错误提示使用 次级/弱 文本层级，避免与正文抢占注意力。
- 数字与金额在表格中建议 右对齐，并用等宽数字特性（如字体支持
font-variant-numeric: tabular-nums）提升可扫读性。
2.3 间距（Spacing）
推荐用 8px 网格作为基础节奏（token 会覆盖实际值）：
- 4/8/12/16/24/32：常用间距档位
- 表单项上下间距、卡片内边距、区块间距尽量统一
落地建议：
- 页面区块：24（区块间）
- 卡片/容器内边距：16 或 24
- 表单项间距：16（常规）/ 12（密集）
2.4 圆角（Radius）
- AntD v5 默认
borderRadius = 6px
常见分层：2/4/6/8（不同组件会使用不同层级）
落地建议：
- 不要在同一页面混用多个“视觉上相近但不一致”的圆角（例如 4 与 6 随意混用）。
2.5 阴影与层级（Shadow & Elevation）
典型层级：
- 容器浮层：Popover/Dropdown/Tooltip
- 对话框：Modal
- 抽屉：Drawer（靠近边缘）
落地建议：
- 阴影仅用于表达“悬浮/层级”，不要把阴影当分割线使用。
2.6 动效（Motion）
- 有意义：动效用于表达状态变化（展开/收起/加载/反馈），避免纯装饰。
- 短而稳：后台系统建议偏短时长，降低等待感；重要确认可以稍长但不要拖沓。
- 可中断：用户快速操作时动效不应叠加导致卡顿或错位。
3. 布局与栅格（Layout & Grid）
- 使用
Row/Col或Space/Flex组织布局，避免大量手写 margin 拼接。 - 表单与筛选区建议固定结构：
- 筛选区（可折叠）
- 操作区（主按钮 + 次按钮 + 批量操作）
- 表格区
- 分页/汇总
- 页面建议采用“标题 + 关键指标/说明 + 主体内容”层级，减少首屏信息噪声。
4. 组件使用规范（后台高频）
4.1 Button（按钮）
- 主按钮（Primary）：每个视图/弹窗尽量只有一个主按钮（最主要动作）。
- 次按钮（Default）：辅助动作、返回、取消。
- 危险（Danger）：删除/作废/清空等不可逆操作，必须配确认（Popconfirm/Modal.confirm）。
- 禁用态：禁用必须有原因（提示或辅助文案），避免“为什么点不了”。
弹窗页脚建议顺序（从右到左）：主操作 → 次操作（取消/关闭）。
4.2 Form（表单）
- 校验提示就近展示，错误文案可读且可执行（告诉用户怎么改）。
- 必填项统一标识；不要同页混用不同必填标记策略。
- 长表单建议分组（Card/Collapse/Steps），并提供保存草稿/分步提交（视业务复杂度）。
4.3 Table（表格）
- 列宽：关键列固定宽度，描述列可自适应；避免全自适应导致抖动。
- 对齐：金额/数量 右对齐；状态/标签可居中；文本默认左对齐。
- 操作列：避免超过 3 个直出操作；其余收纳到 Dropdown/More。
- 空态：提供原因与下一步（调整筛选/新建/刷新）。
4.4 Modal / Drawer（弹窗/抽屉）
- Modal：用于强打断、需要确认的任务；内容不宜过长。
- Drawer：用于不中断上下文的编辑/详情；适合较长内容或分区信息。
- 关闭方式：提供右上角关闭；重要内容关闭需二次确认（有未保存变更时）。
4.5 Message / Notification / Alert（反馈）
- Message：短反馈（保存成功/复制成功），不承载复杂信息。
- Notification：较长信息、异步结果、可操作提示（带按钮/链接）。
- Alert：页面内静态提示/规则说明/风险提示。
落地建议：错误信息尽量包含 定位信息 + 原因 + 建议动作（例如“金额格式不合法，请输入最多两位小数”）。
5. 主题与 Token “导出”（工程落地）
5.1 通过 ConfigProvider 统一主题
在应用入口用 ConfigProvider 设置全局 token（示意）：
import { ConfigProvider, theme } from 'antd';
export function App() {
return (
<ConfigProvider
theme={{
algorithm: theme.defaultAlgorithm,
token: {
colorPrimary: '#1677ff',
borderRadius: 6,
fontSize: 14,
},
components: {
// 组件级 token 覆盖（按需）
},
}}
>
{/* routes */}
</ConfigProvider>
);
}
5.2 在页面/组件中打印当前 token（用于“导出当前主题规范”）
你可以在任意页面临时输出（开发态）：
import { theme } from 'antd';
export function DebugTokens() {
const { token } = theme.useToken();
// 控制台复制即可作为“当前工程实际 token 导出”
console.log('antd token =>', token);
return null;
}
如果需要生成 JSON 文件，可以把 token 序列化后下载（浏览器端）：
export function downloadJson(filename: string, data: unknown) {
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json;charset=utf-8' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = filename;
a.click();
URL.revokeObjectURL(url);
}
6. 默认关键值速查（AntD v5）
- 主色：
#1677ff - 基础字号：
14px - 默认圆角：
6px
注：完整 token 以
theme.useToken()输出为准（因为你的工程可能有覆盖）。