mirror of
https://github.com/ant-design/ant-design.git
synced 2025-08-06 16:06:28 +08:00
chore: more cursor rules (#53224)
* feat: add cursor rules in .cursor/rules * docs: add non-component changelog rule * docs: update cursor rules format * feat: update cursor rules * refactor: remove duplicated styles.mdc * Apply suggestions from code review Signed-off-by: afc163 <afc163@gmail.com> * Apply suggestions from code review Signed-off-by: afc163 <afc163@gmail.com> * Delete .cursor/rules/component.mdc Signed-off-by: afc163 <afc163@gmail.com> * Apply suggestions from code review Signed-off-by: afc163 <afc163@gmail.com> * Delete pr_template.txt Signed-off-by: afc163 <afc163@gmail.com> * Delete .cursorrules Signed-off-by: afc163 <afc163@gmail.com> * Apply suggestions from code review Signed-off-by: afc163 <afc163@gmail.com> * Update .cursor/rules/project.mdc Signed-off-by: afc163 <afc163@gmail.com> * Update project.mdc Signed-off-by: afc163 <afc163@gmail.com> * Delete .cursor/rules/implementation.mdc Signed-off-by: afc163 <afc163@gmail.com> * Update project.mdc Signed-off-by: afc163 <afc163@gmail.com> * Apply suggestions from code review Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> Signed-off-by: afc163 <afc163@gmail.com> * feat: add server-side rendering guidelines * update * update --------- Signed-off-by: afc163 <afc163@gmail.com> Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
This commit is contained in:
afc163
GitHub
parent
1596b96163
commit
79425c5dc1
80
.cursor/rules/demo.mdc
Normal file
80
.cursor/rules/demo.mdc
Normal file
@ -0,0 +1,80 @@
|
|||||||
|
---
|
||||||
|
description:
|
||||||
|
globs: components/*/demo/**
|
||||||
|
alwaysApply: false
|
||||||
|
---
|
||||||
|
# Demo 规范
|
||||||
|
|
||||||
|
- demo 代码尽可能简洁
|
||||||
|
- 避免冗余代码，方便用户复制到项目直接使用
|
||||||
|
- 每个 demo 聚焦展示一个功能点
|
||||||
|
- 提供中英文两个版本的说明
|
||||||
|
- demo 文件扩展名：
|
||||||
|
- 基础 demo：.tsx
|
||||||
|
- markdown 说明：.md
|
||||||
|
- 遵循展示优先原则，确保视觉效果良好
|
||||||
|
- 展示组件的主要使用场景
|
||||||
|
- 按照由简到繁的顺序排列 demo
|
||||||
|
- 确保 demo 在各种尺寸下都能正常展示
|
||||||
|
- 对于复杂交互提供必要的操作说明
|
||||||
|
|
||||||
|
## 文件组织
|
||||||
|
|
||||||
|
- 每个组件演示包含 `.md`（说明文档）和 `.tsx`（实际代码）两个文件
|
||||||
|
- 位置：组件目录下的 `demo` 子目录，如 `components/button/demo/`
|
||||||
|
- 命名：短横线连接的小写英文单词，如 `basic.tsx`、`custom-filter.tsx`
|
||||||
|
- 文件名应简洁地描述示例内容
|
||||||
|
|
||||||
|
## MD 文档规范
|
||||||
|
|
||||||
|
- 必须包含 `## zh-CN` 和 `## en-US` 两种语言说明
|
||||||
|
- 内容简洁明了，突出组件特性和用法
|
||||||
|
- 避免冗长段落，必要时使用列表或粗体
|
||||||
|
- 标注注意事项和实验性功能
|
||||||
|
|
||||||
|
## TSX 代码规范
|
||||||
|
|
||||||
|
- 导入顺序：React → 依赖库 → 组件库 → 自定义组件 → 类型 → 样式
|
||||||
|
- 类型：为复杂数据定义清晰接口，避免 `any`
|
||||||
|
- 结构：
|
||||||
|
- 使用函数式组件和 Hooks
|
||||||
|
- 复杂逻辑提取为独立函数
|
||||||
|
- 状态管理用 `useState`/`useEffect`
|
||||||
|
- 风格：
|
||||||
|
- 2空格缩进，箭头函数，驼峰命名
|
||||||
|
- 常量大写+下划线，布尔props用`is`/`has`前缀
|
||||||
|
|
||||||
|
## 示例类型
|
||||||
|
|
||||||
|
1. **基础用法**：展示最简用法，置于首位，代码精简
|
||||||
|
2. **变体展示**：不同大小、类型、状态，合理分组
|
||||||
|
3. **交互演示**：展示状态变化和用户交互
|
||||||
|
4. **数据交互**：展示加载、过滤、排序等
|
||||||
|
5. **边界情况**：空数据、错误状态处理
|
||||||
|
|
||||||
|
## 代码质量
|
||||||
|
|
||||||
|
- 实用且专注于单一功能
|
||||||
|
- 关键处添加简洁注释
|
||||||
|
- 使用有意义的数据和变量
|
||||||
|
- 优先使用 antd 内置组件，减少外部依赖
|
||||||
|
- 性能优化：适当使用 `useMemo`/`useCallback`，清理副作用
|
||||||
|
|
||||||
|
## 命名规则
|
||||||
|
|
||||||
|
- 基础文件：`basic.tsx`、`controlled.tsx` 等
|
||||||
|
- 调试类：使用 `debug-` 前缀
|
||||||
|
- 实验性：使用 `experimental-` 前缀
|
||||||
|
|
||||||
|
## 特殊示例
|
||||||
|
|
||||||
|
- **调试示例**：用于开发测试，通常不在文档显示
|
||||||
|
- **无障碍**：展示标签关联和键盘导航
|
||||||
|
- **响应式**：展示不同视口下的行为
|
||||||
|
- **多语言**：展示国际化配置方法
|
||||||
|
|
||||||
|
## 质量要求
|
||||||
|
|
||||||
|
- 确保代码运行正常，无控制台错误
|
||||||
|
- 适配常见浏览器
|
||||||
|
- 避免过时 API，及时更新到新推荐用法
|
||||||
60
.cursor/rules/docs.mdc
Normal file
60
.cursor/rules/docs.mdc
Normal file
@ -0,0 +1,60 @@
|
|||||||
|
---
|
||||||
|
description: 规范项目文档和 Changelog
|
||||||
|
globs: ["**/CHANGELOG*.md", "components/**/index.*.md"]
|
||||||
|
alwaysApply: false
|
||||||
|
---
|
||||||
|
# 文档和 Changelog 规范
|
||||||
|
|
||||||
|
## 基本要求
|
||||||
|
|
||||||
|
- 提供中英文两个版本
|
||||||
|
- 新的属性需要声明可用的版本号
|
||||||
|
- 属性命名符合 antd 的 API 命名规则：https://github.com/ant-design/ant-design/wiki/API-Naming-rules
|
||||||
|
|
||||||
|
## Changelog 规范
|
||||||
|
|
||||||
|
- 在 CHANGELOG.en-US.md 和 CHANGELOG.zh-CN.md 书写每个版本的变更
|
||||||
|
- 对用户使用上无感知的改动建议（文档修补、微小的样式优化、代码风格重构等等）不要提及，保持 CHANGELOG 的内容有效性
|
||||||
|
- 非 antd 组件的改动（如工程化、构建工具、开发流程等）在 changelog 区块中写 "-"
|
||||||
|
- 用面向开发者的角度和叙述方式撰写 CHANGELOG，不描述修复细节，描述问题和对开发者的影响；描述用户的原始问题，而非你的解决方式
|
||||||
|
|
||||||
|
### 示例
|
||||||
|
|
||||||
|
- 不好的例子：修复组件 Typography 的 dom 结构问题
|
||||||
|
- 好的例子：修复了 List.Item 中内容空格丢失的问题
|
||||||
|
|
||||||
|
### 其他要求
|
||||||
|
|
||||||
|
- 新增属性时，建议用易于理解的语言补充描述用户可以感知的变化
|
||||||
|
- 尽量给出原始的 PR 链接，社区提交的 PR 改动加上提交者的链接
|
||||||
|
- 底层模块升级中间版本要去 rc-component 里找到改动，给出变动说明
|
||||||
|
- 建议参考之前版本的日志写法
|
||||||
|
- 将同组件的改动放在一起，内容子级缩进
|
||||||
|
|
||||||
|
### Changelog Emoji 规范
|
||||||
|
|
||||||
|
- 🐞 Bug 修复
|
||||||
|
- 💄 样式更新或 token 更新
|
||||||
|
- 🆕 新增特性，新增属性
|
||||||
|
- 🔥 极其值得关注的新增特性
|
||||||
|
- 🇺🇸🇨🇳🇬🇧 国际化改动
|
||||||
|
- 📖 📝 文档或网站改进
|
||||||
|
- ✅ 新增或更新测试用例
|
||||||
|
- 🛎 更新警告/提示信息
|
||||||
|
- ⌨️ ♿ 可访问性增强
|
||||||
|
- 🗑 废弃或移除
|
||||||
|
- 🛠 重构或工具链优化
|
||||||
|
- ⚡️ 性能提升
|
||||||
|
|
||||||
|
# 文档规范
|
||||||
|
|
||||||
|
- 提供中英文两个版本
|
||||||
|
- 新属性需声明可用的版本号
|
||||||
|
- 属性命名符合 API 命名规则
|
||||||
|
- 组件文档包含：使用场景、基础用法、API 说明
|
||||||
|
- 文档示例应简洁明了
|
||||||
|
- 属性的描述应清晰易懂
|
||||||
|
- 对复杂功能提供详细说明
|
||||||
|
- 加入 TypeScript 定义
|
||||||
|
- 提供常见问题解答
|
||||||
|
- 更新文档时同步更新中英文版本
|
||||||
128
.cursor/rules/git.mdc
Normal file
128
.cursor/rules/git.mdc
Normal file
@ -0,0 +1,128 @@
|
|||||||
|
---
|
||||||
|
description:
|
||||||
|
globs:
|
||||||
|
alwaysApply: true
|
||||||
|
---
|
||||||
|
# Git 规范
|
||||||
|
|
||||||
|
## 分支管理
|
||||||
|
|
||||||
|
- 禁止直接提交到以下保护分支：
|
||||||
|
- `master`：主分支，用于发布
|
||||||
|
- `feature`：特性分支，用于开发新版本
|
||||||
|
- `next`：下一个版本分支
|
||||||
|
|
||||||
|
## 开发流程
|
||||||
|
|
||||||
|
1. 从保护分支（通常是 `master`）创建新的功能分支
|
||||||
|
2. 在新分支上进行开发
|
||||||
|
3. 提交 Pull Request 到目标分支
|
||||||
|
4. 等待 Code Review 和 CI 通过
|
||||||
|
5. 合并到目标分支
|
||||||
|
|
||||||
|
## 分支命名规范
|
||||||
|
|
||||||
|
- 功能开发：`feat/description-of-feature`
|
||||||
|
- 例如：`feat/add-dark-mode`
|
||||||
|
- 例如：`feat/improve-table-performance`
|
||||||
|
- 问题修复：`fix/issue-number-or-description`
|
||||||
|
- 例如：`fix/button-style-issue`
|
||||||
|
- 例如：`fix/issue-1234`
|
||||||
|
- 文档更新：`docs/what-is-changed`
|
||||||
|
- 例如：`docs/update-api-reference`
|
||||||
|
- 例如：`docs/fix-typos`
|
||||||
|
- 代码重构：`refactor/what-is-changed`
|
||||||
|
- 例如：`refactor/button-component`
|
||||||
|
- 例如：`refactor/remove-deprecated-api`
|
||||||
|
- 样式修改：`style/what-is-changed`
|
||||||
|
- 例如：`style/update-button-tokens`
|
||||||
|
- 例如：`style/improve-mobile-layout`
|
||||||
|
- 测试相关：`test/what-is-changed`
|
||||||
|
- 例如：`test/add-button-test`
|
||||||
|
- 例如：`test/improve-coverage`
|
||||||
|
- 构建相关：`build/what-is-changed`
|
||||||
|
- 例如：`build/upgrade-webpack`
|
||||||
|
- 例如：`build/fix-ts-config`
|
||||||
|
- 持续集成：`ci/what-is-changed`
|
||||||
|
- 例如：`ci/add-e2e-test`
|
||||||
|
- 例如：`ci/fix-deploy-script`
|
||||||
|
- 性能优化：`perf/what-is-changed`
|
||||||
|
- 例如：`perf/optimize-render`
|
||||||
|
- 例如：`perf/reduce-bundle-size`
|
||||||
|
- 依赖升级：`deps/package-name-version`
|
||||||
|
- 例如：`deps/upgrade-react-18`
|
||||||
|
- 例如：`deps/update-dependencies`
|
||||||
|
|
||||||
|
## 分支命名注意事项
|
||||||
|
|
||||||
|
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](mdc:.github/PULL_REQUEST_TEMPLATE.md)
|
||||||
|
- 中文模板：[PULL_REQUEST_TEMPLATE_CN.md](mdc:.github/PULL_REQUEST_TEMPLATE_CN.md)
|
||||||
|
|
||||||
|
### PR 提交注意事项
|
||||||
|
|
||||||
|
1. **合并策略**：
|
||||||
|
|
||||||
|
- 新特性请提交至 `feature` 分支
|
||||||
|
- 其余可提交至 `master` 分支
|
||||||
|
|
||||||
|
2. **审核流程**：
|
||||||
|
|
||||||
|
- PR 需要由至少一名维护者审核通过后才能合并
|
||||||
|
- 确保所有 CI 检查都通过
|
||||||
|
- 解决所有 Code Review 中提出的问题
|
||||||
|
|
||||||
|
3. **PR 质量要求**：
|
||||||
|
|
||||||
|
- 确保代码符合项目代码风格
|
||||||
|
- 添加必要的测试用例
|
||||||
|
- 更新相关文档
|
||||||
|
- 大型改动需要更详细的说明和更多的审核者参与
|
||||||
|
|
||||||
|
4. **工具标注**：
|
||||||
|
- 如果是用 Cursor 提交的代码，请在 PR body 末尾进行标注：`> Submitted by Cursor`
|
||||||
|
|
||||||
|
## 新增内容
|
||||||
|
|
||||||
|
- Pull Request 标题格式：[组件名]: 描述
|
||||||
|
- 从 master 分支创建新分支
|
||||||
|
- 分支命名规范：
|
||||||
|
- feature/xxx：新特性
|
||||||
|
- fix/xxx：Bug 修复
|
||||||
|
- docs/xxx：文档更新
|
||||||
|
- PR 说明中选择改动类型：
|
||||||
|
- 🆕 新特性提交
|
||||||
|
- 🐞 Bug 修复
|
||||||
|
- 📝 文档改进
|
||||||
|
- 📽️ 演示代码改进
|
||||||
|
- 💄 样式/交互改进
|
||||||
|
- 🤖 TypeScript 更新
|
||||||
|
- 📦 包体积优化
|
||||||
|
- ⚡️ 性能优化
|
||||||
|
- 🌐 国际化改进
|
||||||
|
- 提供改动背景和解决方案
|
||||||
|
- 更新日志同时提供英文和中文版本
|
||||||
108
.cursor/rules/naming.mdc
Normal file
108
.cursor/rules/naming.mdc
Normal file
@ -0,0 +1,108 @@
|
|||||||
|
---
|
||||||
|
description:
|
||||||
|
globs:
|
||||||
|
alwaysApply: true
|
||||||
|
---
|
||||||
|
Basically, antd naming requires **FULL NAME** instead of Abbreviation.
|
||||||
|
|
||||||
|
## Props
|
||||||
|
* Initialize prop: `default` + `PropName`
|
||||||
|
* Force render: `forceRender`
|
||||||
|
* Force render sub component: `force` + `Sub Component Name` + `Render`
|
||||||
|
* Sub Component Render: `Sub Component Name` + `Render`. e.g.
|
||||||
|
> panelRender(originNode, info: { SubComponent1, SubComponent2, [somePassedProps]: someValue })
|
||||||
|
* Sub Item Render: `Sub Item Name` + `Render`. e.g.
|
||||||
|
> cellRender(date, info: { [somePassedProps]: someValue })
|
||||||
|
* Data Source: `dataSource`
|
||||||
|
* Panel open: popup & dropdown `open`, additional popup `popupName` + `Open` like `tooltipOpen`
|
||||||
|
* Do not use `visible` to make sure all the visible api align
|
||||||
|
* `children`:
|
||||||
|
* Mainly display content. To avoid additional prop name.
|
||||||
|
* Option list like `Select.Option` or `Tree.TreeNode`.
|
||||||
|
* Customize wrapped component can consider use `component` prop if `children` may have other usage in future.
|
||||||
|
* Display related naming: `show` + `PropName`
|
||||||
|
* Functional: `PropName` + `able`
|
||||||
|
* Disable: `disabled`
|
||||||
|
* sub component: `disabled` + `Sub Component Name`
|
||||||
|
* Extra: `extra`
|
||||||
|
* sub component: `Sub Component Name` + `extra`. e.g. `titleExtra`
|
||||||
|
* mainly icon: `icon`
|
||||||
|
* Merge with function first: `functionName: { icon }`. e.g. `expandable: { icon: <Smile /> }`
|
||||||
|
* Multiple icons: `FunctionName` + `Icon`
|
||||||
|
* Trigger: `trigger`
|
||||||
|
* Sub function trigger: `Sub Function` + `Trigger`
|
||||||
|
* Trigger on the time point: `xxx` + `On` + `EventName` (e.g. `destroyOnClose`)
|
||||||
|
* Component use other component config. Naming as component.(e.g. `<Table pagination={{...}} />`)
|
||||||
|
* ClassName: `className`
|
||||||
|
* Additional classes should be merged into `classes` (e.g. `<Button classes={{ inner: 'custom-inner' }} />`)
|
||||||
|
* Format
|
||||||
|
* Not modify value when blur: `preserveInvalidOnBlur`
|
||||||
|
|
||||||
|
## Event
|
||||||
|
* Trigger event: `on` + `EventName`
|
||||||
|
* Trigger sub component event: `on` + `SubComponentName` + `EventName` (e.g.`onSearchChange`)
|
||||||
|
* Trigger prop event: `on` + `PropName` + `EventName` (e.g.`onDragStart`)
|
||||||
|
* Before trigger event: `before` + `EventName`
|
||||||
|
* After trigger event: `after` + `EventName`
|
||||||
|
* After continuous action, such as drag Slider: `on` + `EventName` + `Complete`
|
||||||
|
|
||||||
|
## Reference
|
||||||
|
|
||||||
|
Component should have `ref` prop. Which should provide the structure:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
ComponentRef {
|
||||||
|
nativeElement: HTMLElement;
|
||||||
|
// Other function
|
||||||
|
focus: VoidFunction;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Component Token
|
||||||
|
`variant (optional)` + `semantic part` + `semantic part variant (optional)` + `css property` + `size/disabled (optional)`
|
||||||
|
|
||||||
|
All component tokens should follow the structure above, and should not conflict with Global Token.
|
||||||
|
* `variant` means this token only works in certain variant, like `horizontal` `borderless`.
|
||||||
|
* `semantic part` means the typical element of component, like `item` `header`. If there's.
|
||||||
|
* `semantic part status` means the variant of the semantic part before it, like `hover` `selected`.
|
||||||
|
* `css property` means the exact property where the token is used, like `fontSize` `width`.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
| v4 | v5 | Note |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `@menu-item-color` | `itemColor` | Remove the component prefix |
|
||||||
|
| `@select-item-selected-bg` | `itemSelectedBg` | `selected` is variant of item |
|
||||||
|
| `@select-single-item-height-lg` | `itemHeightLG` | `single` is variant of Select (by default), `LG` is size of Select |
|
||||||
|
|
||||||
|
> Note: If there's no semantic part for one component token, for example, the root borderRadius of Button, it is not suitable to add it. Because we could modify it easily with `className` and `style`.
|
||||||
|
|
||||||
|
## Current listing api & Chinese version
|
||||||
|
ref: [#16048](mdc:https:/github.com/ant-design/ant-design/issues/16048)
|
||||||
|
|
||||||
|
## API standard in the document
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
| Property | Description | Type | Default |
|
||||||
|
| --------- | ---------------------- | ------------------------------ | ------ |
|
||||||
|
| htmlType | xxx | string | `button ` |
|
||||||
|
| type | xxx | `horizontal ` \| `vertical ` | `horizontal` |
|
||||||
|
| disabled | xxx | boolean | false |
|
||||||
|
| minLength | xxx | number | 0 |
|
||||||
|
| style | xxx | CSSProperties | - |
|
||||||
|
| character | xxx | (props) => ReactNode | - |
|
||||||
|
| offset | xxx| \[number, number] | \[0, 0] |
|
||||||
|
| value | xxx | string \| number | `small` |
|
||||||
|
|
||||||
|
### Promise
|
||||||
|
- When string type, the **Default** use ` `` `.
|
||||||
|
- Can also list string optional values in **Type**.
|
||||||
|
- When boolean type, the **Default** value is true or false.
|
||||||
|
- When number type, the **Default** value use numbers directly.
|
||||||
|
- When function type, use an arrow function expression in **Type**.
|
||||||
|
- No default value use - .
|
||||||
|
- Capitalize the first letter in **Description** apart from `someProp`.
|
||||||
|
- No period at the end of the **Description**.
|
||||||
|
- API order is arranged in alphabetical order, and can be put together under special circumstances (such as: xs sm md).
|
||||||
|
|
||||||
|
ref: [#25066](mdc:https:/github.com/ant-design/ant-design/issues/25066)
|
||||||
27
.cursor/rules/project.mdc
Normal file
27
.cursor/rules/project.mdc
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
---
|
||||||
|
description:
|
||||||
|
globs:
|
||||||
|
alwaysApply: true
|
||||||
|
---
|
||||||
|
# 项目背景
|
||||||
|
|
||||||
|
这是 ant-design/ant-design（antd）的源代码仓库，是一个 React 组件库，发布为 npm 包 antd。
|
||||||
|
|
||||||
|
- 使用 TypeScript 和 React 开发
|
||||||
|
- 兼容 React 16 ~ 19 版本
|
||||||
|
- 组件库设计精美，功能完善，广泛应用于企业级中后台产品
|
||||||
|
- 遵循 Ant Design 设计规范
|
||||||
|
- 支持国际化
|
||||||
|
|
||||||
|
# 编码规范
|
||||||
|
|
||||||
|
- 使用 TypeScript 和 React 书写
|
||||||
|
- 使用函数式组件和 hooks，避免类组件
|
||||||
|
- 使用提前返回（early returns）提高代码可读性
|
||||||
|
- 避免引入新依赖，严控打包体积
|
||||||
|
- 兼容 Chrome 80+ 浏览器
|
||||||
|
- 支持服务端渲染
|
||||||
|
- 保持向下兼容，避免 breaking change
|
||||||
|
- 组件名使用大驼峰（PascalCase）
|
||||||
|
- 属性名使用小驼峰（camelCase）
|
||||||
|
- 合理使用 React.memo、useMemo 和 useCallback 优化性能
|
||||||
79
.cursor/rules/styling.mdc
Normal file
79
.cursor/rules/styling.mdc
Normal file
@ -0,0 +1,79 @@
|
|||||||
|
---
|
||||||
|
description:
|
||||||
|
globs: components/*/style/**
|
||||||
|
alwaysApply: false
|
||||||
|
---
|
||||||
|
# 样式规范
|
||||||
|
|
||||||
|
## 样式方案
|
||||||
|
|
||||||
|
- 使用 `@ant-design/cssinjs` 作为样式解决方案
|
||||||
|
- 每个组件的样式应该放在 `style/` 目录下
|
||||||
|
- 样式文件应该与组件结构保持一致
|
||||||
|
- 使用 CSS-in-JS 时应当注意性能影响，避免不必要的样式重计算
|
||||||
|
- 样式生成函数应遵循 `gen[ComponentName]Style` 的命名规范
|
||||||
|
- 样式覆盖应使用类选择器而非标签选择器，提高样式特异性
|
||||||
|
|
||||||
|
## Token 系统
|
||||||
|
|
||||||
|
- 使用 Ant Design 的设计 Token 系统
|
||||||
|
- 避免硬编码颜色、尺寸、间距等值
|
||||||
|
- 组件样式应基于全局 Token 和组件级 Token
|
||||||
|
- 自定义样式应尽可能使用现有的 Token，保持一致性
|
||||||
|
- 组件级 Token 命名规范：`Component` + 属性名，如 `buttonPrimaryColor`
|
||||||
|
- 对 Token 的修改应当向下传递，确保设计系统的一致性
|
||||||
|
|
||||||
|
## 响应式设计
|
||||||
|
|
||||||
|
- 组件应支持在不同屏幕尺寸下良好展示
|
||||||
|
- 使用相对单位（如 em、rem）而非固定像素值
|
||||||
|
- 关键断点应与设计系统保持一致
|
||||||
|
- 在小屏幕上提供良好的降级方案
|
||||||
|
- 使用 CSS Grid 和 Flexbox 布局实现响应式布局
|
||||||
|
- 考虑移动设备上的触摸交互体验
|
||||||
|
|
||||||
|
## 暗色模式
|
||||||
|
|
||||||
|
- 所有组件必须支持暗色模式
|
||||||
|
- 暗色模式应通过 Token 系统实现，不应硬编码
|
||||||
|
- 测试暗色模式下的颜色对比度，确保可访问性
|
||||||
|
- 在设计暗色模式时考虑降低亮度和饱和度
|
||||||
|
- 确保文本在暗色背景上有足够的对比度
|
||||||
|
- 图片和图标应提供适合暗色模式的版本
|
||||||
|
|
||||||
|
## RTL 支持
|
||||||
|
|
||||||
|
- 组件应支持从右到左（RTL）的阅读方向
|
||||||
|
- 使用 CSS 逻辑属性（如 margin-inline-start）替代方向性属性（如 margin-left）
|
||||||
|
- 图标和方向性元素应随 RTL 模式翻转
|
||||||
|
- 测试组件在 RTL 模式下的布局和交互
|
||||||
|
- 确保文本对齐和方向符合 RTL 规范
|
||||||
|
- 处理好数字和日期等特殊内容在 RTL 模式下的显示
|
||||||
|
|
||||||
|
## 动画效果
|
||||||
|
|
||||||
|
- 使用 CSS 过渡实现简单动画
|
||||||
|
- 复杂动画使用 rc-motion 实现
|
||||||
|
- 尊重用户的减少动画设置（prefers-reduced-motion）
|
||||||
|
- 动画时长和缓动函数应保持一致性
|
||||||
|
- 动画不应干扰用户的操作和阅读体验
|
||||||
|
- 为关键操作提供合适的反馈动画
|
||||||
|
- 避免使用会导致性能问题的 CSS 属性（如 box-shadow）进行动画
|
||||||
|
|
||||||
|
## 主题定制
|
||||||
|
|
||||||
|
- 支持通过 ConfigProvider 进行主题定制
|
||||||
|
- 提供完整的组件级 Token 配置
|
||||||
|
- 保持向后兼容性，不轻易改变 Token 含义
|
||||||
|
- 避免在组件内使用不可覆盖的样式
|
||||||
|
- 提供主题切换的平滑过渡效果
|
||||||
|
- 测试自定义主题在各种组件组合下的效果
|
||||||
|
|
||||||
|
## 可访问性样式
|
||||||
|
|
||||||
|
- 遵循 WCAG 2.1 AA 级别标准
|
||||||
|
- 确保焦点状态有明显的视觉提示
|
||||||
|
- 提供足够的色彩对比度
|
||||||
|
- 不依赖颜色来传达信息
|
||||||
|
- 支持用户放大页面至 200% 时的正常布局
|
||||||
|
- 避免使用会导致闪烁的动画
|
||||||
11
.cursor/rules/testing.mdc
Normal file
11
.cursor/rules/testing.mdc
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
---
|
||||||
|
description:
|
||||||
|
globs: **/__tests__/**,**/*.test.tsx,**/*.test.ts
|
||||||
|
alwaysApply: false
|
||||||
|
---
|
||||||
|
# 测试规范
|
||||||
|
|
||||||
|
- 使用 Jest 和 React Testing Library 编写单元测试
|
||||||
|
- 对 UI 组件使用快照测试 (Snapshot Testing)
|
||||||
|
- 测试覆盖率要求 100%
|
||||||
|
- 测试文件放在 __tests__ 目录，命名格式为：index.test.tsx 或 xxx.test.tsx
|
||||||
81
.cursor/rules/typescript.mdc
Normal file
81
.cursor/rules/typescript.mdc
Normal file
@ -0,0 +1,81 @@
|
|||||||
|
# TypeScript 规范
|
||||||
|
|
||||||
|
## 基本原则
|
||||||
|
|
||||||
|
- 所有组件和函数必须提供准确的类型定义
|
||||||
|
- 避免使用 `any` 类型，尽可能精确地定义类型
|
||||||
|
- 使用接口而非类型别名定义对象结构
|
||||||
|
- 导出所有公共接口类型，方便用户使用
|
||||||
|
- 严格遵循 TypeScript 类型设计原则，确保类型安全
|
||||||
|
- 确保编译无任何类型错误或警告
|
||||||
|
|
||||||
|
## 组件类型定义
|
||||||
|
|
||||||
|
- 组件 props 应使用 interface 定义，便于扩展
|
||||||
|
- 组件 props 接口命名应为 `ComponentNameProps`
|
||||||
|
- 为组件状态定义专门的接口，如 `ComponentNameState`
|
||||||
|
- 复杂的数据结构应拆分为多个接口定义
|
||||||
|
- 组件的 ref 类型应该明确定义，使用 `React.ForwardRefRenderFunction`
|
||||||
|
- 所有回调函数类型应明确定义参数和返回值
|
||||||
|
|
||||||
|
## 泛型使用
|
||||||
|
|
||||||
|
- 适当使用泛型增强类型灵活性
|
||||||
|
- 为泛型参数提供合理的默认类型和约束
|
||||||
|
- 避免过度使用泛型导致类型复杂化
|
||||||
|
- 在泛型参数上应用限制条件（constraints）确保类型安全
|
||||||
|
- 为复杂泛型提供类型别名以提高可读性
|
||||||
|
|
||||||
|
## 类型合并与扩展
|
||||||
|
|
||||||
|
- 使用交叉类型（&）合并多个类型
|
||||||
|
- 使用 Partial<T>、Pick<T, K>、Omit<T, K> 等工具类型修改现有类型
|
||||||
|
- 扩展原生 DOM 元素属性时，继承相应的内置类型
|
||||||
|
- 使用 type 定义联合类型和交叉类型
|
||||||
|
- 优先使用自带的工具类型，避免重复定义
|
||||||
|
|
||||||
|
## 枚举和常量
|
||||||
|
|
||||||
|
- 使用字面量联合类型定义有限的选项集合
|
||||||
|
- 为复杂的枚举值提供类型守卫函数
|
||||||
|
- 避免使用 `enum`，优先使用联合类型和 `as const`
|
||||||
|
- 对于关键常量，使用 `as const` 断言确保类型严格
|
||||||
|
- 为联合类型中的每个值提供适当的注释
|
||||||
|
|
||||||
|
## 类型推断与断言
|
||||||
|
|
||||||
|
- 尽可能依赖 TypeScript 的类型推断
|
||||||
|
- 只在必要时使用类型断言（as）
|
||||||
|
- 使用类型守卫函数进行运行时类型检查
|
||||||
|
- 避免使用非空断言操作符（!）
|
||||||
|
- 使用 `instanceof` 和 `typeof` 进行类型守卫
|
||||||
|
- 为自定义类型创建类型谓词（type predicates）函数
|
||||||
|
|
||||||
|
## JSDoc 注释
|
||||||
|
|
||||||
|
- 为复杂的类型、函数、组件添加 JSDoc 注释
|
||||||
|
- 使用 `@deprecated` 标记已废弃的 API
|
||||||
|
- 在注释中提供使用示例
|
||||||
|
- 说明参数和返回值的含义与约束
|
||||||
|
- 在 interface 和重要类型定义上添加文档注释
|
||||||
|
- 使用 `@template` 标记泛型参数
|
||||||
|
|
||||||
|
## 类型兼容性
|
||||||
|
|
||||||
|
- 确保类型定义兼容不同版本的 React
|
||||||
|
- 避免使用实验性或不稳定的 TypeScript 特性
|
||||||
|
- 为第三方库未提供的类型编写声明文件
|
||||||
|
- 使用条件类型处理复杂的类型逻辑
|
||||||
|
- 验证类型在不同 TypeScript 版本下的兼容性
|
||||||
|
|
||||||
|
## 严格使用 TypeScript 类型
|
||||||
|
|
||||||
|
- 导出组件类型和接口
|
||||||
|
- 使用 React.FC<Props> 或明确的返回类型
|
||||||
|
- 避免使用 any，优先使用 unknown
|
||||||
|
- 组件 Props 使用 interface 定义
|
||||||
|
- 工具类型使用 type 定义
|
||||||
|
- 使用明确的命名约定
|
||||||
|
- 合理使用泛型提高复用性
|
||||||
|
- 导出类型时使用 export type
|
||||||
|
- 组件属性使用 JSDoc 注释说明用途
|
||||||
76
.cursorrules
76
.cursorrules
@ -1,76 +0,0 @@
|
|||||||
## 项目背景
|
|
||||||
|
|
||||||
这是 ant-design/ant-design（antd）的源代码仓库，是一个 React 组件库，发布为 npm 包 antd 。
|
|
||||||
|
|
||||||
## 编码规范
|
|
||||||
|
|
||||||
- 使用 TypeScript 和 React 书写
|
|
||||||
- 兼容 React 16 ~ 19 版本
|
|
||||||
- 使用 @ant-design/cssinjs 书写 css
|
|
||||||
- 使用 @ant-design/icons 图标库
|
|
||||||
- 使用函数式组件和 hooks，避免类组件
|
|
||||||
- 尽可能使用提前返回（early returns）以提高代码的可读性
|
|
||||||
- 避免引入新的依赖，严控打包体积
|
|
||||||
- demo 代码尽可能简洁，避免冗余代码，方便用户复制到应用项目里直接可用
|
|
||||||
- 兼容 chrome 80+ 浏览器
|
|
||||||
- 修改时请保持向下兼容，避免制造 break change
|
|
||||||
|
|
||||||
## 测试要求
|
|
||||||
|
|
||||||
- 使用 Jest 和 React Testing Library 编写单元测试
|
|
||||||
- 对 UI 组件使用快照测试 (Snapshot Testing)
|
|
||||||
- 测试覆盖率要求 100%
|
|
||||||
|
|
||||||
# 文档规范
|
|
||||||
|
|
||||||
- 提供中英文两个版本
|
|
||||||
- 新的属性需要声明可用的版本号
|
|
||||||
- 属性命名符合 antd 的 API 命名规则：https://github.com/ant-design/ant-design/wiki/API-Naming-rules
|
|
||||||
|
|
||||||
## Changelog 规范
|
|
||||||
|
|
||||||
- 在 CHANGELOG.en-US.md 和 CHANGELOG.zh-CN.md 书写每个版本的变更
|
|
||||||
- 对用户使用上无感知的改动建议（文档修补、微小的样式优化、代码风格重构等等）不要提及，保持 CHANGELOG 的内容有效性。
|
|
||||||
- 用面向开发者的角度和叙述方式撰写 CHANGELOG，不描述修复细节，描述问题和对开发者的影响；描述用户的原始问题，而非你的解决方式。
|
|
||||||
* 例子一
|
|
||||||
bad: 修复组件 Typography 的 dom 结构问题。
|
|
||||||
good: 重构并简化了 List Item 的 dom 结构，并且修复了 Item 中内容空格丢失的问题。
|
|
||||||
* 例子二
|
|
||||||
bad: 修复 lib 下样式文件路径问题。
|
|
||||||
good: 修复部分组件样式丢失的问题。
|
|
||||||
- 新增属性时，建议用易于理解的语言补充描述用户可以感知的变化。（例如，新增 onCellClick 属性，可以定义单元格点击事件）
|
|
||||||
- 尽量给出原始的 PR 链接，社区提交的 PR 改动加上提交者的链接。
|
|
||||||
- 底层模块升级中间版本要去 rc-component 里找到改动，给出变动说明。
|
|
||||||
- 建议参考之前版本的日志写法
|
|
||||||
- 将同组件的改动放在一起，内容子级缩进。
|
|
||||||
- 每一个改动前加 emoji 增加更新日志的可读性和生动性，可选 emoji 参考：
|
|
||||||
- 🐞 Bug 修复
|
|
||||||
- 💄 样式更新或 token 更新
|
|
||||||
- 🆕 新增特性，新增属性
|
|
||||||
- 🔥 极其值得关注的新增特性
|
|
||||||
- 🇺🇸🇨🇳🇬🇧 国际化改动，注意这里直接用对应国家/地区的旗帜。
|
|
||||||
- 📖 📝 文档或网站改进
|
|
||||||
- ✅ 新增或更新测试用例
|
|
||||||
- 🛎 更新警告/提示信息
|
|
||||||
- ⌨️ ♿ 可访问性增强
|
|
||||||
- 🗑 废弃或移除
|
|
||||||
- 🛠 重构或工具链优化
|
|
||||||
- ⚡️ 性能提升
|
|
||||||
|
|
||||||
## 实现要求
|
|
||||||
|
|
||||||
你是一名资深的前端开发工程师，同时也是 React、Ant Design、TypeScript、HTML、CSS 的专家。你思维缜密，能够给出细致入微的答案，并且在逻辑推理方面表现出色。你会谨慎地提供准确、真实、深思熟虑的答案，并且擅长逻辑推理。
|
|
||||||
|
|
||||||
- 严格遵循用户的需求，逐字逐句完成。
|
|
||||||
- 首先逐步思考——用伪代码详细描述你要构建的内容的计划。
|
|
||||||
- 确认后，再编写代码！
|
|
||||||
- 始终编写正确、符合最佳实践、遵循 DRY 原则（不要重复自己）、无错误、功能齐全且可运行的代码。
|
|
||||||
- 注重代码的易读性和可维护性。
|
|
||||||
- 非常关注代码压缩后的体积。
|
|
||||||
- 全面实现所有请求的功能。
|
|
||||||
- 不留任何待办事项、占位符或缺失的部分。
|
|
||||||
- 确保代码完整！彻底验证最终结果。
|
|
||||||
- 包含所有必要的导入，并确保关键组件的命名得当。
|
|
||||||
- 简洁明了，尽量减少其他冗长的说明。
|
|
||||||
- 如果你认为可能没有正确的答案，请明确说明。
|
|
||||||
- 如果你不知道答案，请坦诚说明，而不是猜测。
|
|
||||||
Loading…
Reference in New Issue
Block a user