fix
This commit is contained in:
parent
f843b2d894
commit
933d71c99d
|
|
@ -0,0 +1,148 @@
|
|||
# Cursor Rules for Outfit Web Project
|
||||
|
||||
## 项目概述
|
||||
这是一个基于 React 19 + TypeScript + Vite + Tailwind CSS 的前端项目，使用 shadcn/ui 组件库，包含自动生成的 API 客户端。
|
||||
|
||||
## 技术栈
|
||||
- **前端框架**: React 19
|
||||
- **语言**: TypeScript
|
||||
- **构建工具**: Vite
|
||||
- **样式**: Tailwind CSS 4.x
|
||||
- **UI 组件库**: shadcn/ui (基于 Radix UI)
|
||||
- **图标库**: Lucide React
|
||||
- **工具库**: class-variance-authority, clsx, tailwind-merge
|
||||
- **HTTP 客户端**: Axios
|
||||
- **API 生成**: openapi-typescript-codegen
|
||||
|
||||
## 代码规范
|
||||
|
||||
### TypeScript 规范
|
||||
- 使用严格的 TypeScript 配置
|
||||
- 优先使用类型推断，但为公共 API 和复杂对象显式定义类型
|
||||
- 使用 `interface` 定义对象类型，使用 `type` 定义联合类型和工具类型
|
||||
- 避免使用 `any`，优先使用 `unknown` 或具体类型
|
||||
- 使用泛型提高代码复用性
|
||||
|
||||
### React 组件规范
|
||||
- 使用函数组件和 React Hooks
|
||||
- 组件名使用 PascalCase
|
||||
- 文件名与组件名保持一致
|
||||
- 使用 TypeScript 为 props 定义接口
|
||||
- 优先使用 `useState` 和 `useEffect` 等内置 Hooks
|
||||
- 自定义 Hooks 以 `use` 开头
|
||||
|
||||
### shadcn/ui 组件库规范
|
||||
- 使用 shadcn/ui 作为主要 UI 组件库
|
||||
- 组件配置使用 "new-york" 风格
|
||||
- 组件放在 `src/components/ui/` 目录
|
||||
- 使用 `@/components/ui` 别名导入 UI 组件
|
||||
- 使用 `@/lib/utils` 导入工具函数
|
||||
- 图标使用 Lucide React 库
|
||||
- 遵循 shadcn/ui 的设计原则和可访问性标准
|
||||
- 组件引入、升级、修复请统一使用 `npx shadcn@latest add [component]`，确保与 Tailwind v4、React 19 兼容
|
||||
- 组件样式、主题、变量配置统一在 `components.json` 和 `tailwind.config.ts`/`tailwind.config.js` 中管理，Tailwind v4 下 `config` 字段应留空，主题色用 `baseColor`，如 `neutral`、`zinc` 等
|
||||
- 推荐开启 `cssVariables: true`，用 CSS 变量做主题定制，支持暗色模式
|
||||
- 组件样式冲突时可用 `prefix` 字段（如 `tw-`）隔离 Tailwind 工具类
|
||||
- 组件样式入口通过 `tailwind.css`/`globals.css` 引入
|
||||
- 组件变体、条件样式统一用 `class-variance-authority`、`clsx`、`tailwind-merge` 组合
|
||||
- 推荐使用 `cn()` 工具函数（`clsx`+`tailwind-merge`）合并类名，避免冲突
|
||||
- 组件开发/迁移时优先用函数组件，类型用 `React.ComponentProps<typeof X>` 推断，避免 `forwardRef`，如需 `ref` 用 `data-slot` 辅助样式
|
||||
- 组件升级/迁移时注意 Tailwind v4 新特性（如 `size-*` 替换 `w-* h-*`）
|
||||
- 组件主题色、动画、变量扩展统一用 `cssVars` 和 `theme.extend`，如需自定义色彩/动画，参考官方 registry item 配置
|
||||
- 组件可访问性（a11y）严格遵循 shadcn/ui 官方标准，确保键盘可用、aria 属性齐全、对比度达标
|
||||
- 组件 peerDependencies 必须支持 React 19，升级依赖时如遇 npm ERESOLVE，优先用 `--force` 或 `--legacy-peer-deps` 解决
|
||||
- 组件升级后如有 breaking change，需同步更新相关用法和文档
|
||||
|
||||
### 样式规范
|
||||
- 使用 Tailwind CSS 类名
|
||||
- 使用 `clsx` 和 `tailwind-merge` 进行条件样式组合
|
||||
- 使用 `class-variance-authority` 创建变体组件
|
||||
- 避免内联样式，优先使用 Tailwind 类名
|
||||
- 响应式设计使用 Tailwind 的断点前缀
|
||||
- 使用 CSS 变量进行主题定制（baseColor: neutral）
|
||||
|
||||
### 文件组织
|
||||
- 组件放在 `src/components/` 目录
|
||||
- UI 组件放在 `src/components/ui/` 目录
|
||||
- 页面组件放在 `src/pages/` 目录
|
||||
- 工具函数放在 `src/lib/` 目录
|
||||
- 自定义 Hooks 放在 `src/hooks/` 目录
|
||||
- API 相关代码在 `src/api/` 目录（自动生成）
|
||||
- 类型定义放在 `src/types/` 目录
|
||||
|
||||
### 导入规范
|
||||
- 使用绝对路径导入（`@/` 别名）
|
||||
- 按以下顺序组织导入：
|
||||
1. React 相关
|
||||
2. 第三方库
|
||||
3. shadcn/ui 组件
|
||||
4. 内部组件/工具
|
||||
5. 类型定义
|
||||
6. 样式文件
|
||||
|
||||
### API 使用规范
|
||||
- 使用自动生成的 API 客户端
|
||||
- 在组件中使用 `useApi` Hook 进行 API 调用
|
||||
- 处理加载状态和错误状态
|
||||
- 使用 TypeScript 类型确保类型安全
|
||||
|
||||
### 命名规范
|
||||
- 变量和函数使用 camelCase
|
||||
- 常量使用 UPPER_SNAKE_CASE
|
||||
- 组件使用 PascalCase
|
||||
- 文件使用 kebab-case 或 PascalCase（组件文件）
|
||||
- 类型和接口使用 PascalCase
|
||||
|
||||
### 代码质量
|
||||
- 使用 ESLint 进行代码检查
|
||||
- 遵循 React Hooks 规则
|
||||
- 避免不必要的重新渲染
|
||||
- 使用 React.memo 优化性能
|
||||
- 正确处理副作用和清理
|
||||
|
||||
### 开发工作流
|
||||
- 使用 `npm run dev` 启动开发服务器
|
||||
- 使用 `npm run build` 构建生产版本
|
||||
- 使用 `npm run generate-api` 重新生成 API 客户端
|
||||
- 使用 `npm run lint` 检查代码质量
|
||||
- 使用 `npx shadcn@latest add [component]` 添加新组件
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### shadcn/ui 使用最佳实践
|
||||
- 优先使用 shadcn/ui 提供的组件，避免重复造轮子
|
||||
- 使用 `cn()` 工具函数组合类名
|
||||
- 遵循 shadcn/ui 的可访问性标准
|
||||
- 使用 `class-variance-authority` 创建组件变体
|
||||
- 保持组件的可组合性和可扩展性
|
||||
|
||||
### 状态管理
|
||||
- 对于简单状态，使用 `useState`
|
||||
- 对于复杂状态，考虑使用 `useReducer`
|
||||
- 避免过度使用全局状态
|
||||
|
||||
### 性能优化
|
||||
- 使用 React.memo 包装纯组件
|
||||
- 使用 useCallback 和 useMemo 优化回调函数和计算值
|
||||
- 懒加载路由和组件
|
||||
- 优化图片和资源加载
|
||||
|
||||
### 错误处理
|
||||
- 使用 Error Boundaries 捕获组件错误
|
||||
- 为 API 调用添加适当的错误处理
|
||||
- 提供用户友好的错误信息
|
||||
|
||||
### 可访问性
|
||||
- 使用语义化的 HTML 标签
|
||||
- 添加适当的 ARIA 属性
|
||||
- 确保键盘导航支持
|
||||
- 提供足够的颜色对比度
|
||||
- 遵循 shadcn/ui 的可访问性指南
|
||||
|
||||
## 注意事项
|
||||
- API 客户端是自动生成的，不要手动修改
|
||||
- 使用 Tailwind CSS 4.x 的新特性
|
||||
- 遵循 React 19 的最佳实践
|
||||
- 保持代码简洁和可维护性
|
||||
- shadcn/ui 组件是可定制的，可以根据需要修改
|
||||
- 使用 CSS 变量进行主题定制，支持暗色模式
|
||||
Loading…
Reference in New Issue