cloud
48 lines
1.5 KiB
Markdown
48 lines
1.5 KiB
Markdown
---
|
||
name: frontend-ui-conventions
|
||
description: 前端 UI 通用规范。用于本仓库 React 前端开发时，统一技术栈、暗色主题、CSS Modules、对话框与 API 层约束。
|
||
---
|
||
|
||
# 前端通用规范
|
||
|
||
## 技术栈约束
|
||
|
||
- React + Vite
|
||
- 路由：React Router
|
||
- 状态：Zustand（如现有模块已采用）
|
||
- 样式：CSS Modules
|
||
- 网络：原生 `fetch`（统一走 `utils/api.js`）
|
||
|
||
## 主题与视觉
|
||
|
||
- 保持暗色主题一致，不引入突兀浅色块
|
||
- 颜色、边框、文字层级沿用现有页面设计
|
||
- 新页面优先复用已有组件和样式变量
|
||
|
||
## 组件复用规则
|
||
|
||
- 改页面前先检索现有自定义组件，优先复用，不重复造轮子
|
||
- 公共可复用组件统一放 `src/components/common/`，页面私有组件再放业务目录
|
||
- 若必须新增组件，先评估是否可扩展已有组件（例如通过 `props`/插槽）而不是复制一份新实现
|
||
- `frontend/config_app` 与 `frontend/cloud_app` 各自维护本工程公共组件目录，但复用策略保持一致
|
||
|
||
## 交互规则
|
||
|
||
- 对话框统一走 `frontend-dialog` 规范
|
||
- 只读展示、下拉控件统一走 `frontend-conventions` 规范
|
||
- 需要确认的危险操作必须二次确认
|
||
|
||
## API 约束
|
||
|
||
- 统一封装在 `utils/api.js`
|
||
- 请求/响应字段统一 `snake_case`
|
||
- 错误提示统一入口，不在页面散写不同风格处理
|
||
|
||
## 文件组织
|
||
|
||
- 页面放 `pages/`
|
||
- 组件放 `components/`
|
||
- 公共组件放 `components/common/`
|
||
- Hook 与状态放 `hooks/`
|
||
- 工具与 API 放 `utils/`
|