3009 lines
83 KiB
Markdown
3009 lines
83 KiB
Markdown
# 前端技术设计规范
|
||
|
||
## 目录
|
||
1. [项目概述](#项目概述)
|
||
2. [技术栈](#技术栈)
|
||
3. [项目架构](#项目架构)
|
||
4. [页面结构规范](#页面结构规范)
|
||
5. [组件使用规范](#组件使用规范)
|
||
6. [业务组件规范](#业务组件规范)
|
||
7. [图标使用规范](#图标使用规范)
|
||
8. [样式规范](#样式规范)
|
||
9. [文件预览规范](#文件预览规范)
|
||
10. [路由规范](#路由规范)
|
||
11. [状态管理规范](#状态管理规范)
|
||
12. [接口处理规范](#接口处理规范)
|
||
13. [最佳实践](#最佳实践)
|
||
|
||
## 项目概述
|
||
|
||
本项目是一个RMO管理网站（vdano.com/GCP-RMO），采用 Vue 3 + Vite + Element Plus 技术栈构建，提供完整的权限管理、知识库管理、CRM管理、OA审批等功能模块。
|
||
|
||
### 设计原则
|
||
- **统一性**：所有页面采用相同的布局结构和交互模式
|
||
- **简洁性**：基于Element Plus组件库，避免重度定制样式
|
||
- **可维护性**：使用composable模式和组件分离提高代码质量
|
||
- **可扩展性**：模块化设计，支持功能快速迭代
|
||
|
||
## 技术栈
|
||
|
||
### 核心框架
|
||
- **Vue 3.3.4** - 渐进式JavaScript框架
|
||
- **Vite 4.4.9** - 下一代前端构建工具
|
||
- **Vue Router 4.2.4** - 官方路由管理器
|
||
- **Pinia 2.1.6** - Vue状态管理库
|
||
|
||
### UI组件库
|
||
- **Element Plus 2.10.4** - 基于Vue 3的组件库
|
||
- **@element-plus/icons-vue 2.1.0** - Element Plus图标库
|
||
|
||
### 表格组件
|
||
- **vxe-table 4.14.1** - 高性能表格组件
|
||
- **xe-utils 3.7.6** - 表格工具库
|
||
|
||
### 编辑器组件
|
||
- **@umoteam/editor 7.0.1** - 富文本编辑器
|
||
- **@vueup/vue-quill 1.2.0** - Quill编辑器Vue组件
|
||
- **@vue-office/** - Office文档预览组件
|
||
|
||
### 工具库
|
||
- **@vueuse/core 13.1.0** - Vue组合式API工具集
|
||
- **axios 1.5.0** - HTTP客户端
|
||
- **crypto-js 4.2.0** - 加密库
|
||
- **echarts 5.6.0** - 数据可视化图表库
|
||
|
||
|
||
### 架构特点
|
||
- **分层架构**: API层、组件层、页面层清晰分离
|
||
- **模块化设计**: 按业务功能模块组织代码
|
||
- **组件化开发**: 可复用的公共组件和业务组件
|
||
- **状态管理**: 使用Pinia进行全局状态管理
|
||
- **Composable模式**: 使用composable函数实现逻辑复用
|
||
- **动态组件**: 支持按需加载和动态组件管理
|
||
|
||
## 页面结构规范
|
||
|
||
### 1. 页面容器规范
|
||
|
||
#### 必须使用 PageContainer 包裹
|
||
所有页面必须使用 `PageContainer` 组件作为根容器：
|
||
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<!-- 页面内容 -->
|
||
</PageContainer>
|
||
</template>
|
||
|
||
<script setup>
|
||
import PageContainer from '@/components/PageContainer.vue'
|
||
|
||
const handlePageRefresh = () => {
|
||
// 刷新页面数据逻辑
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 2. 标准页面结构
|
||
|
||
#### 页面布局容器规范
|
||
|
||
**必须使用 `page-body` 包裹除 header 外的所有内容**
|
||
|
||
所有使用 `page-header` 的页面，必须使用 `page-body` 容器包裹除 header 外的所有内容区域：
|
||
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<!-- 页面头部 -->
|
||
<div class="page-header">
|
||
<div class="header-content">
|
||
<div class="header-left">
|
||
<h2 class="page-title">
|
||
<el-icon class="title-icon"><Document /></el-icon>
|
||
页面标题
|
||
</h2>
|
||
<p class="page-description">页面描述信息</p>
|
||
</div>
|
||
<div class="header-actions">
|
||
<el-button type="primary" @click="handleAdd" class="add-btn">
|
||
<el-icon><Plus /></el-icon>
|
||
新增
|
||
</el-button>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 页面内容区域（必须使用 page-body） -->
|
||
<div class="page-body">
|
||
<!-- 所有页面内容都在这里 -->
|
||
<!-- 可以是 el-card、el-tabs、表格等 -->
|
||
</div>
|
||
</PageContainer>
|
||
</template>
|
||
```
|
||
|
||
**`page-body` 的作用**：
|
||
- **高度管理**：自动计算并占据除 `page-header` 外的剩余空间
|
||
- **布局容器**：提供统一的 flex 布局容器，支持内部内容的灵活布局
|
||
- **响应式支持**：自动适配移动端和桌面端的高度计算
|
||
|
||
**高度计算逻辑**：
|
||
- 桌面端：`calc(100vh - 导航栏 - 标签栏 - PageContainer的padding - page-header高度 - page-header的margin-bottom)`
|
||
- 移动端：使用移动端的导航栏和标签栏高度变量进行计算
|
||
- 所有高度值都通过 CSS 变量定义在 `src/assets/styles/index.scss` 中
|
||
|
||
**CSS 变量定义**（在 `index.scss` 中）：
|
||
```scss
|
||
--page-header-height: 50px; // page-header的高度
|
||
--page-header-margin-bottom: 16px; // page-header的margin-bottom
|
||
--page-content-height: calc(100vh - var(--navbar-height) - var(--tabs-height) - var(--page-container-padding));
|
||
--page-body-height: calc(var(--page-content-height) - var(--page-header-height) - var(--page-header-margin-bottom));
|
||
```
|
||
|
||
#### 普通列表页面结构
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<!-- 页面头部 -->
|
||
<div class="page-header">
|
||
<div class="header-content">
|
||
<div class="header-left">
|
||
<h2 class="page-title">
|
||
<el-icon class="title-icon"><Document /></el-icon>
|
||
页面标题
|
||
</h2>
|
||
<p class="page-description">页面描述信息</p>
|
||
</div>
|
||
<div class="header-actions">
|
||
<el-button type="primary" @click="handleAdd" class="add-btn">
|
||
<el-icon><Plus /></el-icon>
|
||
新增
|
||
</el-button>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 页面内容区域 -->
|
||
<div class="page-body">
|
||
<!-- 主要内容区域 -->
|
||
<el-card class="main-card" shadow="never">
|
||
<!-- 搜索表单 -->
|
||
<div class="search-section">
|
||
<!-- 搜索条件 -->
|
||
</div>
|
||
|
||
<!-- 数据表格 -->
|
||
<div class="table-section">
|
||
<!-- vxe-table 组件 -->
|
||
</div>
|
||
</el-card>
|
||
</div>
|
||
</PageContainer>
|
||
</template>
|
||
```
|
||
|
||
#### 标签页布局结构（分页固定在底部）
|
||
|
||
**使用场景**：当页面使用 `el-tabs` 标签页，且需要将分页固定在底部、内容区域可滚动时：
|
||
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<!-- 页面头部 -->
|
||
<div class="page-header">
|
||
<div class="header-content">
|
||
<div class="header-left">
|
||
<h2 class="page-title">
|
||
<el-icon class="title-icon"><Document /></el-icon>
|
||
页面标题
|
||
</h2>
|
||
<p class="page-description">页面描述信息</p>
|
||
</div>
|
||
<div class="header-actions">
|
||
<el-button type="primary" @click="handleAdd" class="add-btn">
|
||
<el-icon><Plus /></el-icon>
|
||
新增
|
||
</el-button>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 页面内容区域 -->
|
||
<div class="page-body">
|
||
<!-- 标签页 -->
|
||
<el-tabs v-model="activeTab" type="border-card" @tab-change="handleTabChange">
|
||
<el-tab-pane label="标签1" name="tab1">
|
||
<!-- 搜索区域（固定在顶部） -->
|
||
<div class="search-section">
|
||
<!-- 搜索条件 -->
|
||
</div>
|
||
|
||
<!-- 内容区域（可滚动） -->
|
||
<div class="file-cards-container">
|
||
<!-- 卡片列表或其他内容 -->
|
||
</div>
|
||
|
||
<!-- 分页（固定在底部） -->
|
||
<div class="pagination-section">
|
||
<el-pagination
|
||
v-model:current-page="currentPage"
|
||
:page-size="pageSize"
|
||
:total="total"
|
||
layout="prev, pager, next"
|
||
@current-change="handlePageChange"
|
||
/>
|
||
</div>
|
||
</el-tab-pane>
|
||
|
||
<el-tab-pane label="标签2" name="tab2">
|
||
<!-- 其他标签页内容 -->
|
||
</el-tab-pane>
|
||
</el-tabs>
|
||
</div>
|
||
</PageContainer>
|
||
</template>
|
||
|
||
<style lang="scss" scoped>
|
||
@import '@/assets/styles/common.scss';
|
||
|
||
// el-tabs 容器样式
|
||
:deep(.el-tabs) {
|
||
display: flex;
|
||
flex-direction: column;
|
||
flex: 1;
|
||
height: 100%;
|
||
overflow: hidden;
|
||
min-height: 0;
|
||
|
||
.el-tabs__content {
|
||
flex: 1;
|
||
overflow: hidden;
|
||
min-height: 0;
|
||
}
|
||
}
|
||
|
||
// 标签页内容区域样式
|
||
:deep(.el-tabs__content) {
|
||
padding: 16px;
|
||
display: flex;
|
||
flex-direction: column;
|
||
height: 100%;
|
||
overflow: hidden;
|
||
|
||
// 每个 tab-pane 的内容区域
|
||
.el-tab-pane {
|
||
display: flex;
|
||
flex-direction: column;
|
||
height: 100%;
|
||
overflow: hidden;
|
||
}
|
||
}
|
||
|
||
// 搜索区域样式
|
||
.search-section {
|
||
flex-shrink: 0; // 固定在顶部，不收缩
|
||
// ... 其他样式
|
||
}
|
||
|
||
// 内容容器样式（可滚动）
|
||
.file-cards-container {
|
||
flex: 1;
|
||
overflow-y: auto;
|
||
overflow-x: hidden;
|
||
min-height: 0; // 允许flex子元素收缩
|
||
// ... 其他样式
|
||
}
|
||
|
||
// 分页样式
|
||
.pagination-section {
|
||
flex-shrink: 0; // 固定在底部，不收缩
|
||
margin-top: auto; // 自动推到底部
|
||
background: white; // 确保背景色，避免滚动时覆盖
|
||
// ... 其他样式
|
||
}
|
||
</style>
|
||
```
|
||
|
||
**布局原理**：
|
||
1. **`page-body`**：提供固定高度的 flex 容器
|
||
2. **`el-tabs`**：设置为 `flex: 1`，占据全部高度
|
||
3. **`el-tab-pane`**：设置为 `display: flex; flex-direction: column`，垂直排列子元素
|
||
4. **搜索区域**：`flex-shrink: 0`，固定在顶部
|
||
5. **内容区域**：`flex: 1` + `overflow-y: auto`，占据剩余空间并可滚动
|
||
6. **分页区域**：`flex-shrink: 0` + `margin-top: auto`，自动推到底部
|
||
|
||
**关键样式说明**：
|
||
- `margin-top: auto`：在 flex 容器中，会将元素推到底部
|
||
- `flex: 1`：占据剩余空间
|
||
- `overflow-y: auto`：内容超出时可滚动
|
||
- `min-height: 0`：允许 flex 子元素收缩，配合 `overflow` 使用
|
||
|
||
#### 一级菜单首页结构（模块Dashboard）
|
||
**重要说明**：一级菜单的首页（如 `/email`、`/crm`、`/knowledge` 等路由的根页面）必须采用特殊的模块首页布局，不能使用普通列表页面结构：
|
||
|
||
**标准首页结构（带动画效果）** - **推荐使用**：
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<div class="module-dashboard-container">
|
||
<!-- 模块首页头部（带背景动画） -->
|
||
<div class="module-home-header">
|
||
<!-- 背景装饰 -->
|
||
<div class="header-decoration">
|
||
<!-- 流星动画效果 -->
|
||
<div class="meteor meteor-1"></div>
|
||
<div class="meteor meteor-2"></div>
|
||
<div class="meteor meteor-3"></div>
|
||
|
||
<!-- 装饰形状 -->
|
||
<div class="decoration-shape shape-1"></div>
|
||
<div class="decoration-shape shape-2"></div>
|
||
<div class="decoration-shape shape-3"></div>
|
||
</div>
|
||
|
||
<div class="header-main">
|
||
<div class="header-content">
|
||
<!-- 左侧：模块图标 -->
|
||
<div class="module-image">
|
||
<img src="@/assets/images/模块名/banner.png" alt="模块名称" />
|
||
</div>
|
||
|
||
<!-- 右侧：文字内容 -->
|
||
<div class="header-text">
|
||
<h1>模块名称</h1>
|
||
<p>模块功能的详细描述，说明模块的价值和特色功能，让用户了解模块的核心价值和使用场景。</p>
|
||
|
||
<div class="status-indicator">
|
||
<div class="status-dot"></div>
|
||
<span>系统正在为您服务</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 模块内容区域 -->
|
||
<div class="module-content">
|
||
<!-- 统计卡片区域 -->
|
||
<div class="stats-section">
|
||
<!-- 数据统计卡片 -->
|
||
</div>
|
||
|
||
<!-- 功能入口区域 -->
|
||
<div class="feature-section">
|
||
<!-- 功能模块卡片 -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</PageContainer>
|
||
</template>
|
||
|
||
<style lang="scss" scoped>
|
||
@import '@/assets/styles/common.scss';
|
||
|
||
/* 模块特定样式 */
|
||
.module-content {
|
||
// 在这里添加模块特定的内容样式
|
||
}
|
||
</style>
|
||
```
|
||
|
||
**简化首页结构（无动画效果）**：
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<!-- 模块首页头部（简化版） -->
|
||
<div class="page-header">
|
||
<div class="header-content">
|
||
<div class="header-left">
|
||
<h2 class="page-title">
|
||
<el-icon class="title-icon"><Management /></el-icon>
|
||
模块名称
|
||
</h2>
|
||
<p class="page-description">模块功能描述</p>
|
||
</div>
|
||
<div class="header-actions">
|
||
<!-- 模块级操作按钮 -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 模块内容区域 -->
|
||
<div class="module-content">
|
||
<!-- 统计卡片区域 -->
|
||
<div class="stats-section">
|
||
<!-- 数据统计卡片 -->
|
||
</div>
|
||
|
||
<!-- 功能入口区域 -->
|
||
<div class="feature-section">
|
||
<!-- 功能模块卡片 -->
|
||
</div>
|
||
</div>
|
||
</PageContainer>
|
||
</template>
|
||
```
|
||
|
||
**关键区别**：
|
||
- **模块首页**：使用 `<div class="module-content">` 直接包裹内容区域
|
||
- **普通列表页**：使用 `<el-card class="main-card" shadow="never">` 包裹内容区域
|
||
|
||
**样式选择**：
|
||
- **`module-home-header`**：华丽的动画效果，适合重要的模块首页（推荐）
|
||
- **`page-header`**：简洁的渐变样式，适合功能型页面或简化的首页
|
||
|
||
**类名对照表**：
|
||
| 用途 | 类名 | 说明 |
|
||
|------|------|------|
|
||
| 模块首页容器 | `module-dashboard-container` | 统一的模块首页容器 |
|
||
| 动画头部 | `module-home-header` | 带背景动画的头部样式 |
|
||
| 简化头部 | `page-header` | 简洁的渐变头部样式 |
|
||
| 模块图片 | `module-image` | 模块banner图片容器 |
|
||
| 文字内容 | `header-text` | 头部文字内容区域 |
|
||
| 状态指示器 | `status-indicator` | 系统状态显示 |
|
||
|
||
**应用场景**：
|
||
- **模块首页**：如 `/email`、`/crm`、`/knowledge` 等一级菜单的入口页面
|
||
- **普通列表页**：如 `/email/management`、`/crm/customer`、`/knowledge/repository` 等功能页面
|
||
|
||
**识别规则**：
|
||
1. **路由层级**：一级菜单的根路由页面（如 `/email/index/Dashboard.vue`）
|
||
2. **页面性质**：展示模块概览、统计数据、功能入口的首页
|
||
3. **文件位置**：通常位于 `views/模块名/index/Dashboard.vue` 或 `views/模块名/Dashboard.vue`
|
||
4. **菜单结构**：在左侧菜单中作为一级菜单的主页面
|
||
|
||
**样式文件优化**：
|
||
- ✅ **统一封装**：所有首页样式都在 `src/assets/styles/common.scss` 中定义
|
||
- ✅ **完整动画**：包含流星漂移、浮动形状、呼吸状态指示器等动画效果
|
||
- ✅ **响应式设计**：自动适配移动端和桌面端
|
||
- ✅ **模块特定样式**：各模块只需要在自己的文件中添加特定样式
|
||
- ✅ **性能优化**：避免重复代码，减少CSS体积
|
||
|
||
**使用指南**：
|
||
1. **导入样式**：在Vue文件中使用 `@import '@/assets/styles/common.scss'`
|
||
2. **统一结构**：使用标准的模板结构和类名
|
||
3. **内容区域**：使用 `.module-content` 包裹所有模块内容
|
||
4. **首页布局**：在 `.module-content` 内使用 `.dashboard-layout` 进行布局
|
||
5. **模块特定样式**：在模块的style中添加特定的内容样式
|
||
6. **图片资源**：将模块banner图片放在 `src/assets/images/模块名/banner.png`
|
||
|
||
**正确的首页布局结构**：
|
||
```vue
|
||
<template>
|
||
<PageContainer @refresh="handlePageRefresh">
|
||
<div class="module-dashboard-container">
|
||
<!-- 模块首页头部（带动画效果） -->
|
||
<div class="module-home-header">
|
||
<!-- ... 头部内容 ... -->
|
||
</div>
|
||
|
||
<!-- 模块内容区域 -->
|
||
<div class="module-content">
|
||
<!-- 首页专用布局容器 -->
|
||
<div class="dashboard-layout">
|
||
<!-- 第一行：智能分析摘要 + 快捷操作 -->
|
||
<div class="dashboard-row-1">
|
||
<div class="summary-section"><!-- 智能分析摘要 --></div>
|
||
<div class="feature-section"><!-- 快捷操作 --></div>
|
||
</div>
|
||
|
||
<!-- 第二行：未读内容 + 活动记录 -->
|
||
<div class="dashboard-row-2">
|
||
<div class="unread-section"><!-- 未读内容 --></div>
|
||
<div class="activity-section"><!-- 活动记录 --></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</PageContainer>
|
||
</template>
|
||
```
|
||
|
||
**层级说明**：
|
||
- `module-dashboard-container`：模块首页的根容器
|
||
- `module-home-header`：带动画效果的模块头部
|
||
- `module-content`：模块内容区域（所有模块页面的标准容器）
|
||
- `dashboard-layout`：首页专用的布局容器（只在Dashboard页面使用）
|
||
- `dashboard-row-1/2`：首页布局的行容器
|
||
|
||
**动画效果**：
|
||
- `meteor-drift`：流星漂移动画，3个不同延迟的流星在XY平面内移动
|
||
- `float`：装饰形状的旋转和缩放动画（**已优化：移除上下浮动**）
|
||
- `pulse`：状态指示器的呼吸灯效果
|
||
- **交互动画**：使用阴影、亮度、边框等效果替代Y轴位移
|
||
- 所有动画都经过性能优化，使用硬件加速
|
||
|
||
**设计原则**：
|
||
- ❌ **禁止使用** `translateY` 进行上下浮动动画
|
||
- ✅ **推荐使用** 阴影变化、颜色过渡、缩放、旋转等效果
|
||
- ✅ **保持稳定** 所有元素位置固定，避免页面跳动
|
||
- ✅ **流畅体验** 使用平滑的视觉反馈替代位移动画
|
||
|
||
### 动画设计规范
|
||
|
||
**推荐的悬停效果**：
|
||
```scss
|
||
// ✅ 推荐：使用阴影和亮度变化
|
||
&:hover {
|
||
box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
|
||
filter: brightness(1.05);
|
||
border-color: #primary-color;
|
||
}
|
||
|
||
// ✅ 推荐：使用缩放和旋转
|
||
&:hover {
|
||
transform: scale(1.05) rotate(2deg);
|
||
box-shadow: 0 4px 15px rgba(0, 0, 0, 0.1);
|
||
}
|
||
|
||
// ❌ 禁止：使用Y轴位移
|
||
&:hover {
|
||
transform: translateY(-5px); // 不要使用这种效果
|
||
}
|
||
```
|
||
|
||
**装饰性动画原则**：
|
||
- 旋转动画：`transform: rotate(0deg to 360deg)`
|
||
- 缩放动画：`transform: scale(0.9 to 1.1)`
|
||
- 透明度变化：`opacity: 0.3 to 0.8`
|
||
- 颜色渐变：`background`, `border-color`, `color` 过渡
|
||
- 禁止位移：避免 `translateX`, `translateY` 造成的位置跳动
|
||
|
||
### 快捷操作组件封装
|
||
|
||
**快捷操作区域**已在 `common.scss` 中统一封装，支持自适应布局和多种样式：
|
||
|
||
```vue
|
||
<template>
|
||
<div class="quick-actions-section">
|
||
<!-- 头部标题区域 -->
|
||
<div class="quick-actions-header">
|
||
<h3 class="actions-title">
|
||
<el-icon class="title-icon"><Lightning /></el-icon>
|
||
快捷操作
|
||
</h3>
|
||
<span class="actions-extra">6 项服务</span>
|
||
</div>
|
||
|
||
<!-- 自适应网格 -->
|
||
<div class="quick-actions-grid">
|
||
<!-- 按顺序使用预设颜色 -->
|
||
<div class="quick-action-item color-0" @click="handleAction1">
|
||
<div class="action-icon">
|
||
<el-icon><Edit /></el-icon>
|
||
</div>
|
||
<div class="action-text">写邮件</div>
|
||
</div>
|
||
|
||
<div class="quick-action-item color-1" @click="handleAction2">
|
||
<div class="action-icon">
|
||
<el-icon><Folder /></el-icon>
|
||
</div>
|
||
<div class="action-text">文件管理</div>
|
||
</div>
|
||
|
||
<div class="quick-action-item color-2" @click="handleAction3">
|
||
<div class="action-icon">
|
||
<el-icon><Setting /></el-icon>
|
||
</div>
|
||
<div class="action-text">设置</div>
|
||
</div>
|
||
|
||
<div class="quick-action-item color-3" @click="handleAction4">
|
||
<div class="action-icon">
|
||
<el-icon><DataAnalysis /></el-icon>
|
||
</div>
|
||
<div class="action-text">数据分析</div>
|
||
</div>
|
||
|
||
<div class="quick-action-item color-4" @click="handleAction5">
|
||
<div class="action-icon">
|
||
<el-icon><User /></el-icon>
|
||
</div>
|
||
<div class="action-text">用户管理</div>
|
||
</div>
|
||
|
||
<div class="quick-action-item color-5" @click="handleAction6">
|
||
<div class="action-icon">
|
||
<el-icon><Bell /></el-icon>
|
||
</div>
|
||
<div class="action-text">消息通知</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
**自适应特性**：
|
||
- **最小宽度控制**：每个操作项最小宽度 `120px`
|
||
- **自动换行**：使用 `grid-template-columns: repeat(auto-fit, minmax(120px, 1fr))`
|
||
- **响应式布局**：
|
||
- 桌面端：最多8列
|
||
- 平板端：自动适应
|
||
- 手机端：最少2列，最小宽度100px
|
||
|
||
**预设颜色系统**：
|
||
| 类名 | 颜色 | 图标渐变 | 悬停背景 |
|
||
|------|------|----------|----------|
|
||
| `color-0` | 蓝色 | `#6366f1 → #4f46e5` | 紫蓝色浅色 |
|
||
| `color-1` | 绿色 | `#10b981 → #059669` | 绿色浅色 |
|
||
| `color-2` | 橙色 | `#f59e0b → #d97706` | 橙色浅色 |
|
||
| `color-3` | 红色 | `#ef4444 → #dc2626` | 红色浅色 |
|
||
| `color-4` | 紫色 | `#8b5cf6 → #7c3aed` | 紫色浅色 |
|
||
| `color-5` | 青色 | `#06b6d4 → #0891b2` | 青色浅色 |
|
||
| `color-6` | 粉色 | `#ec4899 → #db2777` | 粉色浅色 |
|
||
| `color-7` | 草绿色 | `#84cc16 → #65a30d` | 草绿色浅色 |
|
||
| `color-8` | 灰色 | `#6b7280 → #4b5563` | 灰色浅色 |
|
||
| `color-9` | 深橙色 | `#f97316 → #ea580c` | 深橙色浅色 |
|
||
|
||
**使用规则**：
|
||
- **顺序分配**：按照操作项的顺序依次使用 `color-0` 到 `color-9`
|
||
- **循环使用**：超过10个操作时，重新从 `color-0` 开始循环
|
||
- **主要操作**：仍可使用 `primary-action` 类来突出显示最重要的操作
|
||
- **视觉一致**：所有颜色都经过精心调配，确保视觉和谐
|
||
|
||
**布局规则**：
|
||
1. **网格优先**：优先显示更多列，到达最小宽度后自动换行
|
||
2. **均匀分布**：使用 `1fr` 确保每项宽度相等
|
||
3. **最小保证**：极小屏幕下确保至少显示2列
|
||
4. **最大限制**：大屏幕下限制最大8列，避免过度拉伸
|
||
|
||
## 组件使用规范
|
||
|
||
### 1. 表格组件使用规范
|
||
|
||
#### 使用场景
|
||
- **数据列表展示**: 用户列表、文件列表、订单列表等
|
||
- **数据筛选排序**: 需要分页、搜索、排序的数据表格
|
||
- **复杂数据操作**: 批量操作、行内编辑、树形数据等
|
||
|
||
#### 技术选型
|
||
**必须使用 vxe-table 作为表格组件**
|
||
|
||
```vue
|
||
<vxe-table
|
||
:data="tableData"
|
||
:loading="loading"
|
||
:pager-config="pagerConfig"
|
||
@page-change="handlePageChange"
|
||
>
|
||
<vxe-column field="name" title="名称" />
|
||
<vxe-column field="status" title="状态" />
|
||
<vxe-column title="操作" width="200">
|
||
<template #default="{ row }">
|
||
<el-button size="small" @click="handleEdit(row)">
|
||
<el-icon><Edit /></el-icon>编辑
|
||
</el-button>
|
||
</template>
|
||
</vxe-column>
|
||
</vxe-table>
|
||
```
|
||
|
||
#### 表格配置规范
|
||
```javascript
|
||
// 标准分页配置
|
||
const pagerConfig = {
|
||
currentPage: 1,
|
||
pageSize: 20,
|
||
total: 0,
|
||
layouts: ['PrevPage', 'JumpNumber', 'NextPage', 'FullJump', 'Sizes', 'Total']
|
||
}
|
||
```
|
||
|
||
### 2. 按钮组件使用规范
|
||
|
||
#### 按钮类型和使用场景
|
||
```vue
|
||
<!-- 主要操作按钮 -->
|
||
<el-button type="primary" @click="handleSubmit">
|
||
<el-icon><Check /></el-icon>
|
||
确认
|
||
</el-button>
|
||
|
||
<!-- 次要操作按钮 -->
|
||
<el-button @click="handleCancel">
|
||
<el-icon><Close /></el-icon>
|
||
取消
|
||
</el-button>
|
||
|
||
<!-- 危险操作按钮 -->
|
||
<el-button type="danger" @click="handleDelete">
|
||
<el-icon><Delete /></el-icon>
|
||
删除
|
||
</el-button>
|
||
|
||
<!-- 图标按钮 -->
|
||
<el-button circle size="small" @click="handleRefresh">
|
||
<el-icon><Refresh /></el-icon>
|
||
</el-button>
|
||
|
||
<!-- 页面头部特殊按钮（使用add-btn类） -->
|
||
<el-button type="primary" @click="handleAdd" class="add-btn">
|
||
<el-icon><Plus /></el-icon>
|
||
新增
|
||
</el-button>
|
||
```
|
||
|
||
### 3. 表单组件使用规范
|
||
|
||
```vue
|
||
<el-form
|
||
ref="formRef"
|
||
:model="formData"
|
||
:rules="formRules"
|
||
label-width="120px"
|
||
>
|
||
<el-form-item label="名称" prop="name">
|
||
<el-input v-model="formData.name" placeholder="请输入名称" />
|
||
</el-form-item>
|
||
|
||
<el-form-item label="状态" prop="status">
|
||
<el-select v-model="formData.status" placeholder="请选择状态">
|
||
<el-option label="启用" value="enabled" />
|
||
<el-option label="禁用" value="disabled" />
|
||
</el-select>
|
||
</el-form-item>
|
||
</el-form>
|
||
```
|
||
|
||
#### 下拉框组件使用规范
|
||
|
||
**必须支持搜索功能**
|
||
|
||
所有下拉框（`el-select`）组件必须添加 `filterable` 属性，支持用户搜索过滤选项，提升用户体验：
|
||
|
||
```vue
|
||
<!-- ✅ 正确：支持搜索的下拉框 -->
|
||
<el-form-item label="严重程度" prop="severity">
|
||
<el-select
|
||
v-model="formData.severity"
|
||
placeholder="请选择或输入严重程度"
|
||
style="width: 100%"
|
||
filterable
|
||
>
|
||
<el-option label="非严重" value="非严重" />
|
||
<el-option label="严重" value="严重" />
|
||
<el-option label="危机生命、致死" value="危机生命、致死" />
|
||
</el-select>
|
||
</el-form-item>
|
||
|
||
<!-- ❌ 错误：不支持搜索的下拉框 -->
|
||
<el-form-item label="状态" prop="status">
|
||
<el-select v-model="formData.status" placeholder="请选择状态">
|
||
<el-option label="启用" value="enabled" />
|
||
<el-option label="禁用" value="disabled" />
|
||
</el-select>
|
||
</el-form-item>
|
||
```
|
||
|
||
**可输入可选择的场景**
|
||
|
||
对于需要支持用户手动输入新值的场景（如下拉框没有对应选项时），应添加 `allow-create` 和 `default-first-option` 属性：
|
||
|
||
```vue
|
||
<!-- ✅ 支持搜索和手动输入的下拉框 -->
|
||
<el-form-item label="严重程度" prop="severity">
|
||
<el-select
|
||
v-model="formData.severity"
|
||
placeholder="请选择或输入严重程度"
|
||
style="width: 100%"
|
||
filterable
|
||
allow-create
|
||
default-first-option
|
||
>
|
||
<el-option label="非严重" value="非严重" />
|
||
<el-option label="严重" value="严重" />
|
||
<el-option label="危机生命、致死" value="危机生命、致死" />
|
||
</el-select>
|
||
</el-form-item>
|
||
```
|
||
|
||
**属性说明**
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `filterable` | Boolean | ✅ 是 | 是否可搜索，所有下拉框必须添加此属性 |
|
||
| `allow-create` | Boolean | ⚠️ 可选 | 是否允许用户创建新条目，适用于需要手动输入的场景 |
|
||
| `default-first-option` | Boolean | ⚠️ 可选 | 在输入框按下回车，选择第一个匹配项，配合 `allow-create` 使用 |
|
||
|
||
**使用场景**
|
||
|
||
1. **标准下拉框**（选项固定，只需搜索）：
|
||
```vue
|
||
<el-select v-model="value" filterable>
|
||
<el-option label="选项1" value="1" />
|
||
<el-option label="选项2" value="2" />
|
||
</el-select>
|
||
```
|
||
|
||
2. **可输入下拉框**（选项不固定，需要手动输入）：
|
||
```vue
|
||
<el-select
|
||
v-model="value"
|
||
filterable
|
||
allow-create
|
||
default-first-option
|
||
>
|
||
<el-option label="选项1" value="1" />
|
||
<el-option label="选项2" value="2" />
|
||
</el-select>
|
||
```
|
||
|
||
3. **多选下拉框**（支持搜索和创建）：
|
||
```vue
|
||
<el-select
|
||
v-model="value"
|
||
multiple
|
||
filterable
|
||
allow-create
|
||
default-first-option
|
||
>
|
||
<el-option label="选项1" value="1" />
|
||
<el-option label="选项2" value="2" />
|
||
</el-select>
|
||
```
|
||
|
||
**Placeholder 规范**
|
||
|
||
- **仅搜索**：`placeholder="请选择或搜索XXX"`
|
||
- **搜索+输入**：`placeholder="请选择或输入XXX"`
|
||
|
||
**注意事项**
|
||
|
||
1. ✅ **必须添加**：所有下拉框必须添加 `filterable` 属性
|
||
2. ✅ **用户体验**：搜索功能可以快速定位选项，特别是选项较多时
|
||
3. ✅ **一致性**：保持所有下拉框的交互方式一致
|
||
4. ⚠️ **性能考虑**：选项数量超过 100 条时，建议使用远程搜索（`remote` 属性）
|
||
5. ⚠️ **数据验证**：使用 `allow-create` 时，需要在表单验证中处理用户输入的新值
|
||
|
||
### 4. 卡片组件使用规范
|
||
|
||
```vue
|
||
<!-- 主要内容卡片 -->
|
||
<el-card class="main-card" shadow="never">
|
||
<!-- 卡片内容 -->
|
||
</el-card>
|
||
|
||
<!-- 功能模块卡片 -->
|
||
<el-card class="feature-card" shadow="hover">
|
||
<!-- 功能入口内容 -->
|
||
</el-card>
|
||
```
|
||
|
||
### 5. 骨架屏组件使用规范
|
||
|
||
#### 使用场景
|
||
- **数据加载中**: 列表、表格、卡片等数据加载时显示
|
||
- **内容占位**: 避免页面空白，提升用户体验
|
||
- **异步操作**: API调用、文件上传等异步操作期间
|
||
|
||
#### 标准用法
|
||
```vue
|
||
<template>
|
||
<div class="content-container">
|
||
<!-- 骨架屏加载状态 -->
|
||
<div v-if="loading" class="skeleton-container">
|
||
<el-skeleton :rows="5" animated />
|
||
</div>
|
||
|
||
<!-- 空状态 -->
|
||
<el-empty v-else-if="dataList.length === 0" description="暂无数据" />
|
||
|
||
<!-- 实际内容 -->
|
||
<div v-else class="content-list">
|
||
<!-- 列表内容 -->
|
||
</div>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
#### 骨架屏配置
|
||
```vue
|
||
<!-- 基础骨架屏 -->
|
||
<el-skeleton :rows="3" />
|
||
|
||
<!-- 带动画效果 -->
|
||
<el-skeleton :rows="5" animated />
|
||
|
||
<!-- 自定义行数 -->
|
||
<el-skeleton :rows="8" animated />
|
||
|
||
<!-- 自定义样式 -->
|
||
<el-skeleton :rows="4" animated class="custom-skeleton" />
|
||
```
|
||
|
||
#### 样式规范
|
||
```scss
|
||
// 骨架屏容器样式
|
||
.skeleton-container {
|
||
padding: 16px; // 与内容区域保持一致的padding
|
||
|
||
// 自定义骨架屏样式
|
||
:deep(.el-skeleton__item) {
|
||
background: linear-gradient(90deg, #f2f2f2 25%, #e6e6e6 50%, #f2f2f2 75%);
|
||
background-size: 400% 100%;
|
||
animation: loading 1.4s ease infinite;
|
||
}
|
||
}
|
||
|
||
@keyframes loading {
|
||
0% {
|
||
background-position: 100% 50%;
|
||
}
|
||
100% {
|
||
background-position: 0% 50%;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 使用原则
|
||
1. **一致性**: 骨架屏行数应与实际内容行数相近
|
||
2. **动画效果**: 使用 `animated` 属性提供更好的视觉反馈
|
||
3. **适当间距**: 骨架屏容器padding应与实际内容保持一致
|
||
4. **状态管理**: 配合loading状态正确显示和隐藏
|
||
5. **性能考虑**: 避免在骨架屏上添加过多复杂样式
|
||
|
||
### 6. 通知详情组件使用规范
|
||
|
||
#### 使用场景
|
||
- **通知详情**: 显示通知的完整内容、标题和时间
|
||
- **弹框展示**: 在弹框中展示通知详情
|
||
- **工作首页**: 工作台首页的通知详情展示
|
||
- **消息中心**: 消息提醒页面的详情展示
|
||
|
||
#### 标准用法
|
||
```vue
|
||
<template>
|
||
<div class="notification-detail">
|
||
<div class="detail-header">
|
||
<h3 class="detail-title">{{ notification.title }}</h3>
|
||
<div class="detail-time">{{ notification.displayTime }}</div>
|
||
</div>
|
||
<div class="detail-content">
|
||
<div class="content-text" v-html="notification.content"></div>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
defineProps({
|
||
notification: {
|
||
type: Object,
|
||
required: true,
|
||
default: () => ({})
|
||
}
|
||
})
|
||
</script>
|
||
```
|
||
|
||
#### 在弹框中使用
|
||
```vue
|
||
<template>
|
||
<div>
|
||
<!-- 触发弹框的按钮或元素 -->
|
||
<el-button @click="showDetail">查看详情</el-button>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { h } from 'vue'
|
||
import { ElMessageBox } from 'element-plus'
|
||
import NotificationDetail from '@/components/NotificationDetail.vue'
|
||
|
||
const showDetail = (notification) => {
|
||
ElMessageBox({
|
||
title: '通知详情',
|
||
message: h(NotificationDetail, { notification }),
|
||
showCancelButton: false,
|
||
confirmButtonText: '确定',
|
||
customClass: 'notification-detail-dialog'
|
||
})
|
||
}
|
||
</script>
|
||
```
|
||
|
||
#### 组件属性
|
||
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| notification | Object | 是 | {} | 通知对象，包含title、content、displayTime等属性 |
|
||
|
||
#### 样式特性
|
||
- **响应式设计**: 支持移动端和桌面端适配
|
||
- **内容滚动**: 长内容自动滚动显示
|
||
- **HTML支持**: 支持富文本内容显示
|
||
- **统一样式**: 使用项目统一的设计令牌
|
||
|
||
#### 使用原则
|
||
1. **组件复用**: 在多个页面中复用该组件
|
||
2. **数据完整**: 确保传入的notification对象包含必要属性
|
||
3. **样式统一**: 使用组件内置样式，避免外部覆盖
|
||
4. **内容安全**: 使用v-html时注意内容安全性
|
||
|
||
### 7. 分页组件使用规范
|
||
|
||
#### 使用场景
|
||
- **数据列表**: 表格、列表等大量数据的分页展示
|
||
- **内容浏览**: 文章、图片等内容的分页浏览
|
||
- **数据筛选**: 配合搜索和筛选功能进行数据分页
|
||
|
||
#### 标准用法
|
||
```vue
|
||
<template>
|
||
<div class="content-container">
|
||
<!-- 数据列表 -->
|
||
<div class="data-list">
|
||
<!-- 列表内容 -->
|
||
</div>
|
||
|
||
<!-- 分页组件 -->
|
||
<div class="pagination-section" v-if="total > 0">
|
||
<el-pagination
|
||
v-model:current-page="currentPage"
|
||
:page-size="pageSize"
|
||
:total="total"
|
||
layout="prev, pager, next"
|
||
@current-change="handlePageChange"
|
||
/>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
|
||
const currentPage = ref(1)
|
||
const pageSize = ref(20)
|
||
const total = ref(0)
|
||
|
||
const handlePageChange = (page) => {
|
||
currentPage.value = page
|
||
// 重新加载数据
|
||
loadData()
|
||
}
|
||
</script>
|
||
```
|
||
|
||
#### 分页配置选项
|
||
```vue
|
||
<!-- 基础分页 -->
|
||
<el-pagination layout="prev, pager, next" :total="50" />
|
||
|
||
<!-- 带页码数量控制 -->
|
||
<el-pagination
|
||
layout="prev, pager, next"
|
||
:total="1000"
|
||
:pager-count="11"
|
||
/>
|
||
|
||
<!-- 完整分页功能 -->
|
||
<el-pagination
|
||
v-model:current-page="currentPage"
|
||
:page-size="pageSize"
|
||
:total="total"
|
||
layout="total, sizes, prev, pager, next, jumper"
|
||
@current-change="handlePageChange"
|
||
@size-change="handleSizeChange"
|
||
/>
|
||
```
|
||
|
||
#### 布局选项
|
||
| 布局值 | 说明 | 使用场景 |
|
||
|--------|------|----------|
|
||
| `prev, pager, next` | 上一页 + 页码 + 下一页 | 简洁列表页面 |
|
||
| `total, prev, pager, next` | 总数 + 上一页 + 页码 + 下一页 | 需要显示总数的页面 |
|
||
| `sizes, prev, pager, next` | 每页条数 + 上一页 + 页码 + 下一页 | 需要调整每页条数的页面 |
|
||
| `total, sizes, prev, pager, next, jumper` | 完整分页功能 | 复杂的数据管理页面 |
|
||
|
||
#### 样式规范
|
||
```scss
|
||
// 分页区域样式
|
||
.pagination-section {
|
||
display: flex;
|
||
justify-content: center;
|
||
margin-top: 16px;
|
||
padding: 12px 0;
|
||
border-top: 1px solid var(--customer-board-color);
|
||
}
|
||
|
||
// 响应式设计
|
||
@media (max-width: 768px) {
|
||
.pagination-section {
|
||
// 移动端可以调整间距
|
||
margin-top: 12px;
|
||
padding: 8px 0;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 使用原则
|
||
1. **简洁优先**: 优先使用 `prev, pager, next` 布局，保持界面简洁
|
||
2. **居中显示**: 分页组件应在页面中居中显示
|
||
3. **状态管理**: 正确绑定 `current-page` 和 `total` 数据
|
||
4. **事件处理**: 实现 `@current-change` 事件处理分页切换
|
||
5. **条件显示**: 只在有数据时显示分页组件 `v-if="total > 0"`
|
||
6. **默认样式**: 使用Element Plus默认样式，避免过度自定义
|
||
|
||
### 5. 统计卡片组件规范
|
||
|
||
#### 统计卡片标准结构
|
||
项目已在 `src/assets/styles/common.scss` 中封装了统一的统计卡片样式，支持多种布局和主题：
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 统计卡片区域 -->
|
||
<div class="stats-section">
|
||
<div class="stats-grid grid-4"> <!-- 4列布局 -->
|
||
<div class="stat-card theme-blue" @click="handleClick">
|
||
<div class="stat-icon">
|
||
<el-icon><Message /></el-icon>
|
||
</div>
|
||
<div class="stat-content">
|
||
<div class="stat-number">
|
||
<CountUp :target="statisticsData.count" />
|
||
</div>
|
||
<div class="stat-label">统计标签</div>
|
||
</div>
|
||
</div>
|
||
<!-- 更多统计卡片... -->
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import CountUp from '@/components/CountUp.vue'
|
||
</script>
|
||
```
|
||
|
||
#### 布局类型
|
||
| 类名 | 布局 | 响应式断点 | 使用场景 |
|
||
|------|------|------------|----------|
|
||
| `grid-4` | 4列布局 | 1200px→2列, 768px→1列 | 完整的统计面板 |
|
||
| `grid-3` | 3列布局 | 900px→2列, 768px→1列 | 知识库风格布局 |
|
||
| `grid-2` | 2列布局 | 768px→1列 | 简化的统计展示 |
|
||
|
||
#### 主题颜色
|
||
| 主题类名 | 颜色系 | 渐变色 | 适用场景 |
|
||
|----------|--------|--------|----------|
|
||
| `theme-blue` | 蓝色 | `#3b82f6 → #1d4ed8` | 主要数据、消息类 |
|
||
| `theme-red` | 红色 | `#ef4444 → #dc2626` | 紧急、警告类 |
|
||
| `theme-orange` | 橙色 | `#f59e0b → #d97706` | 待处理、提醒类 |
|
||
| `theme-green` | 绿色 | `#10b981 → #059669` | 完成、成功类 |
|
||
| `theme-purple` | 紫色 | `#a855f7 → #7c3aed` | 特殊、高级功能 |
|
||
| `theme-cyan` | 青色 | `#06b6d4 → #0891b2` | 活动、记录类 |
|
||
| `theme-pink` | 粉色 | `#ec4899 → #db2777` | 收藏、喜欢类 |
|
||
| `theme-lime` | 草绿 | `#84cc16 → #65a30d` | 新增、增长类 |
|
||
|
||
#### CountUp数字动画组件
|
||
统计卡片配合使用CountUp组件实现数字滚动动画效果：
|
||
|
||
```vue
|
||
<script setup>
|
||
import CountUp from '@/components/CountUp.vue'
|
||
|
||
// CountUp组件参数
|
||
const countUpProps = {
|
||
target: 150, // 目标数字
|
||
duration: 1000, // 动画持续时间(毫秒)
|
||
decimals: 0, // 小数位数
|
||
delay: 0, // 动画延迟(毫秒)
|
||
preset: 'easeOutCubic' // 动画预设
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<div class="stat-number">
|
||
<!-- 基础用法 -->
|
||
<CountUp :target="statistics.count" />
|
||
|
||
<!-- 带小数位 -->
|
||
<CountUp :target="storage.used" :decimals="1" />
|
||
<span class="stat-unit">GB</span>
|
||
|
||
<!-- 自定义动画 -->
|
||
<CountUp
|
||
:target="performance.score"
|
||
:duration="1500"
|
||
:delay="200"
|
||
preset="easeOutBounce"
|
||
/>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
#### 完整示例
|
||
```vue
|
||
<template>
|
||
<!-- 邮件模块统计示例 -->
|
||
<div class="stats-section">
|
||
<div class="stats-grid grid-3">
|
||
<div class="stat-card theme-blue">
|
||
<div class="stat-icon">
|
||
<el-icon><Message /></el-icon>
|
||
</div>
|
||
<div class="stat-content">
|
||
<div class="stat-number">
|
||
<CountUp :target="emailStats.unreadCount" />
|
||
</div>
|
||
<div class="stat-label">未读邮件</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="stat-card theme-green">
|
||
<div class="stat-icon">
|
||
<el-icon><Calendar /></el-icon>
|
||
</div>
|
||
<div class="stat-content">
|
||
<div class="stat-number">
|
||
<CountUp :target="emailStats.todayCount" />
|
||
</div>
|
||
<div class="stat-label">今日最新邮件</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="stat-card theme-orange">
|
||
<div class="stat-icon">
|
||
<el-icon><User /></el-icon>
|
||
</div>
|
||
<div class="stat-content">
|
||
<div class="stat-number">
|
||
<CountUp :target="emailStats.accountCount" />
|
||
</div>
|
||
<div class="stat-label">邮件账户数量</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref, onMounted } from 'vue'
|
||
import { Message, Calendar, User } from '@element-plus/icons-vue'
|
||
import CountUp from '@/components/CountUp.vue'
|
||
|
||
const emailStats = ref({
|
||
unreadCount: 0,
|
||
todayCount: 0,
|
||
accountCount: 0
|
||
})
|
||
|
||
const loadStatistics = async () => {
|
||
// 加载统计数据的逻辑
|
||
}
|
||
|
||
onMounted(() => {
|
||
loadStatistics()
|
||
})
|
||
</script>
|
||
```
|
||
|
||
#### 设计原则
|
||
1. **视觉一致性**：所有统计卡片使用相同的尺寸和样式
|
||
2. **颜色语义化**：根据数据类型选择合适的主题颜色
|
||
3. **纯展示功能**：统计卡片仅用于数据展示，不支持点击交互
|
||
4. **动画增强**：使用CountUp组件提升用户体验
|
||
5. **响应式设计**：自动适配不同屏幕尺寸
|
||
6. **悬浮反馈**：支持轻微的阴影变化，但不包含Y轴移动效果
|
||
|
||
## 业务组件规范
|
||
|
||
### 1. 组件文件组织结构
|
||
|
||
#### 业务模块组件结构
|
||
```
|
||
views/
|
||
├── module-name/ # 业务模块
|
||
│ ├── stores/ # 模块状态管理
|
||
│ │ └── useModuleStore.js
|
||
│ ├── components/ # 模块内组件
|
||
│ │ ├── ComponentA.vue
|
||
│ │ └── ComponentB.vue
|
||
│ ├── composables/ # 业务逻辑函数
|
||
│ │ ├── useModuleData.js
|
||
│ │ └── useModuleOperations.js
|
||
│ ├── utils/ # 模块工具函数
|
||
│ │ └── moduleUtils.js
|
||
│ ├── api/ # 模块API
|
||
│ │ └── moduleApi.js
|
||
│ ├── Dashboard.vue # 模块首页
|
||
│ └── index.vue # 模块入口
|
||
```
|
||
|
||
### 2. Composable 设计模式
|
||
|
||
#### 推荐使用 Composable 分离业务逻辑
|
||
```javascript
|
||
// composables/useTableOperations.js
|
||
export function useTableOperations() {
|
||
const loading = ref(false)
|
||
const tableData = ref([])
|
||
|
||
const loadData = async () => {
|
||
loading.value = true
|
||
try {
|
||
// 数据加载逻辑
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
return {
|
||
loading,
|
||
tableData,
|
||
loadData
|
||
}
|
||
}
|
||
```
|
||
|
||
## 图标使用规范
|
||
|
||
### 必须使用 Element Plus 图标库
|
||
|
||
**基础操作图标**
|
||
```javascript
|
||
import {
|
||
// 基础操作
|
||
Plus, // 新增
|
||
Edit, // 编辑
|
||
Delete, // 删除
|
||
Search, // 搜索
|
||
Refresh, // 刷新
|
||
View, // 查看
|
||
Setting, // 设置
|
||
|
||
// 文件操作
|
||
Download, // 下载
|
||
Upload, // 上传
|
||
Document, // 文档
|
||
Folder, // 文件夹
|
||
FolderOpened, // 打开的文件夹
|
||
|
||
// 导航和布局
|
||
Home, // 首页
|
||
ArrowLeft, // 左箭头
|
||
ArrowRight, // 右箭头
|
||
ArrowUp, // 上箭头
|
||
ArrowDown, // 下箭头
|
||
|
||
// 状态指示
|
||
Check, // 成功/确认
|
||
Close, // 关闭/失败
|
||
Warning, // 警告
|
||
Info, // 信息
|
||
Success, // 成功
|
||
Error, // 错误
|
||
|
||
// 用户和权限
|
||
User, // 用户
|
||
UserFilled, // 用户（填充）
|
||
Lock, // 锁定
|
||
Unlock, // 解锁
|
||
|
||
// 通信和分享
|
||
Message, // 消息
|
||
Phone, // 电话
|
||
Email, // 邮件
|
||
Share, // 分享
|
||
Link, // 链接
|
||
|
||
// 媒体类型
|
||
Picture, // 图片
|
||
Video, // 视频
|
||
Audio, // 音频
|
||
|
||
// 业务功能
|
||
Management, // 管理
|
||
DataBoard, // 数据看板
|
||
Grid, // 网格
|
||
List, // 列表
|
||
Calendar, // 日历
|
||
Clock, // 时钟
|
||
Location, // 位置
|
||
|
||
// 交互反馈
|
||
Star, // 星标
|
||
StarFilled, // 星标（填充）
|
||
Heart, // 喜欢
|
||
HeartFilled, // 喜欢（填充）
|
||
|
||
// 圆形图标变体
|
||
CircleCheck, // 圆形确认
|
||
CircleClose, // 圆形关闭
|
||
CirclePlus, // 圆形加号
|
||
|
||
// 更多操作
|
||
More, // 更多
|
||
MoreFilled, // 更多（填充）
|
||
|
||
// 展开收起
|
||
Expand, // 展开
|
||
Fold, // 收起
|
||
|
||
// 其他常用
|
||
Filter, // 筛选
|
||
Sort, // 排序
|
||
Export, // 导出
|
||
Import, // 导入
|
||
Copy, // 复制
|
||
Files, // 文件集合
|
||
Histogram, // 柱状图
|
||
PieChart, // 饼图
|
||
TrendCharts // 趋势图
|
||
} from '@element-plus/icons-vue'
|
||
```
|
||
|
||
### 图标使用原则
|
||
|
||
1. **统一性**：同一功能在不同页面必须使用相同图标
|
||
2. **语义性**：图标含义要与功能匹配
|
||
3. **一致性**：图标大小和颜色保持项目统一风格
|
||
|
||
### 常用图标映射
|
||
|
||
| 功能 | 图标 | 使用场景 |
|
||
|------|------|----------|
|
||
| 新增 | Plus | 新建数据、添加项目 |
|
||
| 编辑 | Edit | 修改数据、编辑内容 |
|
||
| 删除 | Delete | 删除数据、移除项目 |
|
||
| 搜索 | Search | 搜索框、查询功能 |
|
||
| 刷新 | Refresh | 重新加载数据 |
|
||
| 下载 | Download | 文件下载、数据导出 |
|
||
| 上传 | Upload | 文件上传、导入数据 |
|
||
| 查看 | View | 查看详情、预览 |
|
||
| 设置 | Setting | 配置、参数设置 |
|
||
| 首页 | Home | 返回首页、主页导航 |
|
||
|
||
## 样式规范
|
||
|
||
### 1. 样式架构
|
||
|
||
项目采用分层样式架构：
|
||
- `src/assets/styles/index.scss` - 设计令牌和全局变量
|
||
- `src/assets/styles/common.scss` - 公共页面样式
|
||
|
||
### 2. 间距规范
|
||
|
||
#### 统一Padding标准
|
||
为确保界面的一致性和视觉平衡，项目采用统一的padding规范：
|
||
|
||
**默认padding值：16px**
|
||
|
||
```scss
|
||
// 标准间距规范
|
||
.default-padding {
|
||
padding: 16px; // 默认内边距16px
|
||
}
|
||
|
||
// 卡片组件标准间距
|
||
.dashboard-card {
|
||
:deep(.el-card__body) {
|
||
padding: 16px !important; // 卡片内容区域16px
|
||
}
|
||
|
||
.card-header {
|
||
padding: 16px 16px 12px; // 卡片头部：水平16px，底部12px
|
||
}
|
||
}
|
||
|
||
// 统计卡片间距
|
||
.stat-card {
|
||
padding: 16px; // 统计卡片16px
|
||
}
|
||
```
|
||
|
||
#### 特殊情况说明
|
||
以下情况可根据设计需求调整：
|
||
|
||
| 场景 | Padding值 | 说明 |
|
||
|------|-----------|------|
|
||
| **密集信息展示** | `12px` | 需要显示更多内容时 |
|
||
| **强调内容区域** | `20px` | 需要突出显示的重要内容 |
|
||
| **移动端适配** | `12px` | 小屏幕下的紧凑布局 |
|
||
| **表单输入区域** | `16px` | 保持与默认值一致 |
|
||
| **列表项内容** | `12px - 16px` | 根据列表密度调整 |
|
||
|
||
#### 间距层级系统
|
||
```scss
|
||
// 间距变量定义
|
||
:root {
|
||
--padding-xs: 8px; // 极小间距
|
||
--padding-sm: 12px; // 小间距
|
||
--padding-md: 16px; // 默认间距（推荐）
|
||
--padding-lg: 20px; // 大间距
|
||
--padding-xl: 24px; // 超大间距
|
||
}
|
||
|
||
// 使用示例
|
||
.content-area {
|
||
padding: var(--padding-md); // 使用默认16px
|
||
}
|
||
|
||
.compact-list {
|
||
padding: var(--padding-sm); // 使用紧凑12px
|
||
}
|
||
```
|
||
|
||
### 3. 全局样式规范
|
||
|
||
#### 整体颜色风格规范
|
||
|
||
**品牌主色调**
|
||
|
||
项目采用红色作为品牌主色调，配合白色、黑色和蓝色系形成统一的视觉风格：
|
||
|
||
```scss
|
||
// 品牌主色定义（在 index.scss 中）
|
||
--brand-primary: #D70001; // 主红色 (R215 G0 B1)
|
||
--brand-primary-rgb: 215, 0, 1; // RGB值，用于rgba
|
||
--brand-primary-dark: #B8000D; // 深红色，用于hover等状态
|
||
--brand-primary-light: #FF4D4D; // 浅红色
|
||
--brand-primary-lighter: #FF6B6B; // 更浅的红色
|
||
--brand-text-default: #333333; // 默认文字颜色（黑色）
|
||
--brand-text-active: #ffffff; // 选中状态文字颜色（白色）
|
||
```
|
||
|
||
**布局组件颜色规范**
|
||
|
||
**1. 左侧边栏（LeftSidebar）**
|
||
|
||
- **背景色**：`#D70001`（品牌红色）
|
||
- **默认文字/图标**：`#ffffff`（白色）
|
||
- **选中状态**：
|
||
- 背景：`rgba(255, 255, 255, 0.85)`（白色半透明，85%不透明度）
|
||
- 文字/图标：`#333333`（黑色）
|
||
- 圆角：`8px`
|
||
- **Hover状态**：
|
||
- 背景：`rgba(255, 255, 255, 0.35)`（白色半透明，35%不透明度）
|
||
- 文字/图标：`#ffffff`（白色）
|
||
- 圆角：`8px`
|
||
- **底部信息项**（租户、分辨率、版本）：
|
||
- 背景：`rgba(255, 255, 255, 0.8)`（白色半透明，80%不透明度）
|
||
- 文字/图标：`#333333`（黑色）
|
||
- 圆角：`24px`
|
||
- Hover：`rgba(255, 255, 255, 0.9)`（90%不透明度）
|
||
- **分割线**：`rgba(255, 255, 255, 0.5)`（白色半透明，50%不透明度）
|
||
|
||
```scss
|
||
.sidebar-container {
|
||
background: #D70001;
|
||
|
||
.el-menu-item, .el-sub-menu__title {
|
||
color: #ffffff;
|
||
|
||
&:hover {
|
||
background-color: rgba(255, 255, 255, 0.35);
|
||
color: #ffffff;
|
||
}
|
||
|
||
&.is-active {
|
||
background-color: rgba(255, 255, 255, 0.85);
|
||
color: #333333;
|
||
}
|
||
}
|
||
|
||
.sidebar-footer {
|
||
border-top: 1px solid rgba(255, 255, 255, 0.5);
|
||
background: #D70001;
|
||
|
||
.tenant-item, .footer-item {
|
||
background: rgba(255, 255, 255, 0.8);
|
||
color: #333333;
|
||
border-radius: 24px;
|
||
|
||
&:hover {
|
||
background: rgba(255, 255, 255, 0.9);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**2. 顶部菜单（TopHeader）**
|
||
|
||
- **背景色**：`#D70001`（品牌红色）
|
||
- **默认文字/图标**：`#ffffff`（白色）
|
||
- **一级菜单项**：
|
||
- 默认：透明背景，`#ffffff`文字
|
||
- 选中状态：
|
||
- 背景：`rgba(255, 255, 255, 0.85)`（白色半透明，85%不透明度）
|
||
- 文字/图标：`#333333`（黑色）
|
||
- 圆角：`32px`
|
||
- 字体大小：`16px`，`font-weight: 500`
|
||
- Hover状态：
|
||
- 背景：`rgba(255, 255, 255, 0.35)`（白色半透明，35%不透明度）
|
||
- 文字/图标：`#ffffff`（白色）
|
||
- 圆角：`32px`
|
||
- **工具栏项**（全屏、页面缓存）：
|
||
- 背景：`rgba(255, 255, 255, 0.15)`（白色半透明，15%不透明度）
|
||
- 图标：`#ffffff`（白色）
|
||
- Hover：`rgba(255, 255, 255, 0.25)`（25%不透明度）
|
||
- **公司信息项**：
|
||
- 背景：`rgba(255, 255, 255, 0.8)`（白色半透明，80%不透明度）
|
||
- 文字/图标：`#333333`（黑色）
|
||
- 圆角：`24px`
|
||
- Hover：`rgba(215, 0, 1, 0.1)`（红色半透明）
|
||
- **用户信息项**：
|
||
- 背景：`rgba(255, 255, 255, 0.15)`（白色半透明，15%不透明度）
|
||
- 文字/图标：`#ffffff`（白色）
|
||
- Hover：`rgba(255, 255, 255, 0.25)`（25%不透明度）
|
||
|
||
```scss
|
||
.header-container {
|
||
background: #D70001;
|
||
|
||
.primary-menu .menu-item {
|
||
color: #ffffff;
|
||
|
||
&:hover {
|
||
background: rgba(255, 255, 255, 0.35);
|
||
color: #ffffff;
|
||
border-radius: 32px;
|
||
}
|
||
|
||
&.active {
|
||
background: rgba(255, 255, 255, 0.85);
|
||
color: #333333;
|
||
border-radius: 32px;
|
||
font-weight: 500;
|
||
}
|
||
}
|
||
|
||
.company-item {
|
||
background: rgba(255, 255, 255, 0.8);
|
||
color: #333333;
|
||
border-radius: 24px;
|
||
|
||
&:hover {
|
||
background: rgba(215, 0, 1, 0.1);
|
||
}
|
||
}
|
||
|
||
.tool-item {
|
||
background: rgba(255, 255, 255, 0.15);
|
||
color: #ffffff;
|
||
|
||
&:hover {
|
||
background: rgba(255, 255, 255, 0.25);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**3. 页面头部（Page Header）**
|
||
|
||
- **背景**：红色到黄色的渐变（从左到右）
|
||
```scss
|
||
background: linear-gradient(to right,
|
||
rgba(255, 200, 200, 0.9) 0%, // 起始：浅红色
|
||
rgba(255, 210, 190, 0.8) 70%, // 中间：浅红橙色
|
||
rgba(255, 220, 200, 0.75) 100% // 结束：浅橙黄色
|
||
);
|
||
```
|
||
- **文字颜色**：`#333333`（黑色）
|
||
- **边框**：`rgba(255, 200, 150, 0.3)`（红黄色边框）
|
||
- **阴影**：`rgba(255, 180, 120, 0.15)`（红黄色阴影）
|
||
- **不规则圆形装饰**：
|
||
- `&::before`：`rgba(255, 140, 140, 0.4)`（红色径向渐变）
|
||
- `&::after`：`rgba(255, 160, 130, 0.35)`（红橙色径向渐变）
|
||
|
||
```scss
|
||
.page-header, .module-home-header, .personal-homepage-header {
|
||
background: linear-gradient(to right,
|
||
rgba(255, 200, 200, 0.9) 0%,
|
||
rgba(255, 210, 190, 0.8) 70%,
|
||
rgba(255, 220, 200, 0.75) 100%
|
||
);
|
||
color: #333333;
|
||
border: 1px solid rgba(255, 200, 150, 0.3);
|
||
box-shadow: 0 2px 8px rgba(255, 180, 120, 0.15);
|
||
|
||
&::before {
|
||
background: radial-gradient(circle, rgba(255, 140, 140, 0.4), transparent);
|
||
}
|
||
|
||
&::after {
|
||
background: radial-gradient(circle, rgba(255, 160, 130, 0.35), transparent);
|
||
}
|
||
}
|
||
```
|
||
|
||
**4. 页面容器（PageContainer）**
|
||
|
||
- **背景**：蓝色系渐变
|
||
```scss
|
||
background: linear-gradient(135deg,
|
||
rgba(49, 171, 218, 0.06) 0%, // 起始：中等蓝色
|
||
rgba(87, 190, 216, 0.05) 33%, // 中间：浅蓝色/青色
|
||
rgba(49, 171, 218, 0.04) 66%, // 中间：中等蓝色
|
||
rgba(35, 115, 149, 0.03) 100% // 结束：深蓝色
|
||
);
|
||
```
|
||
|
||
**5. 页面内容区域（page-body）**
|
||
|
||
- **作用**：包裹除 `page-header` 外的所有页面内容，提供统一的高度管理和布局容器
|
||
- **高度计算**：使用 CSS 变量自动计算，占据除 `page-header` 外的剩余空间
|
||
- **布局特性**：提供 flex 布局容器，支持内部内容的灵活布局
|
||
|
||
```scss
|
||
// page-body 样式定义（在 common.scss 中）
|
||
.page-body {
|
||
height: var(--page-body-height);
|
||
display: flex;
|
||
flex-direction: column;
|
||
overflow: hidden;
|
||
min-height: 0;
|
||
}
|
||
```
|
||
|
||
**CSS 变量定义**（在 `index.scss` 中）：
|
||
```scss
|
||
--page-header-height: 50px; // page-header的高度
|
||
--page-header-margin-bottom: 16px; // page-header的margin-bottom
|
||
--page-content-height: calc(100vh - var(--navbar-height) - var(--tabs-height) - var(--page-container-padding));
|
||
--page-body-height: calc(var(--page-content-height) - var(--page-header-height) - var(--page-header-margin-bottom));
|
||
```
|
||
|
||
**使用规范**：
|
||
- ✅ **必须使用**：所有使用 `page-header` 的页面都必须使用 `page-body` 包裹内容
|
||
- ✅ **位置**：紧跟在 `page-header` 之后
|
||
- ✅ **内容**：包裹所有页面内容（卡片、表格、标签页等）
|
||
- ❌ **禁止**：不要在 `page-body` 内再嵌套 `page-body`
|
||
|
||
**6. 标签页（AppTabs）**
|
||
|
||
- **默认标签**：
|
||
- 背景：透明
|
||
- 文字：`#666666`（灰色）
|
||
- **激活标签**：
|
||
- 背景：`rgba(215, 0, 1, 0.1)`（红色半透明，10%不透明度）
|
||
- 文字：`#D70001`（品牌红色）
|
||
- **Hover状态**：
|
||
- 背景：`rgba(0, 0, 0, 0.06)`（黑色半透明，6%不透明度）
|
||
- 文字：`#333333`（黑色）
|
||
|
||
```scss
|
||
.tab-item {
|
||
color: #666666;
|
||
|
||
&:hover {
|
||
background: rgba(0, 0, 0, 0.06);
|
||
color: #333333;
|
||
}
|
||
|
||
&.active-tab {
|
||
background: rgba(215, 0, 1, 0.1);
|
||
color: #D70001;
|
||
}
|
||
}
|
||
```
|
||
|
||
**颜色使用原则**
|
||
|
||
1. **主色调**：红色（`#D70001`）用于主要背景和强调色
|
||
2. **对比色**：白色（`#ffffff`）用于红色背景上的文字和图标
|
||
3. **选中状态**：白色半透明背景（`rgba(255, 255, 255, 0.85)`）+ 黑色文字（`#333333`）
|
||
4. **Hover状态**：白色半透明背景（`rgba(255, 255, 255, 0.35)`）+ 白色文字
|
||
5. **信息项**：白色半透明背景（`rgba(255, 255, 255, 0.8)`）+ 黑色文字，圆角 `24px`
|
||
6. **页面头部**：红色到黄色渐变，营造温暖感
|
||
7. **页面容器**：蓝色系渐变，与红色形成对比，保持清新感
|
||
|
||
**禁止使用的颜色**
|
||
|
||
- ❌ 硬编码的颜色值（应使用CSS变量或统一的颜色定义）
|
||
- ❌ 与品牌主色不协调的颜色（如紫色、绿色等，除非特殊场景）
|
||
- ❌ 过于鲜艳或刺眼的颜色组合
|
||
|
||
#### 页面头部样式规范
|
||
|
||
**统一使用红色到黄色渐变背景**
|
||
|
||
所有页面头部（`.page-header`、`.module-home-header`、`.personal-homepage-header`）统一使用红色到黄色的渐变背景，确保视觉一致性：
|
||
|
||
```scss
|
||
// 标准渐变背景配置（从左到右）
|
||
background: linear-gradient(to right,
|
||
rgba(255, 200, 200, 0.9) 0%, // 起始：浅红色，90%不透明度
|
||
rgba(255, 210, 190, 0.8) 70%, // 中间：浅红橙色，80%不透明度
|
||
rgba(255, 220, 200, 0.75) 100% // 结束：浅橙黄色，75%不透明度
|
||
);
|
||
|
||
// 边框和阴影
|
||
border: 1px solid rgba(255, 200, 150, 0.3); // 红黄色边框
|
||
box-shadow: 0 2px 8px rgba(255, 180, 120, 0.15); // 红黄色阴影
|
||
|
||
// 不规则圆形装饰
|
||
&::before {
|
||
content: '';
|
||
position: absolute;
|
||
width: 150px;
|
||
height: 150px;
|
||
border-radius: 50%;
|
||
background: radial-gradient(circle, rgba(255, 140, 140, 0.4), transparent);
|
||
top: -75px;
|
||
left: -75px;
|
||
z-index: 0;
|
||
pointer-events: none;
|
||
}
|
||
|
||
&::after {
|
||
content: '';
|
||
position: absolute;
|
||
width: 130px;
|
||
height: 130px;
|
||
border-radius: 50%;
|
||
background: radial-gradient(circle, rgba(255, 160, 130, 0.35), transparent);
|
||
bottom: -65px;
|
||
right: -65px;
|
||
z-index: 0;
|
||
pointer-events: none;
|
||
}
|
||
```
|
||
|
||
**颜色规范**：
|
||
- **主色调**：红色系渐变（`rgba(255, 200, 200, ...)` → `rgba(255, 220, 200, ...)`）
|
||
- **装饰色**：`rgba(255, 140, 140, 0.4)`（红色径向渐变）和 `rgba(255, 160, 130, 0.35)`（红橙色径向渐变）
|
||
- **文字颜色**：`#333333`（黑色）
|
||
|
||
**应用场景**：
|
||
- `.page-header` - 普通列表页头部
|
||
- `.module-home-header` - 模块首页头部（不规则圆形装饰尺寸更大）
|
||
- `.personal-homepage-header` - 工作台首页头部
|
||
|
||
**注意事项**：
|
||
1. 所有 header 必须使用相同的渐变配置
|
||
2. 内容区域需要设置 `z-index: 1` 或更高，确保显示在背景装饰之上
|
||
3. 不规则圆形装饰使用 `pointer-events: none` 避免影响交互
|
||
4. 渐变方向为 `to right`（从左到右），不使用角度渐变避免波浪效果
|
||
|
||
#### 使用 common.scss 统一样式
|
||
项目已在 `src/assets/styles/common.scss` 中定义了页面头部样式，所有页面应使用统一的样式类：
|
||
|
||
**页面布局类**：
|
||
- `.page-header` - 页面头部容器
|
||
- `.page-body` - 页面内容区域（包裹除header外的所有内容）
|
||
- `.header-content` - 头部内容区域
|
||
- `.header-left` - 头部左侧区域
|
||
- `.page-title` - 页面标题
|
||
- `.page-description` - 页面描述
|
||
- `.header-actions` - 头部操作区域
|
||
- `.add-btn` - 特殊的新增按钮样式
|
||
|
||
#### CSS 变量和设计令牌
|
||
项目已在 `src/assets/styles/index.scss` 中定义了完整的设计令牌系统：
|
||
|
||
- **颜色系统**: `--primary-color`, `--success-color` 等
|
||
- **间距系统**: `--spacing-small`, `--spacing-medium` 等
|
||
- **高度系统**: `--full-content-height`, `--card-content-height` 等
|
||
- **阴影系统**: `--shadow-light`, `--shadow-medium` 等
|
||
- **Z-Index层级**: `--z-index-header`, `--z-index-modal` 等
|
||
|
||
### 3. 边框颜色规范
|
||
|
||
#### 统一边框颜色使用
|
||
为确保界面的一致性和品牌统一性，项目采用统一的边框颜色规范：
|
||
|
||
**标准边框颜色：`var(--customer-board-color)`**
|
||
|
||
```scss
|
||
// 标准边框样式
|
||
.standard-border {
|
||
border: 1px solid var(--customer-board-color);
|
||
}
|
||
|
||
// 卡片边框
|
||
.card-container {
|
||
border: 1px solid var(--customer-board-color);
|
||
border-radius: 8px;
|
||
}
|
||
|
||
// 分割线边框
|
||
.divider-line {
|
||
border-bottom: 1px solid var(--customer-board-color);
|
||
}
|
||
|
||
// 输入框边框
|
||
.input-field {
|
||
border: 1px solid var(--customer-board-color);
|
||
border-radius: 4px;
|
||
}
|
||
```
|
||
|
||
#### 边框使用场景
|
||
| 场景 | 边框样式 | 说明 |
|
||
|------|----------|------|
|
||
| **容器边框** | `1px solid var(--customer-board-color)` | 卡片、面板、弹窗等容器 |
|
||
| **分割线** | `1px solid var(--customer-board-color)` | 列表项、内容区域之间的分割 |
|
||
| **输入框** | `1px solid var(--customer-board-color)` | 表单输入框、选择器等 |
|
||
| **表格边框** | `1px solid var(--customer-board-color)` | 表格单元格、表头等 |
|
||
| **悬浮状态** | `1px solid var(--customer-board-color)` | 按钮、链接等悬浮时的边框 |
|
||
|
||
#### 禁止使用的边框颜色
|
||
- ❌ 硬编码的颜色值：`#e4e7ed`, `#f1f5f9`, `#e5e7eb` 等
|
||
- ❌ 直接使用 Element Plus 默认边框色
|
||
- ❌ 使用不统一的颜色变量
|
||
|
||
#### 正确示例
|
||
```scss
|
||
// ✅ 正确：使用统一的边框颜色变量
|
||
.email-list {
|
||
border-bottom: 1px solid var(--customer-board-color);
|
||
}
|
||
|
||
// ✅ 正确：使用统一的边框颜色变量
|
||
.sidebar-section {
|
||
border-bottom: 1px solid var(--customer-board-color);
|
||
}
|
||
|
||
// ✅ 正确：使用统一的边框颜色变量
|
||
.dialog-content {
|
||
border: 1px solid var(--customer-board-color);
|
||
}
|
||
```
|
||
|
||
#### 错误示例
|
||
```scss
|
||
// ❌ 错误：使用硬编码颜色值
|
||
.email-list {
|
||
border-bottom: 1px solid #e4e7ed;
|
||
}
|
||
|
||
// ❌ 错误：使用不统一的颜色变量
|
||
.sidebar-section {
|
||
border-bottom: 1px solid #f1f5f9;
|
||
}
|
||
```
|
||
|
||
### 4. 组件样式规范
|
||
|
||
#### Element Plus 组件样式增强
|
||
项目已对 Element Plus 组件进行了样式增强：
|
||
|
||
- **卡片组件**: 统一圆角和阴影
|
||
- **抽屉组件**: 标准化头部和底部样式
|
||
- **对话框组件**: 统一边框和间距
|
||
- **滚动条**: 自定义滚动条样式
|
||
|
||
#### 页面内容布局类
|
||
- `.main-card` - 主要内容卡片
|
||
- `.search-section` - 搜索区域
|
||
- `.table-section` - 表格区域
|
||
- `.stats-section` - 统计区域
|
||
- `.feature-section` - 功能区域
|
||
- `.pagination-section` - 分页区域（配合 flex 布局可实现固定在底部）
|
||
|
||
## 文件预览规范
|
||
|
||
### 使用 FileViewer 组件
|
||
|
||
**统一使用 FileViewer 组件处理文件预览**
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 文件预览 -->
|
||
<FileViewer :file="currentFile" @download="handleDownload" />
|
||
</template>
|
||
|
||
<script setup>
|
||
import FileViewer from '@/views/knowledge/repository/browser/FileViewer.vue'
|
||
|
||
const currentFile = ref(null)
|
||
|
||
const handleDownload = (file) => {
|
||
// 下载逻辑
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 支持的文件类型
|
||
|
||
- **Office文档**: DOC, DOCX, XLS, XLSX, PPT, PPTX
|
||
- **PDF文档**: PDF
|
||
- **图片文件**: JPG, PNG, GIF, BMP, SVG
|
||
- **文本文件**: TXT, MD, JSON, XML
|
||
- **视频文件**: MP4, AVI, MOV
|
||
- **音频文件**: MP3, WAV, OGG
|
||
- **在线文档**: 富文本内容
|
||
|
||
### FileViewer 组件特性
|
||
|
||
- 自动识别文件类型
|
||
- 支持在线预览
|
||
- 统一的预览界面
|
||
- 不支持预览的文件显示下载提示
|
||
|
||
## 路由规范
|
||
|
||
### 1. 路由配置规范
|
||
|
||
#### 路由命名规范
|
||
```javascript
|
||
// 路由命名遵循以下规则：
|
||
// 1. 使用 kebab-case 格式
|
||
// 2. 层级结构清晰
|
||
// 3. 名称具有语义性
|
||
|
||
const routes = [
|
||
{
|
||
path: '/crm',
|
||
name: 'Crm',
|
||
component: Layout,
|
||
meta: {
|
||
title: 'CRM',
|
||
icon: 'UserFilled',
|
||
permission: 'crm'
|
||
},
|
||
children: [
|
||
{
|
||
path: 'customer',
|
||
name: 'CrmCustomer',
|
||
component: () => import('@/views/crm/CustomerInfo.vue'),
|
||
meta: {
|
||
title: '客户信息',
|
||
icon: 'User',
|
||
permission: 'crm:customer',
|
||
cache: true
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 路由 Meta 信息规范
|
||
```javascript
|
||
// Meta 字段标准定义
|
||
meta: {
|
||
title: '页面标题', // 必填：页面标题
|
||
icon: 'ElementIcon', // 可选：菜单图标
|
||
permission: 'module:action', // 可选：权限标识
|
||
cache: true, // 可选：是否缓存页面
|
||
hidden: false, // 可选：是否隐藏菜单
|
||
```
|
||
|
||
### 2. 路由守卫规范
|
||
|
||
#### 权限检查流程
|
||
```javascript
|
||
// 统一的路由守卫逻辑
|
||
router.beforeEach(async (to, from, next) => {
|
||
const userStore = useUserStore()
|
||
const permissionStore = usePermissionStore()
|
||
|
||
// 1. 公开页面直接放行
|
||
if (PUBLIC_PAGES.has(to.path)) {
|
||
next()
|
||
return
|
||
}
|
||
|
||
// 2. 登录状态检查
|
||
if (!userStore.isLoggedIn) {
|
||
userStore.redirectToLoginWithUrl(to.fullPath, router)
|
||
return
|
||
}
|
||
|
||
// 3. 权限检查
|
||
if (to.meta.permission && !permissionStore.hasPermission(to.meta.permission)) {
|
||
next('/403')
|
||
return
|
||
}
|
||
|
||
next()
|
||
})
|
||
```
|
||
|
||
### 3. 路由跳转规范
|
||
|
||
#### 编程式导航
|
||
```javascript
|
||
// 推荐：使用命名路由
|
||
router.push({ name: 'CrmCustomer', params: { id: '123' } })
|
||
|
||
// 推荐：带查询参数
|
||
router.push({
|
||
name: 'CrmCustomer',
|
||
query: { tab: 'projects', status: 'active' }
|
||
})
|
||
|
||
// 避免：硬编码路径
|
||
// router.push('/crm/customer/123')
|
||
```
|
||
|
||
#### 路由参数处理
|
||
```javascript
|
||
// 在组件中获取路由参数
|
||
const route = useRoute()
|
||
const router = useRouter()
|
||
|
||
// 获取路径参数
|
||
const customerId = route.params.id
|
||
|
||
// 获取查询参数
|
||
const activeTab = route.query.tab || 'basic'
|
||
|
||
// 监听路由变化
|
||
watch(() => route.params.id, (newId) => {
|
||
if (newId) {
|
||
loadCustomerData(newId)
|
||
}
|
||
})
|
||
```
|
||
|
||
## 状态管理规范
|
||
|
||
### 1. Store 组织结构
|
||
|
||
#### Store 命名和文件组织
|
||
```
|
||
# 全局状态管理
|
||
stores/
|
||
├── user.js # 用户状态
|
||
├── permission.js # 权限状态
|
||
├── app.js # 应用全局状态
|
||
└── utils/ # 状态工具
|
||
└── storeHelpers.js
|
||
|
||
# 业务模块状态管理（放在各自模块内）
|
||
views/
|
||
├── crm/
|
||
│ ├── stores/
|
||
│ │ └── useCrmStore.js # CRM模块状态
|
||
│ ├── components/
|
||
│ └── ...
|
||
├── knowledge/
|
||
│ ├── stores/
|
||
│ │ └── useKnowledgeStore.js # 知识库模块状态
|
||
│ ├── components/
|
||
│ └── ...
|
||
└── email/
|
||
├── stores/
|
||
│ └── useEmailStore.js # 邮件模块状态
|
||
├── components/
|
||
└── ...
|
||
```
|
||
|
||
### 2. Store 设计规范
|
||
|
||
#### 标准 Store 结构
|
||
```javascript
|
||
// views/crm/stores/useCrmStore.js
|
||
import { defineStore } from 'pinia'
|
||
import { ref, computed } from 'vue'
|
||
import * as crmApi from '../api/crmApi'
|
||
|
||
export const useCrmStore = defineStore('crm', () => {
|
||
// ========== 状态定义 ==========
|
||
const customers = ref([])
|
||
const projects = ref([])
|
||
const loading = ref(false)
|
||
const error = ref(null)
|
||
|
||
// ========== 计算属性 ==========
|
||
const activeCustomers = computed(() =>
|
||
customers.value.filter(customer => customer.status === 'active')
|
||
)
|
||
|
||
const totalProjects = computed(() => projects.value.length)
|
||
|
||
// ========== Actions ==========
|
||
const loadCustomers = async (params = {}) => {
|
||
loading.value = true
|
||
error.value = null
|
||
|
||
try {
|
||
const response = await crmApi.getCustomerPage(params)
|
||
customers.value = response.records || []
|
||
return response
|
||
} catch (err) {
|
||
error.value = err.message
|
||
throw err
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
const addCustomer = async (customerData) => {
|
||
try {
|
||
const newCustomer = await crmApi.createCustomer(customerData)
|
||
customers.value.unshift(newCustomer)
|
||
return newCustomer
|
||
} catch (err) {
|
||
error.value = err.message
|
||
throw err
|
||
}
|
||
}
|
||
|
||
const updateCustomer = async (id, customerData) => {
|
||
try {
|
||
const updatedCustomer = await crmApi.updateCustomer(id, customerData)
|
||
const index = customers.value.findIndex(c => c.id === id)
|
||
if (index !== -1) {
|
||
customers.value[index] = updatedCustomer
|
||
}
|
||
return updatedCustomer
|
||
} catch (err) {
|
||
error.value = err.message
|
||
throw err
|
||
}
|
||
}
|
||
|
||
const removeCustomer = async (id) => {
|
||
try {
|
||
await crmApi.deleteCustomer(id)
|
||
customers.value = customers.value.filter(c => c.id !== id)
|
||
} catch (err) {
|
||
error.value = err.message
|
||
throw err
|
||
}
|
||
}
|
||
|
||
// ========== 工具方法 ==========
|
||
const resetState = () => {
|
||
customers.value = []
|
||
projects.value = []
|
||
loading.value = false
|
||
error.value = null
|
||
}
|
||
|
||
const findCustomerById = (id) => {
|
||
return customers.value.find(customer => customer.id === id)
|
||
}
|
||
|
||
return {
|
||
// 状态
|
||
customers,
|
||
projects,
|
||
loading,
|
||
error,
|
||
|
||
// 计算属性
|
||
activeCustomers,
|
||
totalProjects,
|
||
|
||
// 方法
|
||
loadCustomers,
|
||
addCustomer,
|
||
updateCustomer,
|
||
removeCustomer,
|
||
resetState,
|
||
findCustomerById
|
||
}
|
||
})
|
||
```
|
||
|
||
### 3. Store 使用规范
|
||
|
||
#### 在组件中使用 Store
|
||
```javascript
|
||
// 组件中的标准用法
|
||
<script setup>
|
||
import { useCrmStore } from './stores/useCrmStore'
|
||
import { storeToRefs } from 'pinia'
|
||
|
||
const crmStore = useCrmStore()
|
||
|
||
// 响应式引用状态（使用 storeToRefs）
|
||
const { customers, loading, error } = storeToRefs(crmStore)
|
||
|
||
// 直接使用方法
|
||
const { loadCustomers, addCustomer } = crmStore
|
||
|
||
// 组件挂载时加载数据
|
||
onMounted(() => {
|
||
loadCustomers()
|
||
})
|
||
|
||
// 处理错误
|
||
watch(error, (newError) => {
|
||
if (newError) {
|
||
ElMessage.error(newError)
|
||
}
|
||
})
|
||
</script>
|
||
```
|
||
|
||
#### 跨 Store 通信
|
||
```javascript
|
||
// 在业务模块 Store 中使用全局 Store
|
||
export const useCrmStore = defineStore('crm', () => {
|
||
const userStore = useUserStore() // 全局用户状态
|
||
const permissionStore = usePermissionStore() // 全局权限状态
|
||
|
||
const loadCustomers = async () => {
|
||
// 检查权限
|
||
if (!permissionStore.hasPermission('crm:customer:read')) {
|
||
throw new Error('没有访问权限')
|
||
}
|
||
|
||
// 使用用户信息
|
||
const params = {
|
||
userId: userStore.userId,
|
||
tenantId: userStore.currentTenant?.id
|
||
}
|
||
|
||
// API调用...
|
||
}
|
||
})
|
||
```
|
||
|
||
### 4. 状态持久化
|
||
|
||
#### 使用 localStorage 持久化
|
||
```javascript
|
||
import { defineStore } from 'pinia'
|
||
|
||
export const useAppStore = defineStore('app', () => {
|
||
// 从 localStorage 恢复状态
|
||
const sidebarCollapsed = ref(
|
||
localStorage.getItem('sidebarCollapsed') === 'true'
|
||
)
|
||
|
||
const toggleSidebar = () => {
|
||
sidebarCollapsed.value = !sidebarCollapsed.value
|
||
// 持久化到 localStorage
|
||
localStorage.setItem('sidebarCollapsed', sidebarCollapsed.value.toString())
|
||
}
|
||
|
||
return {
|
||
sidebarCollapsed,
|
||
toggleSidebar
|
||
}
|
||
})
|
||
```
|
||
|
||
## 接口处理规范
|
||
|
||
### 1. 接口调用规范
|
||
|
||
#### 基于 http.js 的统一调用
|
||
项目已使用 `src/utils/http.js` 进行 Ajax 响应封装，所有接口调用必须使用统一的 request 方法：
|
||
|
||
```javascript
|
||
// 正确：使用统一的 http 实例
|
||
import request from '@/utils/http'
|
||
|
||
export function getCustomerList(params) {
|
||
return request({
|
||
url: '/kx-pv/crm/customer/page',
|
||
method: 'post',
|
||
data: params
|
||
})
|
||
}
|
||
|
||
// 错误：直接使用 axios
|
||
// import axios from 'axios'
|
||
// axios.post('/api/customer', data)
|
||
```
|
||
|
||
### 2. 接口文件组织规范
|
||
|
||
#### API 文件结构
|
||
```
|
||
# 全局API接口
|
||
api/
|
||
├── index.js # API 统一导出
|
||
├── user.js # 用户相关接口
|
||
├── permission.js # 权限相关接口
|
||
└── wiki/ # Wiki相关接口
|
||
├── comment.js
|
||
├── favorite.js
|
||
└── version.js
|
||
|
||
# 业务模块API接口（放在各自模块内）
|
||
views/
|
||
├── crm/
|
||
│ └── api/
|
||
│ └── crmApi.js # CRM模块接口
|
||
├── email/
|
||
│ └── api/
|
||
│ └── emailApi.js # 邮件模块接口
|
||
└── knowledge/
|
||
└── api/
|
||
└── knowledgeApi.js # 知识库模块接口
|
||
```
|
||
|
||
#### 接口命名规范
|
||
```javascript
|
||
// 命名规范：动词 + 资源名 + 操作类型
|
||
// CRUD 操作标准命名
|
||
export function getCustomerList(params) // 获取列表
|
||
export function getCustomerPage(params) // 分页查询
|
||
export function getCustomerDetail(id) // 获取详情
|
||
export function createCustomer(data) // 创建
|
||
export function updateCustomer(id, data) // 更新
|
||
export function deleteCustomer(id) // 删除
|
||
|
||
// 特殊操作命名
|
||
export function exportCustomers(params) // 导出
|
||
export function importCustomers(file) // 导入
|
||
export function batchDeleteCustomers(ids) // 批量删除
|
||
export function enableCustomer(id) // 启用
|
||
export function disableCustomer(id) // 禁用
|
||
```
|
||
|
||
### 3. 接口文档规范
|
||
|
||
#### 标准接口注释
|
||
```javascript
|
||
/**
|
||
* 获取客户分页列表
|
||
* @param {Object} params - 查询参数
|
||
* @param {number} params.pageNo - 页码（从1开始）
|
||
* @param {number} params.pageSize - 每页大小
|
||
* @param {string} [params.keyword] - 搜索关键词
|
||
* @param {string} [params.status] - 客户状态：active|inactive
|
||
* @param {string} [params.createTimeStart] - 创建时间开始
|
||
* @param {string} [params.createTimeEnd] - 创建时间结束
|
||
* @returns {Promise<Object>} 返回分页数据
|
||
* @returns {Object[]} returns.records - 客户列表
|
||
* @returns {number} returns.total - 总数量
|
||
* @returns {number} returns.pageNo - 当前页码
|
||
* @returns {number} returns.pageSize - 每页大小
|
||
*
|
||
* @example
|
||
* const result = await getCustomerPage({
|
||
* pageNo: 1,
|
||
* pageSize: 20,
|
||
* keyword: '客户名称',
|
||
* status: 'active'
|
||
* })
|
||
*/
|
||
export function getCustomerPage(params) {
|
||
return request({
|
||
url: '/kx-pv/crm/customer/page',
|
||
method: 'post',
|
||
data: params
|
||
})
|
||
}
|
||
```
|
||
|
||
### 4. Mock 数据规范
|
||
|
||
#### Mock 开关管理
|
||
```javascript
|
||
// views/email/api/emailApi.js - Mock模式示例
|
||
import http from '@/utils/http'
|
||
import { EMAIL_LIST, createMockResponse } from '@/mock/emailData'
|
||
|
||
// Mock模式开关
|
||
const USE_MOCK = process.env.NODE_ENV === 'development'
|
||
|
||
export function getEmailList(params) {
|
||
if (USE_MOCK) {
|
||
// Mock 数据处理逻辑
|
||
let filteredEmails = [...EMAIL_LIST]
|
||
|
||
// 搜索筛选
|
||
if (params.search) {
|
||
const query = params.search.toLowerCase()
|
||
filteredEmails = filteredEmails.filter(email =>
|
||
email.subject?.toLowerCase().includes(query)
|
||
)
|
||
}
|
||
|
||
return Promise.resolve(createMockResponse(filteredEmails))
|
||
}
|
||
|
||
// 真实接口调用
|
||
return http({
|
||
url: '/kx-pv/email/list',
|
||
method: 'post',
|
||
data: params
|
||
})
|
||
}
|
||
```
|
||
|
||
### 5. 错误处理规范
|
||
|
||
#### 统一错误处理模式
|
||
```javascript
|
||
// 在 composable 中处理接口错误
|
||
export function useCustomerOperations() {
|
||
const loading = ref(false)
|
||
const error = ref(null)
|
||
|
||
const loadCustomers = async (params) => {
|
||
loading.value = true
|
||
error.value = null
|
||
|
||
try {
|
||
const result = await getCustomerPage(params)
|
||
return result
|
||
} catch (err) {
|
||
error.value = err.message || '获取客户列表失败'
|
||
ElMessage.error(error.value)
|
||
throw err
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
return {
|
||
loading,
|
||
error,
|
||
loadCustomers
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 标准错误处理
|
||
```javascript
|
||
// 统一的错误处理模式
|
||
export function createCustomer(data) {
|
||
return request({
|
||
url: '/kx-pv/crm/customer/create',
|
||
method: 'post',
|
||
data
|
||
})
|
||
}
|
||
|
||
// 在 composable 中处理错误
|
||
export function useCustomerOperations() {
|
||
const createCustomer = async (data) => {
|
||
try {
|
||
const result = await createCustomerApi(data)
|
||
ElMessage.success('创建客户成功')
|
||
return result
|
||
} catch (error) {
|
||
ElMessage.error(error.message || '创建客户失败')
|
||
throw error
|
||
}
|
||
}
|
||
|
||
return { createCustomer }
|
||
}
|
||
```
|
||
|
||
### 6. 日期时间处理规范
|
||
|
||
#### 日期时间格式转换规范
|
||
|
||
**技术规范说明**：
|
||
- 前端日期选择器（Element Plus）返回的格式为 `yyyy-MM-dd HH:mm:ss`（本地时间）
|
||
- 后端需要 ISO 8601 格式 `yyyy-MM-ddTHH:mm:ss+08:00`（东八区时区）
|
||
- 只处理包含时间部分的日期字符串（`yyyy-MM-dd HH:mm:ss`），纯日期（`yyyy-MM-dd`）不需要转换
|
||
- 如果已经是 ISO 格式，检查是否已有 Z 或时区信息，没有则添加 +08:00
|
||
|
||
#### 统一使用 time.js 工具函数
|
||
|
||
**必须使用 `formatDateToISO` 函数进行日期时间格式转换**
|
||
|
||
```javascript
|
||
// 正确：使用 time.js 中的 formatDateToISO 函数
|
||
import { formatDateToISO } from '@/utils/time'
|
||
|
||
export function createActionItem(data) {
|
||
const processedData = {
|
||
...data,
|
||
dueDate: formatDateToISO(data.dueDate) // 自动转换日期时间格式
|
||
}
|
||
|
||
return request({
|
||
url: '/kx-pv/action-item/create',
|
||
method: 'post',
|
||
data: processedData
|
||
})
|
||
}
|
||
```
|
||
|
||
#### 转换规则
|
||
|
||
| 输入格式 | 输出格式 | 说明 |
|
||
|---------|---------|------|
|
||
| `"2025-12-11 00:00:00"` | `"2025-12-11T00:00:00+08:00"` | 日期时间字符串，转换为 ISO 格式并添加 +08:00 |
|
||
| `"2025-12-11"` | `"2025-12-11"` | 纯日期，不处理，原样返回 |
|
||
| `"2025-12-11T00:00:00"` | `"2025-12-11T00:00:00+08:00"` | 已有 T 但无时区，添加 +08:00 |
|
||
| `"2025-12-11T00:00:00Z"` | `"2025-12-11T00:00:00Z"` | 已有 Z，保持不变 |
|
||
| `"2025-12-11T00:00:00+08:00"` | `"2025-12-11T00:00:00+08:00"` | 已有时区信息，保持不变 |
|
||
| `null` 或 `undefined` | `null` | 空值返回 null |
|
||
|
||
#### 使用场景
|
||
|
||
**1. 创建/更新数据时转换日期时间字段**
|
||
|
||
```javascript
|
||
// API 文件中
|
||
import { formatDateToISO } from '@/utils/time'
|
||
|
||
export function createTask(data) {
|
||
const processedData = {
|
||
...data,
|
||
startDate: formatDateToISO(data.startDate), // 日期时间字段需要转换
|
||
endDate: formatDateToISO(data.endDate)
|
||
}
|
||
|
||
return request({
|
||
url: '/kx-pv/task/create',
|
||
method: 'post',
|
||
data: processedData
|
||
})
|
||
}
|
||
```
|
||
|
||
**2. 查询参数中的日期时间范围**
|
||
|
||
```javascript
|
||
export function getTaskPage(params) {
|
||
const processedParams = {
|
||
...params,
|
||
startDateStart: params.startDateStart ? formatDateToISO(params.startDateStart) : undefined,
|
||
startDateEnd: params.startDateEnd ? formatDateToISO(params.startDateEnd) : undefined
|
||
}
|
||
|
||
return request({
|
||
url: '/kx-pv/task/page',
|
||
method: 'post',
|
||
data: processedParams
|
||
})
|
||
}
|
||
```
|
||
|
||
#### 日期选择器配置
|
||
|
||
**Element Plus 日期选择器标准配置**：
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 日期时间选择器 -->
|
||
<el-date-picker
|
||
v-model="formData.dueDate"
|
||
type="datetime"
|
||
placeholder="选择截止时间"
|
||
format="YYYY-MM-DD HH:mm"
|
||
value-format="YYYY-MM-DD HH:mm:ss"
|
||
/>
|
||
|
||
<!-- 日期选择器（纯日期，不需要转换） -->
|
||
<el-date-picker
|
||
v-model="formData.startDate"
|
||
type="date"
|
||
placeholder="选择开始日期"
|
||
format="YYYY-MM-DD"
|
||
value-format="YYYY-MM-DD"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
#### 注意事项
|
||
|
||
1. **只转换日期时间字段**：只有包含时间部分的日期字符串（`yyyy-MM-dd HH:mm:ss`）才需要转换
|
||
2. **纯日期不处理**：纯日期格式（`yyyy-MM-dd`）不需要转换，直接传递给后端
|
||
3. **统一使用工具函数**：所有日期时间格式转换必须使用 `time.js` 中的 `formatDateToISO` 函数
|
||
4. **API 层统一处理**：在 API 文件中统一进行格式转换，不要在组件中手动转换
|
||
5. **空值处理**：空值（`null`、`undefined`、空字符串）返回 `null`，不进行转换
|
||
|
||
#### 错误示例
|
||
|
||
```javascript
|
||
// ❌ 错误：手动拼接字符串
|
||
const dueDate = `${year}-${month}-${day}T${hours}:${minutes}:${seconds}+08:00`
|
||
|
||
// ❌ 错误：在组件中转换
|
||
const handleSubmit = () => {
|
||
const data = {
|
||
...formData,
|
||
dueDate: formData.dueDate.replace(' ', 'T') + '+08:00' // 不应该在组件中处理
|
||
}
|
||
createActionItem(data)
|
||
}
|
||
|
||
// ❌ 错误：转换纯日期
|
||
const startDate = formatDateToISO('2025-12-11') // 纯日期不需要转换
|
||
```
|
||
|
||
#### 正确示例
|
||
|
||
```javascript
|
||
// ✅ 正确：在 API 文件中统一转换
|
||
import { formatDateToISO } from '@/utils/time'
|
||
|
||
export function createActionItem(data) {
|
||
const processedData = {
|
||
...data,
|
||
dueDate: formatDateToISO(data.dueDate) // 日期时间字段转换
|
||
}
|
||
|
||
return request({
|
||
url: '/kx-pv/action-item/create',
|
||
method: 'post',
|
||
data: processedData
|
||
})
|
||
}
|
||
|
||
// ✅ 正确：纯日期不转换
|
||
export function createTask(data) {
|
||
const processedData = {
|
||
...data,
|
||
startDate: data.startDate, // 纯日期，不转换
|
||
endDate: data.endDate // 纯日期，不转换
|
||
}
|
||
|
||
return request({
|
||
url: '/kx-pv/task/create',
|
||
method: 'post',
|
||
data: processedData
|
||
})
|
||
}
|
||
```
|
||
|
||
### 7. 文件上传/下载规范
|
||
|
||
#### 文件上传规范
|
||
**必须使用已封装的阿里云OSS上传组件**
|
||
|
||
```javascript
|
||
// 使用项目封装的OSS上传工具
|
||
import { uesOssUpload } from '@/utils/uesOssUpload'
|
||
|
||
// 在组件中使用OSS上传
|
||
export function useFileUpload() {
|
||
const uploadRequest = uesOssUpload()
|
||
|
||
const handleUpload = async (file, options = {}) => {
|
||
try {
|
||
const result = await uploadRequest.upload(file, {
|
||
onProgress: (progress) => {
|
||
console.log(`上传进度: ${progress}%`)
|
||
},
|
||
...options
|
||
})
|
||
|
||
return {
|
||
fileId: result.fileId,
|
||
fileName: result.fileName,
|
||
originalName: file.name,
|
||
fileSize: file.size,
|
||
fileType: file.type,
|
||
filePath: result.filePath
|
||
}
|
||
} catch (error) {
|
||
ElMessage.error('文件上传失败')
|
||
throw error
|
||
}
|
||
}
|
||
|
||
return { handleUpload }
|
||
}
|
||
```
|
||
|
||
#### 文件下载规范
|
||
**使用 FileUtils 工具类统一处理文件下载**
|
||
|
||
```javascript
|
||
// utils/fileUtils.js - 添加标准下载方法
|
||
import SystemConfig from '@/config/config'
|
||
import { ElMessage } from 'element-plus'
|
||
|
||
class FileUtils {
|
||
/**
|
||
* 下载文件
|
||
* @param {string} fileId - 文件ID
|
||
* @param {string} fileName - 文件名
|
||
* @returns {Promise<void>}
|
||
*/
|
||
static async downloadFile(fileId, fileName) {
|
||
if (!fileId) {
|
||
ElMessage.error('文件ID不能为空')
|
||
return
|
||
}
|
||
|
||
if (!fileName) {
|
||
ElMessage.error('文件名不能为空')
|
||
return
|
||
}
|
||
|
||
const downloadUrl = SystemConfig.FILE_DOWNLOAD_BASE_URL + `/${fileId}?fileName=${encodeURIComponent(fileName)}`
|
||
|
||
try {
|
||
const response = await fetch(downloadUrl)
|
||
if (!response.ok) {
|
||
throw new Error(`HTTP error! status: ${response.status}`)
|
||
}
|
||
|
||
const blob = await response.blob()
|
||
const url = window.URL.createObjectURL(blob)
|
||
const link = document.createElement('a')
|
||
link.href = url
|
||
link.download = fileName
|
||
document.body.appendChild(link)
|
||
link.click()
|
||
document.body.removeChild(link)
|
||
window.URL.revokeObjectURL(url)
|
||
|
||
ElMessage.success('开始下载文件')
|
||
} catch (error) {
|
||
console.error('下载文件失败:', error)
|
||
ElMessage.error('下载文件失败')
|
||
throw error
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 下载文件（兼容对象参数）
|
||
* @param {Object} file - 文件信息对象
|
||
* @returns {Promise<void>}
|
||
*/
|
||
static async downloadFileByObject(file) {
|
||
if (!file) {
|
||
ElMessage.error('文件信息为空')
|
||
return
|
||
}
|
||
|
||
const fileId = file.fileId || file.id
|
||
const fileName = file.originalName || file.fileName || file.name || '文件'
|
||
|
||
return this.downloadFile(fileId, fileName)
|
||
}
|
||
}
|
||
|
||
export default FileUtils
|
||
```
|
||
|
||
#### 在组件中使用
|
||
```javascript
|
||
// 在业务组件中使用
|
||
import FileUtils from '@/utils/fileUtils'
|
||
|
||
// 方式1：直接传入fileId和fileName
|
||
const handleDownload = async () => {
|
||
try {
|
||
await FileUtils.downloadFile(fileId, fileName)
|
||
} catch (error) {
|
||
console.error('下载失败:', error)
|
||
}
|
||
}
|
||
|
||
// 方式2：传入文件对象（兼容现有代码）
|
||
const handleDownloadByObject = async (file) => {
|
||
try {
|
||
await FileUtils.downloadFileByObject(file)
|
||
} catch (error) {
|
||
console.error('下载失败:', error)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 组件设计原则
|
||
|
||
#### 单一职责原则
|
||
- 每个组件只负责一个功能领域
|
||
- 使用 composable 函数分离业务逻辑
|
||
- 避免组件代码超过 500 行
|
||
|
||
#### 可复用性原则
|
||
- 提取公共逻辑到 composable 函数
|
||
- 业务组件放在模块的 components 文件夹
|
||
- 通用组件放在 src/components 文件夹
|
||
|
||
#### Composable 模式
|
||
```javascript
|
||
// 推荐：使用 composable 管理复杂逻辑
|
||
export function useFileOperations() {
|
||
const loading = ref(false)
|
||
|
||
const uploadFile = async (file) => {
|
||
loading.value = true
|
||
try {
|
||
// 上传逻辑
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
return {
|
||
loading,
|
||
uploadFile
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 代码质量规范
|
||
|
||
#### 组件文档注释
|
||
```javascript
|
||
/**
|
||
* 文件预览组件
|
||
* @description 支持多种文件类型的在线预览
|
||
* @author 团队名称
|
||
* @date 2024-01-01
|
||
*/
|
||
|
||
// Props 定义
|
||
const props = defineProps({
|
||
file: {
|
||
type: Object,
|
||
required: true,
|
||
default: () => ({})
|
||
}
|
||
})
|
||
```
|
||
|
||
#### 统一错误处理
|
||
```javascript
|
||
// 在 composable 中处理错误
|
||
export function useApiCall() {
|
||
const loading = ref(false)
|
||
const error = ref(null)
|
||
|
||
const execute = async (apiFunction, errorMessage = '操作失败') => {
|
||
loading.value = true
|
||
error.value = null
|
||
|
||
try {
|
||
const result = await apiFunction()
|
||
return result
|
||
} catch (err) {
|
||
error.value = err
|
||
ElMessage.error(errorMessage)
|
||
throw err
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
return { loading, error, execute }
|
||
}
|
||
```
|
||
|
||
### 3. 性能优化建议
|
||
|
||
#### 组件懒加载
|
||
```javascript
|
||
// 推荐：使用动态组件加载器
|
||
import { useDynamicLoader } from '@/utils/dynamicComponentLoader'
|
||
|
||
const { getAsyncComponent } = useDynamicLoader()
|
||
const LazyDialog = getAsyncComponent('CreateDialog')
|
||
```
|
||
|
||
#### 大数据优化
|
||
```vue
|
||
<!-- vxe-table 虚拟滚动 -->
|
||
<vxe-table
|
||
:data="tableData"
|
||
:scroll-y="{ enabled: true, gt: 100 }"
|
||
:height="var(--card-content-height)"
|
||
>
|
||
<!-- 表格配置 -->
|
||
</vxe-table>
|
||
```
|
||
|
||
## 总结
|
||
|
||
本设计规范确保了项目的统一性和可维护性，所有开发成员应严格遵循。
|
||
|
||
### 核心要求
|
||
1. **页面结构统一**: 使用 PageContainer + 标准页面结构
|
||
2. **组件库优先**: 基于 Element Plus，避免重度定制
|
||
3. **表格统一**: 必须使用 vxe-table
|
||
4. **文件预览统一**: 使用 FileViewer 组件
|
||
5. **图标规范**: 只使用 Element Plus 图标库
|
||
6. **样式统一**: 使用 common.scss 中的全局样式
|
||
7. **路由规范**: 统一路由配置和守卫机制
|
||
8. **状态管理**: 业务模块内管理，全局状态分离
|
||
9. **接口调用**: 基于 http.js 统一处理
|
||
10. **业务组件**: 按模块组织，自包含结构
|
||
11. **代码质量**: 单一职责、可复用、高性能
|
||
12. **骨架屏规范**: 数据加载时使用 el-skeleton 组件
|
||
13. **分页规范**: 使用 el-pagination 默认样式，简洁布局
|
||
14. **通知详情组件**: 使用 NotificationDetail 组件统一展示通知详情
|
||
|
||
### 开发流程
|
||
1. **新建页面**: 复制标准页面结构模板
|
||
2. **配置路由**: 按照路由规范配置路由和权限
|
||
3. **创建模块**: 在业务模块内创建 stores 和 api 目录
|
||
4. **开发 Store**: 使用标准 Store 结构管理模块状态
|
||
5. **开发 API**: 基于 http.js 创建模块接口调用
|
||
6. **添加功能**: 优先使用现有组件和 composable
|
||
7. **样式开发**: 使用全局样式类，避免重复定义
|
||
8. **图标选择**: 从规范的图标列表中选择
|
||
9. **测试验证**: 确保功能正常和性能良好
|
||
10. **代码审查**: 确保符合所有规范要求
|
||
|
||
---
|
||
|
||
*版本: v2.0*
|
||
*更新时间: 2024年1月*
|
||
*维护团队: 前端架构团队* |