docs(project): 完善开发规范和最佳实践文档
- 新增页面开发规范，涵盖表格样式和主题色彩规范 - 添加表单验证处理的统一标准和错误处理机制 - 完善代码示例和最佳实践指导 - 规范化开发流程，提升代码质量和一致性 - 为团队协作提供清晰的开发指南
This commit is contained in:
Leo
parent
78cb6ea782
commit
4d2d428423
279
CLAUDE.md
279
CLAUDE.md
@ -922,6 +922,285 @@ async function handleSubmit() {
|
||||
- ❌ 省略 `lang="ts"` 属性
|
||||
- ❌ 在全局组件中省略 `scoped` 属性
|
||||
|
||||
## 📝 页面开发规范（强制要求）
|
||||
|
||||
**在开发新页面和功能时，必须严格遵循以下UI和主题规范**
|
||||
|
||||
### 表格样式规范
|
||||
1. **表头字体规范**：
|
||||
- ✅ 表头字段字体不需要加粗，与表格数据字体保持一致
|
||||
- ✅ 使用 Naive UI DataTable 的默认样式，不额外设置 `font-weight: bold`
|
||||
- ✅ 确保表头和表格内容具有统一的视觉效果
|
||||
|
||||
```vue
|
||||
<!-- ✅ 正确：不对表头添加额外样式 -->
|
||||
<NDataTable
|
||||
:columns="columns"
|
||||
:data="tableData"
|
||||
:loading="loading"
|
||||
/>
|
||||
|
||||
<!-- ❌ 错误：不要为表头添加加粗样式 -->
|
||||
<NDataTable
|
||||
:columns="columns"
|
||||
:data="tableData"
|
||||
:loading="loading"
|
||||
:th-style="{ fontWeight: 'bold' }"
|
||||
/>
|
||||
```
|
||||
|
||||
### 动态主题色彩规范
|
||||
2. **主题色彩一致性**：
|
||||
- ✅ 所有标签、按钮、状态指示器必须使用系统动态主题色彩
|
||||
- ✅ 使用 CSS 变量而非硬编码颜色值
|
||||
- ✅ 遵循项目的主题色彩体系，确保在主题切换时保持一致性
|
||||
|
||||
```vue
|
||||
<!-- ✅ 正确：使用系统主题色彩 -->
|
||||
<template>
|
||||
<!-- 状态标签 - 使用主题色彩 -->
|
||||
<NTag type="success" size="small">
|
||||
启用
|
||||
</NTag>
|
||||
<NTag type="warning" size="small">
|
||||
待审核
|
||||
</NTag>
|
||||
<NTag type="error" size="small">
|
||||
禁用
|
||||
</NTag>
|
||||
|
||||
<!-- 主要操作按钮 - 使用主题色彩 -->
|
||||
<NButton type="primary">
|
||||
新增
|
||||
</NButton>
|
||||
<NButton type="info">
|
||||
编辑
|
||||
</NButton>
|
||||
<NButton type="error">
|
||||
删除
|
||||
</NButton>
|
||||
|
||||
<!-- 自定义颜色时使用CSS变量 -->
|
||||
<div
|
||||
class="status-indicator" :style="{
|
||||
backgroundColor: 'var(--primary-color)',
|
||||
color: 'var(--primary-color-hover)',
|
||||
}"
|
||||
>
|
||||
状态指示器
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
/* ✅ 正确：使用CSS变量保持主题一致性 */
|
||||
.status-indicator {
|
||||
border: 1px solid var(--border-color);
|
||||
background-color: var(--card-color);
|
||||
color: var(--text-color-base);
|
||||
}
|
||||
|
||||
/* ❌ 错误：不要使用硬编码颜色 */
|
||||
.status-indicator-wrong {
|
||||
border: 1px solid #e0e0e0;
|
||||
background-color: #1890ff;
|
||||
color: #ffffff;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
### 常用主题色彩变量
|
||||
```css
|
||||
/* 主要色彩 */
|
||||
var(--primary-color) /* 主题色 */
|
||||
var(--primary-color-hover) /* 主题色悬停 */
|
||||
var(--primary-color-pressed) /* 主题色按下 */
|
||||
|
||||
/* 文本色彩 */
|
||||
var(--text-color-base) /* 基础文本色 */
|
||||
var(--text-color-1) /* 一级文本色 */
|
||||
var(--text-color-2) /* 二级文本色 */
|
||||
var(--text-color-3) /* 三级文本色 */
|
||||
|
||||
/* 背景色彩 */
|
||||
var(--body-color) /* 页面背景色 */
|
||||
var(--card-color) /* 卡片背景色 */
|
||||
var(--modal-color) /* 弹框背景色 */
|
||||
|
||||
/* 边框色彩 */
|
||||
var(--border-color) /* 边框色 */
|
||||
var(--divider-color) /* 分割线色 */
|
||||
|
||||
/* 状态色彩 */
|
||||
var(--success-color) /* 成功色 */
|
||||
var(--warning-color) /* 警告色 */
|
||||
var(--error-color) /* 错误色 */
|
||||
var(--info-color) /* 信息色 */
|
||||
```
|
||||
|
||||
### 严格禁止行为
|
||||
- ❌ 对表格表头设置 `font-weight: bold` 或其他加粗样式
|
||||
- ❌ 使用硬编码的颜色值（如 `#1890ff`、`#ff4d4f` 等）
|
||||
- ❌ 忽略主题切换时的色彩适配
|
||||
- ❌ 使用与系统主题不一致的自定义颜色方案
|
||||
- ❌ 在标签、按钮等组件上使用固定颜色样式
|
||||
|
||||
### 示例：完整的表格页面实现
|
||||
```vue
|
||||
<template>
|
||||
<div class="page-container">
|
||||
<!-- 操作区域 -->
|
||||
<div class="action-bar">
|
||||
<NButton type="primary" @click="handleAdd">
|
||||
<template #icon>
|
||||
<NIcon><icon-park-outline:plus /></NIcon>
|
||||
</template>
|
||||
新增
|
||||
</NButton>
|
||||
</div>
|
||||
|
||||
<!-- 数据表格 - 表头不加粗，使用默认样式 -->
|
||||
<NDataTable
|
||||
:columns="columns"
|
||||
:data="tableData"
|
||||
:loading="loading"
|
||||
:pagination="pagination"
|
||||
/>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
// 表格列定义 - 不设置表头加粗样式
|
||||
const columns = [
|
||||
{ title: '用户名', key: 'username' },
|
||||
{ title: '状态', key: 'status', render: renderStatus },
|
||||
{ title: '操作', key: 'actions', render: renderActions }
|
||||
]
|
||||
|
||||
// 状态渲染 - 使用系统主题色彩
|
||||
function renderStatus(row: UserVo) {
|
||||
const statusMap = {
|
||||
1: { type: 'success' as const, text: '启用' },
|
||||
0: { type: 'error' as const, text: '禁用' }
|
||||
}
|
||||
const config = statusMap[row.status] || { type: 'default' as const, text: '未知' }
|
||||
|
||||
return h(NTag, {
|
||||
type: config.type,
|
||||
size: 'small'
|
||||
}, { default: () => config.text })
|
||||
}
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.page-container {
|
||||
background-color: var(--body-color);
|
||||
color: var(--text-color-base);
|
||||
}
|
||||
|
||||
.action-bar {
|
||||
padding: 16px;
|
||||
background-color: var(--card-color);
|
||||
border-bottom: 1px solid var(--divider-color);
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
**遵循此规范确保页面具有统一的视觉效果和良好的主题适配性！**
|
||||
|
||||
## 📝 表单验证规范（强制要求）
|
||||
|
||||
**所有包含表单提交的页面都必须实现统一的表单验证和错误处理机制**
|
||||
|
||||
### 表单验证处理原则
|
||||
1. **分离验证逻辑**：将表单验证和API调用分开处理
|
||||
2. **统一错误提示**：使用项目封装的消息提示函数
|
||||
3. **用户友好提示**：验证失败时给予明确的指导信息
|
||||
4. **一致性体验**：所有表单页面使用相同的验证处理模式
|
||||
|
||||
### 必须实现的验证流程
|
||||
|
||||
**✅ 正确的表单提交函数实现**
|
||||
```typescript
|
||||
// 提交表单
|
||||
async function handleSubmit() {
|
||||
if (!formRef.value)
|
||||
return
|
||||
|
||||
try {
|
||||
// 先进行表单验证
|
||||
await formRef.value.validate()
|
||||
}
|
||||
catch {
|
||||
// 表单验证失败，提示用户检查填写内容
|
||||
coiMsgWarning('验证失败，请检查填写内容')
|
||||
return
|
||||
}
|
||||
|
||||
// 表单验证通过，执行API调用
|
||||
try {
|
||||
const submitData = { ...formData.value }
|
||||
|
||||
const { isSuccess } = isEdit.value ? await updateData(submitData) : await addData(submitData)
|
||||
|
||||
if (isSuccess) {
|
||||
coiMsgSuccess(isEdit.value ? '修改成功' : '新增成功')
|
||||
dialogRef.value?.coiClose()
|
||||
await refreshData()
|
||||
}
|
||||
else {
|
||||
coiMsgError(isEdit.value ? '修改失败，请稍后重试' : '新增失败，请稍后重试')
|
||||
}
|
||||
}
|
||||
catch (error) {
|
||||
if (error instanceof Error) {
|
||||
coiMsgError(error.message || (isEdit.value ? '修改失败，请检查网络连接' : '新增失败，请检查网络连接'))
|
||||
}
|
||||
else {
|
||||
coiMsgError(isEdit.value ? '修改失败，请检查网络连接' : '新增失败，请检查网络连接')
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 必要的导入依赖
|
||||
```typescript
|
||||
import { coiMsgError, coiMsgSuccess, coiMsgWarning } from '@/utils/coi'
|
||||
```
|
||||
|
||||
### 适用场景
|
||||
- ✅ 新增/编辑表单页面
|
||||
- ✅ 用户注册/登录表单
|
||||
- ✅ 设置/配置表单
|
||||
- ✅ 搜索表单（如需验证）
|
||||
- ✅ 任何包含用户输入和提交的表单
|
||||
|
||||
### 验证消息规范
|
||||
- **验证失败**: `coiMsgWarning('验证失败，请检查填写内容')`
|
||||
- **操作成功**: `coiMsgSuccess('操作成功')` 或具体操作说明
|
||||
- **操作失败**: `coiMsgError('操作失败，请检查网络连接')` 或具体错误信息
|
||||
|
||||
### 已实现的参考示例
|
||||
- ✅ 角色管理页面：`src/views/system/role/index.vue:1121-1153`
|
||||
- ✅ 菜单管理页面：`src/views/system/menu/index.vue:1360-1407`
|
||||
|
||||
### 严格禁止行为
|
||||
- ❌ 直接提交表单不进行验证
|
||||
- ❌ 验证失败时不给出提示信息
|
||||
- ❌ 使用原生alert()或console.log()进行错误提示
|
||||
- ❌ 验证逻辑与API调用耦合在同一个try-catch中
|
||||
- ❌ 忽略表单验证的catch块
|
||||
|
||||
### 实现检查清单
|
||||
开发表单页面时，必须确保：
|
||||
- [ ] 已导入 `coiMsgWarning` 函数
|
||||
- [ ] 表单验证和API调用分离处理
|
||||
- [ ] 验证失败时显示 `coiMsgWarning` 提示
|
||||
- [ ] API调用成功时显示 `coiMsgSuccess` 提示
|
||||
- [ ] API调用失败时显示 `coiMsgError` 提示
|
||||
- [ ] 错误信息根据操作类型（新增/修改）进行区分
|
||||
|
||||
**遵循此规范确保所有表单页面具有一致的用户体验和错误处理机制！**
|
||||
|
||||
## 文档资源
|
||||
|
||||
项目包含完整的文档系统：
|
||||
|
||||
Loading…
Reference in New Issue
Block a user