ant-design/AGENTS.md

AGENTS.md

Ant Design 项目开发指南 - 为 AI 编程助手提供项目上下文和开发规范

📑 目录

• 项目背景
• 快速开始
• 代码规范
  • 基本编码规范
  • 命名规范
  • TypeScript 规范
  • 样式规范
• 开发指南
  • 测试指南
  • 演示代码规范
  • 国际化规范
• 文档和 Changelog
• Git 和 Pull Request
• 质量保证
• 工具链和环境

---

项目背景

这是 ant-design/ant-design（antd）的源代码仓库，是一个 React 组件库，发布为 npm 包 antd。

核心特性

• 使用 TypeScript 和 React 开发
• 兼容 React 18 ~ 19 版本
• 组件库设计精美，功能完善，广泛应用于企业级中后台产品
• 遵循 Ant Design 设计规范
• 支持国际化（i18n）
• 支持主题定制和暗色模式
• 支持 RTL（从右到左）布局

---

快速开始

开发环境要求

• Node.js: >= 16
• 包管理器: npm 或 utoo
• 浏览器兼容性: Chrome 80+
• 编辑器: VS Code（推荐）或其他支持 TypeScript 的编辑器

安装依赖

npm install
# 或
utoo install

常用开发命令

# 启动开发服务器（访问 http://127.0.0.1:8001）
npm start

# 编译 TypeScript 代码到 lib 和 es 目录
npm run compile

# 构建 UMD 格式的构建产物
npm run build

# 运行所有测试
npm test

# 监听模式运行测试
npm test -- --watch

# 生成测试覆盖率报告
npm run test:coverage

# 代码检查（包括 TypeScript、ESLint、Biome、Markdown、Changelog）
npm run lint

# 格式化代码
npm run format

# 生成 Changelog（交互式）
npm run changelog

# 清理构建产物
npm run clean

项目结构

ant-design/
├── components/          # 组件源代码
│   └── [component]/     # 单个组件目录
│       ├── demo/        # 演示代码
│       ├── style/       # 样式文件
│       ├── index.tsx     # 组件入口
│       └── index.zh-CN.md # 组件文档
├── scripts/             # 构建和工具脚本
├── tests/               # 测试文件
├── CHANGELOG.zh-CN.md   # 中文更新日志
├── CHANGELOG.en-US.md   # 英文更新日志
└── package.json         # 项目配置

---

代码规范

基本编码规范

• ✅ 使用 TypeScript 和 React 书写
• ✅ 使用函数式组件和 Hooks，避免类组件
• ✅ 使用提前返回（early returns）提高代码可读性
• ✅ 避免引入新依赖，严控打包体积
• ✅ 兼容 Chrome 80+ 浏览器
• ✅ 支持服务端渲染（SSR）
• ✅ 保持向下兼容，避免 breaking change
• ✅ 组件名使用大驼峰（PascalCase），如 Button、DatePicker
• ✅ 属性名使用小驼峰（camelCase），如 onClick、defaultValue
• ✅ 合理使用 React.memo、useMemo 和 useCallback 优化性能

Props 命名

用途	命名规则	示例
初始化属性	default + PropName	defaultValue、defaultOpen
强制渲染	forceRender	forceRender
子组件强制渲染	force + SubComponentName + Render	forcePanelRender
子组件渲染	SubComponentName + Render	titleRender、footerRender
数据源	dataSource	dataSource
面板开启	使用 open，避免使用 visible	open、defaultOpen
显示相关	show + PropName	showSearch、showHeader
功能性	PropName + able	disabled、readable
禁用	disabled	disabled
额外内容	extra	extra
图标	icon	icon、prefixIcon
触发器	trigger	trigger
类名	className	className

事件命名

类型	命名规则	示例
触发事件	on + EventName	onClick、onChange
子组件事件	on + SubComponentName + EventName	onPanelChange
前置事件	before + EventName	beforeUpload
后置事件	after + EventName	afterClose
连续动作完成	on + EventName + Complete	onUploadComplete

组件引用（Ref）

组件应提供 ref 属性，结构如下：

interface ComponentRef {
  nativeElement: HTMLElement;
  focus: VoidFunction;
  blur: VoidFunction;
  // 其他方法...
}

组件 Token 命名

格式：variant (optional) + semantic part + semantic part variant (optional) + css property + size/disabled (optional)

示例：

• buttonPrimaryColor - Button 主色
• inputPaddingBlock - Input 垂直内边距
• menuItemActiveBg - Menu 激活项背景色

API 文档规范

API 表格格式

Property	Description	Type	Default
htmlType	Button 原生类型	string	button
type	按钮类型	primary | default | dashed | link | text	default
disabled	是否禁用	boolean	false
minLength	最小长度	number	0
style	自定义样式	CSSProperties	-

API 文档要求

• ✅ 字符串类型的默认值使用反引号包裹，如 `button`
• ✅ 布尔类型直接使用 true 或 false
• ✅ 数字类型直接使用数字，如 0、100
• ✅ 函数类型使用箭头函数表达式，如 (e: Event) => void
• ✅ 无默认值使用 -
• ✅ 描述首字母大写，结尾无句号
• ✅ API 按字母顺序排列

---

TypeScript 规范

基本原则

• ✅ 所有组件和函数必须提供准确的类型定义
• ✅ 避免使用 any 类型，尽可能精确地定义类型
• ✅ 使用接口（interface）而非类型别名（type）定义对象结构
• ✅ 导出所有公共接口类型，方便用户使用
• ✅ 严格遵循 TypeScript 类型设计原则，确保类型安全
• ✅ 确保编译无任何类型错误或警告

组件类型定义

// ✅ 正确：使用 interface 定义 Props
interface ButtonProps {
  type?: 'primary' | 'default' | 'dashed';
  onClick?: (e: React.MouseEvent) => void;
}

// ❌ 错误：避免使用 type 定义对象结构
type ButtonProps = {
  type?: 'primary' | 'default';
};

// ✅ 正确：组件 Props 接口命名
interface ComponentNameProps {
  // ...
}

// ✅ 正确：组件状态接口命名
interface ComponentNameState {
  // ...
}

// ✅ 正确：使用 ForwardRefRenderFunction 定义 ref
const Component = React.forwardRef<ComponentRef, ComponentProps>((props, ref) => {
  // ...
});

类型使用最佳实践

• ✅ 适当使用泛型增强类型灵活性
• ✅ 使用交叉类型（&）合并多个类型
• ✅ 使用字面量联合类型定义有限的选项集合
• ✅ 避免使用 enum，优先使用联合类型和 as const
• ✅ 尽可能依赖 TypeScript 的类型推断
• ✅ 只在必要时使用类型断言（as）

// ✅ 推荐：使用联合类型和 as const
const ButtonTypes = ['primary', 'default', 'dashed'] as const;
type ButtonType = (typeof ButtonTypes)[number];

// ❌ 不推荐：使用 enum
enum ButtonType {
  Primary = 'primary',
  Default = 'default',
}

---

样式规范

样式方案

• 使用 @ant-design/cssinjs 作为样式解决方案
• 每个组件的样式应该放在 style/ 目录下
• 样式文件应该与组件结构保持一致
• 使用 CSS-in-JS 时应当注意性能影响，避免不必要的样式重计算
• 样式生成函数应遵循 gen[ComponentName]Style 的命名规范
• 样式覆盖应使用类选择器而非标签选择器，提高样式特异性

Token 系统

• 使用 Ant Design 的设计 Token 系统
• 避免硬编码颜色、尺寸、间距等值
• 组件样式应基于全局 Token 和组件级 Token
• 自定义样式应尽可能使用现有的 Token，保持一致性
• 组件级 Token 命名规范：Component + 属性名，如 buttonPrimaryColor
• 对 Token 的修改应当向下传递，确保设计系统的一致性

响应式和主题支持

• ✅ 组件应支持在不同屏幕尺寸下良好展示
• ✅ 所有组件必须支持暗色模式
• ✅ 组件应支持从右到左（RTL）的阅读方向
• ✅ 使用 CSS 逻辑属性（如 margin-inline-start）替代方向性属性（如 margin-left）
• ✅ 支持通过 ConfigProvider 进行主题定制

动画效果

• 使用 CSS 过渡实现简单动画
• 复杂动画使用 @rc-component/motion 实现
• 尊重用户的减少动画设置（prefers-reduced-motion）
• 动画时长和缓动函数应保持一致性
• 动画不应干扰用户的操作和阅读体验

可访问性样式

• 遵循 WCAG 2.1 AA 级别标准
• 确保焦点状态有明显的视觉提示
• 提供足够的色彩对比度
• 不依赖颜色来传达信息
• 支持用户放大页面至 200% 时的正常布局
• 避免使用会导致闪烁的动画

---

开发指南

测试指南

测试框架和工具

• 使用 Jest 和 React Testing Library 编写单元测试
• 对 UI 组件使用快照测试（Snapshot Testing）
• 测试覆盖率要求 100%
• 测试文件放在 tests/ 目录，命名格式为：index.test.tsx 或 xxx.test.tsx

运行测试

npm test                    # 运行所有测试
npm test -- --watch        # 监听模式
npm run test:coverage       # 生成覆盖率报告
npm run test:image          # UI 快照测试（需要 Docker）

测试最佳实践

• ✅ 测试用户行为而非实现细节
• ✅ 使用有意义的测试描述
• ✅ 每个测试用例应该独立，不依赖其他测试
• ✅ 测试边界情况和错误处理

演示代码规范

Demo 基本要求

• ✅ demo 代码尽可能简洁
• ✅ 避免冗余代码，方便用户复制到项目直接使用
• ✅ 每个 demo 聚焦展示一个功能点
• ✅ 提供中英文两个版本的说明
• ✅ 遵循展示优先原则，确保视觉效果良好
• ✅ 展示组件的主要使用场景
• ✅ 按照由简到繁的顺序排列 demo

文件组织

• 每个组件演示包含 .md（说明文档）和 .tsx（实际代码）两个文件
• 位置：组件目录下的 demo 子目录，如 components/button/demo/
• 命名：短横线连接的小写英文单词，如 basic.tsx、custom-filter.tsx
• 文件名应简洁地描述示例内容

TSX 代码规范

// ✅ 正确的导入顺序
import React, { useState } from 'react';
import { Button, Space } from 'antd';
import type { ButtonProps } from 'antd';

import './custom.css';

// ✅ 使用函数式组件和 Hooks
const Demo: React.FC = () => {
  const [loading, setLoading] = useState(false);

  const handleClick = () => {
    setLoading(true);
    // ...
  };

  return (
    <Space>
      <Button loading={loading} onClick={handleClick}>
        Click me
      </Button>
    </Space>
  );
};

export default Demo;

规范要点：

• 导入顺序：React → 依赖库 → 组件库 → 自定义组件 → 类型 → 样式
• 类型：为复杂数据定义清晰接口，避免 any
• 使用函数式组件和 Hooks
• 2 空格缩进，箭头函数，驼峰命名
• 优先使用 antd 内置组件，减少外部依赖
• 性能优化：适当使用 useMemo/useCallback，清理副作用

国际化规范

类型定义

antd 的本地化配置的类型定义的入口文件是 components/locale/index.tsx，当需要添加新的本地化配置时，需要检查对应组件或全局配置的类型是否存在，如果不存在，则需要增加相应的类型描述。

本地化配置

• 本地化配置文件命名规则：*_*.ts，如：zh_CN.ts、en_US.ts
• 通常在为 antd 添加或修改某一项本地化配置时，如无特殊说明，需要同时修改所有语言的本地化配置
• 本地化配置的内容通常是纯字符串
• 带有 ${} 的变量将在实际使用的地方被实时替换成对应的变量内容

使用本地化

import { useLocale } from '../locale';
import enUS from '../locale/en_US';

export function TestComp(props) {
  const { locale: propLocale } = props;
  const [contextLocale] = useLocale('TestComp', enUS);

  const locale = { ...contextLocale, ...propLocale };

  return <div title={locale?.title}>{locale?.text}</div>;
}

---

文档和 Changelog 规范

基本要求

• ✅ 提供中英文两个版本
• ✅ 新的属性需要声明可用的版本号
• ✅ 属性命名符合 antd 的 API 命名规则

文档锚点 ID 规范

• 针对 Markdown 文件中的标题（# 到 ######）自动生成锚点 ID
  • 所有中文标题（H1-H6）必须手动指定一个简洁、有意义的英文锚点
  • 格式: ## 中文标题 {#english-anchor-id}
  • 英文标题通常不需要手动指定锚点，但如果需要，可以使用相同的格式
• 锚点 ID 必须符合正则表达式 ^[a-zA-Z][\w-:\.]*$，且长度不应超过 32 个字符
• 用于演示（demo）且包含 -demo- 的 id 不受前面的长度限制
• FAQ 章节下的所有标题锚点必须以 faq- 作为前缀
• 为确保在不同语言间切换时锚点依然有效，同一问题的中英文锚点应保持完全一致

示例：

• 中文标题：### 如何使用组件 {#how-to-use-component}
• 英文标题：### How to Use the Component {#how-to-use-component}

Changelog 规范

🎯 核心原则

1. 文件位置：在 CHANGELOG.en-US.md 和 CHANGELOG.zh-CN.md 书写每个版本的变更

2. 有效性过滤：忽略用户无感知的改动（如文档网站改进、纯测试用例更新、内部重构、工具链优化等），除非其对开发者有直接影响。保持 CHANGELOG 的内容有效性。

3. 开发者视角：用面向开发者的角度和叙述方式撰写 CHANGELOG，描述"用户的原始问题"和"对开发者的影响"，而非"具体的解决代码"。

   • ❌ 修复 Typography 的 DOM 结构问题。
   • ✅ Typography: 💄 重构并简化了 Typography 的 DOM 结构，修复了内容空格丢失的问题。

4. 版本与命名：

   • 新增属性必须符合 antd API 命名规则
   • 新增属性建议在描述中暗示或明确声明可用版本号

5. 双语输出：每次处理必须同时提供 中文版 和 英文版

6. PR 链接：尽量给出原始的 PR 链接，社区提交的 PR 改动加上提交者的链接

🎨 格式与结构规范

1. 单条条目结构：组件名称: 图标 描述内容 [#PR号](链接) [@贡献者]

   • 组件名无需加粗，后接英文冒号和空格

2. 分组逻辑：

   • 多项改动：同一组件有 2 条及以上改动时，使用 - 组件名 作为分类标题（不加粗），具体条目缩进排列
   • 单项改动：直接编写单行条目，不设分类标题

3. 文本细节：

   • 代码包裹：所有属性名、方法名、API、role/aria 属性必须使用反引号 ` 包裹
   • 中英空格：中文与英文、数字、链接、@ 用户名之间必须保留 一个空格

🏷️ Emoji 规范（严格执行）

Emoji	用途
🐞	修复 Bug
💄	样式更新或 token 更新
🆕	新增特性 / 新增属性
🔥	极其值得关注的新增特性
🇺🇸🇨🇳🇬🇧	国际化改动
📖 📝	文档或网站改进
✅	新增或更新测试用例
🛎	更新警告/提示信息
⌨️ ♿	可访问性增强
🗑	废弃或移除
🛠	重构或工具链优化
⚡️	性能提升

💡 输出示例参考

中文版：

- 🐞 Drawer: 修复 Drawer.PurePanel 无法响应鼠标交互的问题。[#56387](https://github.com/ant-design/ant-design/pull/56387) [@wanpan11](https://github.com/wanpan11)
- 🐞 Select: 修复 Select `options` 属性透传至原生 DOM 导致 React 未知属性警告的问题。[#56341](https://github.com/ant-design/ant-design/pull/56341) [@afc163](https://github.com/afc163)

English Version：

- 🐞 Drawer: Fix Drawer.PurePanel failing to respond to mouse interactions. [#56387](https://github.com/ant-design/ant-design/pull/56387) [@wanpan11](https://github.com/wanpan11)
- 🐞 Select: Fix Select `options` props leaking to DOM elements and causing React unknown-prop warnings. [#56341](https://github.com/ant-design/ant-design/pull/56341) [@afc163](https://github.com/afc163)

---

Git 和 Pull Request 规范

分支管理

禁止直接提交到以下保护分支：

• master：主分支，用于发布
• feature：特性分支，用于开发新版本
• next：下一个版本分支

开发流程

1. 从保护分支（通常是 master）创建新的功能分支
2. 在新分支上进行开发
3. 提交 Pull Request 到目标分支
4. 等待 Code Review 和 CI 通过
5. 合并到目标分支

分支命名规范

类型	格式	示例
功能开发	feat/description-of-feature	feat/add-dark-mode
问题修复	fix/issue-number-or-description	fix/button-style-issue
文档更新	docs/what-is-changed	docs/update-api-docs
代码重构	refactor/what-is-changed	refactor/button-component
样式修改	style/what-is-changed	style/fix-button-padding
测试相关	test/what-is-changed	test/add-button-tests
构建相关	build/what-is-changed	build/update-webpack-config
持续集成	ci/what-is-changed	ci/add-github-actions
性能优化	perf/what-is-changed	perf/optimize-render
依赖升级	deps/package-name-version	deps/upgrade-react-19

分支命名注意事项：

1. 使用小写字母
2. 使用连字符（-）分隔单词
3. 简短但具有描述性
4. 避免使用下划线或其他特殊字符
5. 如果与 Issue 关联，可以包含 Issue 编号

Pull Request 规范

PR 标题

• PR 标题始终使用英文
• 遵循格式：类型: 简短描述
• 示例：
  • fix: fix button style issues in Safari browser
  • feat: add dark mode support

PR 内容

• PR 内容默认使用英文
• 尽量简洁清晰地描述改动内容和目的
• 可以视需要在英文描述后附上中文说明

PR 模板

提交 PR 时请使用项目中提供的模板：

• 英文模板（推荐）：PULL_REQUEST_TEMPLATE.md
• 中文模板：PULL_REQUEST_TEMPLATE_CN.md

PR 提交注意事项

1. 合并策略：

   • 新特性请提交至 feature 分支
   • 其余可提交至 master 分支

2. 审核流程：

   • PR 需要由至少一名维护者审核通过后才能合并
   • 确保所有 CI 检查都通过
   • 解决所有 Code Review 中提出的问题

3. PR 质量要求：

   • 确保代码符合项目代码风格
   • 添加必要的测试用例
   • 更新相关文档
   • 大型改动需要更详细的说明和更多的审核者参与

4. 工具标注：

   • 如果是用 Cursor 提交的代码，请在 PR body 末尾进行标注：> Submitted by Cursor

PR 改动类型

• 🆕 新特性提交
• 🐞 Bug 修复
• 📝 文档改进
• 📽️ 演示代码改进
• 💄 样式/交互改进
• 🤖 TypeScript 更新
• 📦 包体积优化
• ⚡️ 性能优化
• 🌐 国际化改进

---

质量保证

代码质量要求

• ✅ 确保代码运行正常，无控制台错误
• ✅ 适配常见浏览器
• ✅ 避免过时 API，及时更新到新推荐用法
• ✅ 测试覆盖率达到 100%
• ✅ 通过所有 ESLint 和 TypeScript 检查

性能要求

• ✅ 避免不必要的重新渲染
• ✅ 合理使用 React.memo、useMemo 和 useCallback
• ✅ 样式计算应当高效，避免重复计算
• ✅ 图片和资源应当优化
• ✅ 支持 Tree Shaking

兼容性要求

• ✅ 支持 React 18 ~ 19 版本
• ✅ 兼容 Chrome 80+ 浏览器
• ✅ 支持服务端渲染（SSR）
• ✅ 保持向下兼容，避免 breaking change
• ✅ 支持 TypeScript 4.0+

---

工具链和环境

开发工具

• 推荐使用 VS Code 或其他支持 TypeScript 的编辑器
• 配置 ESLint 和 Prettier
• 使用 TypeScript 严格模式
• 配置 Git hooks 进行代码检查

构建工具

• 使用 webpack 进行构建
• 支持 ES modules 和 CommonJS
• 提供 UMD 格式的构建产物
• 支持按需加载

CI/CD

• 所有 PR 必须通过 CI 检查
• 包括单元测试、集成测试、类型检查、代码风格检查
• 自动化发布流程
• 支持多环境部署

---

参考资料

• API Naming Rules
• #16048 - Current listing api & Chinese version
• #25066 - API standard in the document
• Development Guide