570 lines
13 KiB
Markdown
570 lines
13 KiB
Markdown
# 页面开发数据模板
|
||
|
||
> 基于 uspscale (秤台设备管理) 页面开发经验总结的完整开发模板
|
||
|
||
## 1. 基本信息配置
|
||
|
||
```typescript
|
||
{
|
||
// 页面基本信息
|
||
pageInfo: {
|
||
moduleName: "uspscale", // 模块名称（小写，用于路径）
|
||
displayName: "秤台设备管理", // 显示名称
|
||
baseRoute: "admin/uspscale", // 路由路径
|
||
referenceModule: "admin/room" // 参考的现有模块（用于复制结构）
|
||
}
|
||
}
|
||
```
|
||
|
||
## 2. API接口定义
|
||
|
||
```typescript
|
||
{
|
||
// API配置
|
||
apiConfig: {
|
||
baseEndpoint: "/api/admin/usp-scale", // API基础路径
|
||
endpoints: {
|
||
getPage: "get-page", // 分页查询
|
||
get: "get", // 单条查询
|
||
add: "add", // 新增
|
||
update: "update", // 更新
|
||
softDelete: "soft-delete" // 软删除（推荐）
|
||
// delete: "delete" // 硬删除（可选）
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 数据字段定义
|
||
|
||
```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: "选择结束时间"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 权限定义
|
||
|
||
```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" // 软删除
|
||
]
|
||
}
|
||
```
|
||
|
||
## 5. 表格列配置
|
||
|
||
```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"
|
||
}
|
||
},
|
||
{
|
||
prop: "isFeedingScale",
|
||
label: "补料地秤",
|
||
width: 100,
|
||
align: "center",
|
||
component: "tag",
|
||
tagConfig: {
|
||
trueText: "是",
|
||
falseText: "否",
|
||
trueType: "primary",
|
||
falseType: "info"
|
||
}
|
||
},
|
||
{
|
||
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. 表单布局配置
|
||
|
||
```typescript
|
||
{
|
||
// 表单配置
|
||
formConfig: {
|
||
dialogWidth: "900px",
|
||
labelWidth: "120px",
|
||
|
||
// 表单分组
|
||
sections: [
|
||
{
|
||
title: "基本信息",
|
||
fields: [
|
||
"deviceNo",
|
||
"assetNo",
|
||
"model",
|
||
"specification",
|
||
"roomID",
|
||
"principalId"
|
||
]
|
||
},
|
||
{
|
||
title: "技术参数",
|
||
fields: [
|
||
"scalePrecision",
|
||
"warningLowerLimit"
|
||
]
|
||
},
|
||
{
|
||
title: "设备配置",
|
||
fields: [
|
||
"maintenanceFlag",
|
||
"isFeedingScale",
|
||
"enabled",
|
||
"communicationSettings"
|
||
]
|
||
}
|
||
],
|
||
|
||
// 特殊组件（如独立表单）
|
||
specialComponents: [
|
||
{
|
||
name: "communicationSettings",
|
||
type: "button",
|
||
label: "通讯设置",
|
||
buttonText: "配置通讯参数",
|
||
icon: "ele-Setting",
|
||
action: "openSubForm",
|
||
subFormConfig: {
|
||
title: "通讯设置",
|
||
width: "600px",
|
||
fields: [
|
||
"subSystemIP",
|
||
"subSystemIPPort",
|
||
"deviceIP",
|
||
"deviceIPPort",
|
||
"serviceName"
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 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 技术栈，使用时请根据实际项目技术栈进行调整。 |