docs: 更新页面开发数据模板，补充路由参数和数据结构说明
This commit is contained in:
parent
7d0b4e76c5
commit
1280c11bbc
703
页面开发数据模板.md
703
页面开发数据模板.md
@ -1,570 +1,207 @@
|
||||
# 页面开发数据模板
|
||||
|
||||
> 基于 uspscale (秤台设备管理) 页面开发经验总结的完整开发模板
|
||||
|
||||
## 1. 基本信息配置
|
||||
# 页面开发指南
|
||||
|
||||
## 路由配置
|
||||
1. 路由参数
|
||||
```typescript
|
||||
// 路由定义
|
||||
{
|
||||
// 页面基本信息
|
||||
pageInfo: {
|
||||
moduleName: "uspscale", // 模块名称（小写，用于路径）
|
||||
displayName: "秤台设备管理", // 显示名称
|
||||
baseRoute: "admin/uspscale", // 路由路径
|
||||
referenceModule: "admin/room" // 参考的现有模块（用于复制结构）
|
||||
path: '/admin/device',
|
||||
name: 'admin/device',
|
||||
component: () => import('/@/views/admin/device/index.vue'),
|
||||
meta: {
|
||||
title: '设备管理',
|
||||
icon: 'ele-Setting',
|
||||
roles: ['admin']
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. API接口定义
|
||||
|
||||
2. 权限控制
|
||||
```typescript
|
||||
{
|
||||
// API配置
|
||||
apiConfig: {
|
||||
baseEndpoint: "/api/admin/usp-scale", // API基础路径
|
||||
endpoints: {
|
||||
getPage: "get-page", // 分页查询
|
||||
get: "get", // 单条查询
|
||||
add: "add", // 新增
|
||||
update: "update", // 更新
|
||||
softDelete: "soft-delete" // 软删除（推荐）
|
||||
// delete: "delete" // 硬删除（可选）
|
||||
}
|
||||
}
|
||||
}
|
||||
// 按钮权限
|
||||
v-auth="'api:admin:device:add'" // 新增权限
|
||||
v-auth="'api:admin:device:update'" // 修改权限
|
||||
v-auth="'api:admin:device:soft-delete'" // 删除权限
|
||||
```
|
||||
|
||||
## 3. 数据字段定义
|
||||
|
||||
## 数据结构
|
||||
1. 列表查询参数
|
||||
```typescript
|
||||
{
|
||||
// 字段定义
|
||||
fields: {
|
||||
// 主键字段
|
||||
primaryKey: {
|
||||
name: "id",
|
||||
type: "number",
|
||||
required: true
|
||||
},
|
||||
|
||||
// 基本字段
|
||||
basicFields: [
|
||||
{
|
||||
name: "deviceNo",
|
||||
type: "string",
|
||||
label: "设备编号",
|
||||
required: true,
|
||||
component: "input",
|
||||
placeholder: "请输入设备编号"
|
||||
},
|
||||
{
|
||||
name: "assetNo",
|
||||
type: "string",
|
||||
label: "资产编号",
|
||||
required: false,
|
||||
component: "input",
|
||||
placeholder: "请输入资产编号"
|
||||
}
|
||||
],
|
||||
|
||||
// 下拉选择字段
|
||||
selectFields: [
|
||||
{
|
||||
name: "roomID",
|
||||
type: "number",
|
||||
label: "房间",
|
||||
required: true,
|
||||
component: "select",
|
||||
dataSource: "room", // 数据来源API
|
||||
displayField: "roomName",
|
||||
valueField: "id",
|
||||
placeholder: "请选择设备所在房间"
|
||||
},
|
||||
{
|
||||
name: "model",
|
||||
type: "string",
|
||||
label: "型号",
|
||||
required: false,
|
||||
component: "select",
|
||||
dataSource: "static", // 静态数据
|
||||
options: [
|
||||
{ label: "CAIS2-U 1500kg", value: "001" },
|
||||
{ label: "METTLER", value: "3" },
|
||||
{ label: "OHAUS", value: "5" }
|
||||
]
|
||||
},
|
||||
{
|
||||
name: "principalId",
|
||||
type: "number",
|
||||
label: "设备负责人",
|
||||
required: false,
|
||||
component: "select",
|
||||
dataSource: "user", // 用户数据源
|
||||
displayField: "name (userName)", // 显示格式：姓名(用户名)
|
||||
valueField: "id",
|
||||
filterable: true, // 支持搜索
|
||||
placeholder: "请输入姓名搜索设备负责人"
|
||||
}
|
||||
],
|
||||
|
||||
// 数字字段
|
||||
numberFields: [
|
||||
{
|
||||
name: "scalePrecision",
|
||||
type: "number",
|
||||
label: "精度(g)",
|
||||
required: false,
|
||||
component: "input-number",
|
||||
min: 0,
|
||||
precision: 1,
|
||||
placeholder: "请输入设备精度"
|
||||
},
|
||||
{
|
||||
name: "warningLowerLimit",
|
||||
type: "number",
|
||||
label: "报警下限值(g)",
|
||||
required: false,
|
||||
component: "input-number",
|
||||
min: 0,
|
||||
precision: 2,
|
||||
placeholder: "请输入报警下限值"
|
||||
}
|
||||
],
|
||||
|
||||
// 开关字段
|
||||
switchFields: [
|
||||
{
|
||||
name: "enabled",
|
||||
type: "boolean",
|
||||
label: "启用状态",
|
||||
required: false,
|
||||
component: "switch",
|
||||
activeText: "启用",
|
||||
inactiveText: "禁用"
|
||||
},
|
||||
{
|
||||
name: "maintenanceFlag",
|
||||
type: "boolean",
|
||||
label: "维护标记",
|
||||
required: false,
|
||||
component: "switch",
|
||||
activeText: "维护中",
|
||||
inactiveText: "正常"
|
||||
},
|
||||
{
|
||||
name: "isFeedingScale",
|
||||
type: "boolean",
|
||||
label: "是否补料地秤",
|
||||
required: false,
|
||||
component: "switch",
|
||||
activeText: "是",
|
||||
inactiveText: "否"
|
||||
}
|
||||
],
|
||||
|
||||
// 搜索筛选字段
|
||||
filterFields: [
|
||||
{
|
||||
name: "keyWord",
|
||||
type: "string",
|
||||
label: "关键词",
|
||||
component: "input",
|
||||
placeholder: "设备编号、资产编号"
|
||||
},
|
||||
{
|
||||
name: "model",
|
||||
type: "string",
|
||||
label: "设备型号",
|
||||
component: "select",
|
||||
dataSource: "static",
|
||||
placeholder: "请选择设备型号"
|
||||
},
|
||||
{
|
||||
name: "roomID",
|
||||
type: "number",
|
||||
label: "房间",
|
||||
component: "select",
|
||||
dataSource: "room",
|
||||
placeholder: "请选择房间"
|
||||
},
|
||||
{
|
||||
name: "stDate",
|
||||
type: "string",
|
||||
label: "开始时间",
|
||||
component: "datetime-picker",
|
||||
format: "YYYY-MM-DD HH:mm:ss",
|
||||
placeholder: "选择开始时间"
|
||||
},
|
||||
{
|
||||
name: "edDate",
|
||||
type: "string",
|
||||
label: "结束时间",
|
||||
component: "datetime-picker",
|
||||
format: "YYYY-MM-DD HH:mm:ss",
|
||||
placeholder: "选择结束时间"
|
||||
}
|
||||
]
|
||||
interface PageInput {
|
||||
currentPage: number
|
||||
pageSize: number
|
||||
filter: {
|
||||
keyWord?: string
|
||||
startTime?: string
|
||||
endTime?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 权限定义
|
||||
|
||||
2. 表单数据结构
|
||||
```typescript
|
||||
{
|
||||
// 权限配置
|
||||
permissions: [
|
||||
"api:admin:usp-scale:get", // 查询单条
|
||||
"api:admin:usp-scale:get-list", // 查询列表
|
||||
"api:admin:usp-scale:get-page", // 分页查询
|
||||
"api:admin:usp-scale:add", // 新增
|
||||
"api:admin:usp-scale:update", // 更新
|
||||
"api:admin:usp-scale:soft-delete" // 软删除
|
||||
]
|
||||
interface FormData {
|
||||
id?: number
|
||||
deviceNo: string
|
||||
assetNo?: string
|
||||
ip: string
|
||||
port: string
|
||||
serviceName?: string
|
||||
status: boolean
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 表格列配置
|
||||
|
||||
3. API 接口
|
||||
```typescript
|
||||
{
|
||||
// 表格列定义
|
||||
tableColumns: [
|
||||
{
|
||||
prop: "deviceNo",
|
||||
label: "设备编号",
|
||||
minWidth: 120,
|
||||
showOverflowTooltip: true
|
||||
},
|
||||
{
|
||||
prop: "assetNo",
|
||||
label: "资产编号",
|
||||
minWidth: 120,
|
||||
showOverflowTooltip: true
|
||||
},
|
||||
{
|
||||
prop: "model",
|
||||
label: "型号",
|
||||
minWidth: 120,
|
||||
showOverflowTooltip: true,
|
||||
formatter: "getModelName" // 需要转换显示的字段
|
||||
},
|
||||
{
|
||||
prop: "specification",
|
||||
label: "规格",
|
||||
minWidth: 120,
|
||||
showOverflowTooltip: true
|
||||
},
|
||||
{
|
||||
prop: "roomID",
|
||||
label: "房间",
|
||||
width: 120,
|
||||
align: "center",
|
||||
formatter: "getRoomName" // 需要转换显示的字段
|
||||
},
|
||||
{
|
||||
prop: "maintenanceFlag",
|
||||
label: "维护标记",
|
||||
width: 80,
|
||||
align: "center",
|
||||
component: "tag", // 使用标签显示
|
||||
tagConfig: {
|
||||
trueText: "维护中",
|
||||
falseText: "正常",
|
||||
trueType: "warning",
|
||||
falseType: "success"
|
||||
// 列表接口
|
||||
GET /api/admin/device/get-page
|
||||
|
||||
// 详情接口
|
||||
GET /api/admin/device/get
|
||||
|
||||
// 新增接口
|
||||
POST /api/admin/device/add
|
||||
|
||||
// 修改接口
|
||||
PUT /api/admin/device/update
|
||||
|
||||
// 删除接口
|
||||
DELETE /api/admin/device/soft-delete
|
||||
```
|
||||
|
||||
## 页面结构
|
||||
1. 列表页面
|
||||
- 搜索区域：关键词搜索
|
||||
- 操作按钮：新增、查询
|
||||
- 表格区域：基础字段展示
|
||||
- 分页区域：标准分页组件
|
||||
|
||||
2. 编辑页面
|
||||
- 基本信息模块
|
||||
- 网络配置模块
|
||||
- 设备配置模块
|
||||
|
||||
## 样式规范
|
||||
1. 对话框配置
|
||||
```html
|
||||
<el-dialog
|
||||
v-model="state.showDialog"
|
||||
destroy-on-close
|
||||
:title="title"
|
||||
draggable
|
||||
:close-on-click-modal="false"
|
||||
:close-on-press-escape="false"
|
||||
width="900px"
|
||||
>
|
||||
```
|
||||
|
||||
2. 表单布局
|
||||
```html
|
||||
<el-form :model="form" ref="formRef" size="default" label-width="120px">
|
||||
<div class="form-section">
|
||||
<div class="section-title">模块标题</div>
|
||||
<el-row :gutter="25">
|
||||
<el-col :xs="24" :sm="12" :md="12" :lg="12" :xl="12">
|
||||
<el-form-item label="字段名称" prop="fieldName">
|
||||
<el-input v-model="form.fieldName" clearable placeholder="请输入" />
|
||||
</el-form-item>
|
||||
</el-col>
|
||||
</el-row>
|
||||
</div>
|
||||
</el-form>
|
||||
```
|
||||
|
||||
3. 样式定义
|
||||
```scss
|
||||
.form-section {
|
||||
margin-bottom: 24px;
|
||||
&:last-child { margin-bottom: 0; }
|
||||
}
|
||||
},
|
||||
{
|
||||
prop: "isFeedingScale",
|
||||
label: "补料地秤",
|
||||
width: 100,
|
||||
align: "center",
|
||||
component: "tag",
|
||||
tagConfig: {
|
||||
trueText: "是",
|
||||
falseText: "否",
|
||||
trueType: "primary",
|
||||
falseType: "info"
|
||||
|
||||
.section-title {
|
||||
font-size: 16px;
|
||||
font-weight: 600;
|
||||
color: #303133;
|
||||
margin-bottom: 16px;
|
||||
padding-bottom: 8px;
|
||||
border-bottom: 2px solid #f0f0f0;
|
||||
position: relative;
|
||||
&:before {
|
||||
content: '';
|
||||
position: absolute;
|
||||
left: 0;
|
||||
bottom: -2px;
|
||||
width: 40px;
|
||||
height: 2px;
|
||||
background: #409eff;
|
||||
}
|
||||
},
|
||||
{
|
||||
prop: "enabled",
|
||||
label: "状态",
|
||||
width: 80,
|
||||
align: "center",
|
||||
component: "tag",
|
||||
tagConfig: {
|
||||
trueText: "启用",
|
||||
falseText: "禁用",
|
||||
trueType: "success",
|
||||
falseType: "danger"
|
||||
}
|
||||
},
|
||||
{
|
||||
prop: "actions",
|
||||
label: "操作",
|
||||
width: 200,
|
||||
fixed: "right",
|
||||
headerAlign: "center",
|
||||
align: "center",
|
||||
actions: [
|
||||
{
|
||||
text: "编辑",
|
||||
type: "primary",
|
||||
permission: "api:admin:usp-scale:update",
|
||||
handler: "onEdit"
|
||||
},
|
||||
{
|
||||
text: "删除",
|
||||
type: "danger",
|
||||
permission: "api:admin:usp-scale:soft-delete",
|
||||
handler: "onDelete"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 表单布局配置
|
||||
## 开发规范
|
||||
1. 组件命名
|
||||
- 目录：小写字母，用横线分隔
|
||||
- 组件：PascalCase
|
||||
- 组合函数：camelCase
|
||||
|
||||
2. 代码组织
|
||||
```typescript
|
||||
{
|
||||
// 表单配置
|
||||
formConfig: {
|
||||
dialogWidth: "900px",
|
||||
labelWidth: "120px",
|
||||
// 1. 导入声明
|
||||
import { reactive, ref } from 'vue'
|
||||
|
||||
// 表单分组
|
||||
sections: [
|
||||
{
|
||||
title: "基本信息",
|
||||
fields: [
|
||||
"deviceNo",
|
||||
"assetNo",
|
||||
"model",
|
||||
"specification",
|
||||
"roomID",
|
||||
"principalId"
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "技术参数",
|
||||
fields: [
|
||||
"scalePrecision",
|
||||
"warningLowerLimit"
|
||||
]
|
||||
},
|
||||
{
|
||||
title: "设备配置",
|
||||
fields: [
|
||||
"maintenanceFlag",
|
||||
"isFeedingScale",
|
||||
"enabled",
|
||||
"communicationSettings"
|
||||
]
|
||||
// 2. 类型定义
|
||||
interface State {
|
||||
showDialog: boolean
|
||||
form: FormData
|
||||
}
|
||||
],
|
||||
|
||||
// 特殊组件（如独立表单）
|
||||
specialComponents: [
|
||||
{
|
||||
name: "communicationSettings",
|
||||
type: "button",
|
||||
label: "通讯设置",
|
||||
buttonText: "配置通讯参数",
|
||||
icon: "ele-Setting",
|
||||
action: "openSubForm",
|
||||
subFormConfig: {
|
||||
title: "通讯设置",
|
||||
width: "600px",
|
||||
fields: [
|
||||
"subSystemIP",
|
||||
"subSystemIPPort",
|
||||
"deviceIP",
|
||||
"deviceIPPort",
|
||||
"serviceName"
|
||||
// 3. 组件定义
|
||||
const props = defineProps({
|
||||
title: String
|
||||
})
|
||||
|
||||
// 4. 状态定义
|
||||
const state = reactive<State>({
|
||||
showDialog: false,
|
||||
form: {}
|
||||
})
|
||||
|
||||
// 5. 方法定义
|
||||
const handleSubmit = async () => {
|
||||
// 处理逻辑
|
||||
}
|
||||
```
|
||||
|
||||
3. 表单验证
|
||||
```typescript
|
||||
const rules = {
|
||||
fieldName: [
|
||||
{ required: true, message: '请输入', trigger: ['blur', 'change'] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
4. API 调用
|
||||
```typescript
|
||||
const handleSave = async () => {
|
||||
try {
|
||||
const res = await api.save(state.form)
|
||||
if (res.success) {
|
||||
ElMessage.success('保存成功')
|
||||
emit('refresh')
|
||||
state.showDialog = false
|
||||
}
|
||||
]
|
||||
} catch (error) {
|
||||
console.error(error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 完整示例配置
|
||||
|
||||
### 设备管理页面示例
|
||||
|
||||
```json
|
||||
{
|
||||
"pageInfo": {
|
||||
"moduleName": "device",
|
||||
"displayName": "设备管理",
|
||||
"baseRoute": "admin/device",
|
||||
"referenceModule": "admin/room"
|
||||
},
|
||||
"apiConfig": {
|
||||
"baseEndpoint": "/api/admin/device",
|
||||
"endpoints": {
|
||||
"getPage": "get-page",
|
||||
"get": "get",
|
||||
"add": "add",
|
||||
"update": "update",
|
||||
"softDelete": "soft-delete"
|
||||
}
|
||||
},
|
||||
"permissions": [
|
||||
"api:admin:device:get",
|
||||
"api:admin:device:get-page",
|
||||
"api:admin:device:add",
|
||||
"api:admin:device:update",
|
||||
"api:admin:device:soft-delete"
|
||||
],
|
||||
"fields": {
|
||||
"basicFields": [
|
||||
{
|
||||
"name": "deviceName",
|
||||
"type": "string",
|
||||
"label": "设备名称",
|
||||
"required": true,
|
||||
"component": "input",
|
||||
"placeholder": "请输入设备名称"
|
||||
},
|
||||
{
|
||||
"name": "deviceCode",
|
||||
"type": "string",
|
||||
"label": "设备编码",
|
||||
"required": true,
|
||||
"component": "input",
|
||||
"placeholder": "请输入设备编码"
|
||||
}
|
||||
],
|
||||
"selectFields": [
|
||||
{
|
||||
"name": "categoryId",
|
||||
"type": "number",
|
||||
"label": "设备分类",
|
||||
"required": true,
|
||||
"component": "select",
|
||||
"dataSource": "category"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 开发步骤清单
|
||||
|
||||
### 8.1 准备阶段
|
||||
- [ ] 确定页面基本信息（模块名、显示名等）
|
||||
- [ ] 设计数据结构和字段定义
|
||||
- [ ] 确定API接口规范
|
||||
- [ ] 确定权限控制规则
|
||||
- [ ] 分析数据关联关系（如外键引用）
|
||||
|
||||
### 8.2 后端准备
|
||||
- [ ] 创建数据库表结构
|
||||
- [ ] 实现API接口（CRUD操作）
|
||||
- [ ] 配置权限控制
|
||||
- [ ] 数据验证和业务逻辑
|
||||
- [ ] API文档编写
|
||||
|
||||
### 8.3 前端开发
|
||||
|
||||
#### 8.3.1 基础文件创建
|
||||
- [ ] 创建主页面文件 `src/views/admin/{module}/index.vue`
|
||||
- [ ] 创建表单组件 `src/views/admin/{module}/components/{module}-form.vue`
|
||||
- [ ] 创建API文件 `src/api/admin/{Module}Api.ts`
|
||||
- [ ] 更新类型定义 `src/api/admin/data-contracts.ts`
|
||||
|
||||
#### 8.3.2 功能实现
|
||||
- [ ] 实现分页查询功能
|
||||
- [ ] 实现新增功能
|
||||
- [ ] 实现编辑功能
|
||||
- [ ] 实现删除功能
|
||||
- [ ] 添加权限控制
|
||||
|
||||
#### 8.3.3 用户体验优化
|
||||
- [ ] 添加搜索筛选功能
|
||||
- [ ] 优化表单布局（分组、占位符）
|
||||
- [ ] 添加数据验证
|
||||
- [ ] 优化选择框（搜索、分页）
|
||||
- [ ] 添加操作确认提示
|
||||
|
||||
### 8.4 测试阶段
|
||||
- [ ] 功能测试（CRUD操作）
|
||||
- [ ] 权限测试
|
||||
- [ ] 数据验证测试
|
||||
- [ ] 用户体验测试
|
||||
- [ ] 性能测试
|
||||
|
||||
### 8.5 优化阶段
|
||||
- [ ] 代码优化和重构
|
||||
- [ ] 性能优化（懒加载、虚拟滚动等）
|
||||
- [ ] 错误处理优化
|
||||
- [ ] 用户反馈收集和改进
|
||||
|
||||
## 9. 开发最佳实践
|
||||
|
||||
### 9.1 命名规范
|
||||
- **文件命名**：使用小写字母和连字符，如 `device-form.vue`
|
||||
- **变量命名**：使用驼峰命名法，如 `deviceList`
|
||||
- **常量命名**：使用大写字母和下划线，如 `MAX_PAGE_SIZE`
|
||||
|
||||
### 9.2 代码组织
|
||||
- **组件拆分**：将复杂表单拆分为多个子组件
|
||||
- **逻辑复用**：将通用逻辑提取为组合函数
|
||||
- **类型安全**：全面使用 TypeScript 类型定义
|
||||
|
||||
### 9.3 用户体验
|
||||
- **响应式设计**：适配不同屏幕尺寸
|
||||
- **加载状态**：添加适当的加载提示
|
||||
- **错误处理**：友好的错误提示信息
|
||||
- **操作反馈**：成功/失败的操作提示
|
||||
|
||||
### 9.4 性能优化
|
||||
- **懒加载**：大型组件使用异步加载
|
||||
- **虚拟滚动**：大数据量列表使用虚拟滚动
|
||||
- **防抖节流**：搜索等操作使用防抖
|
||||
- **缓存策略**：合理使用数据缓存
|
||||
|
||||
## 10. 常见问题和解决方案
|
||||
|
||||
### 10.1 下拉选择优化
|
||||
**问题**：数据量大时选择困难
|
||||
**解决方案**：
|
||||
- 添加搜索功能（filterable）
|
||||
- 显示更多信息（姓名+用户名）
|
||||
- 支持远程搜索
|
||||
- 添加分页加载
|
||||
|
||||
### 10.2 表单字段分组
|
||||
**问题**：字段太多导致表单复杂
|
||||
**解决方案**：
|
||||
- 按逻辑分组（基本信息、技术参数、配置）
|
||||
- 使用独立表单处理复杂模块
|
||||
- 添加分步表单
|
||||
- 使用折叠面板
|
||||
|
||||
### 10.3 权限控制
|
||||
**问题**：不同用户需要不同权限
|
||||
**解决方案**：
|
||||
- 细化权限粒度
|
||||
- 使用 v-auth 指令控制按钮显示
|
||||
- 在API层面进行权限验证
|
||||
- 提供权限管理界面
|
||||
|
||||
### 10.4 数据关联
|
||||
**问题**：外键数据显示和选择
|
||||
**解决方案**：
|
||||
- 提供格式化函数转换显示
|
||||
- 在表单中使用下拉选择
|
||||
- 支持级联选择
|
||||
- 缓存关联数据
|
||||
|
||||
---
|
||||
|
||||
**注意**：此模板基于 Vue 3 + TypeScript + Element Plus + Pinia 技术栈，使用时请根据实际项目技术栈进行调整。
|
||||
## 注意事项
|
||||
1. 保持与 uspscale 页面风格一致
|
||||
2. 使用响应式布局适配不同屏幕
|
||||
3. 统一表单验证规则和错误提示
|
||||
4. 优化用户交互体验
|
||||
5. 保持代码风格统一
|
||||
6. 注意性能优化
|
||||
7. 遵循 TypeScript 类型规范
|
||||
Loading…
x
Reference in New Issue
Block a user