# 页面开发数据模板 > 基于 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 技术栈,使用时请根据实际项目技术栈进行调整。