From 1280c11bbce3f19c33c6297bb3c523c3ab1ae343 Mon Sep 17 00:00:00 2001 From: Asoka Date: Mon, 9 Jun 2025 14:13:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E9=A1=B5=E9=9D=A2?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=95=B0=E6=8D=AE=E6=A8=A1=E6=9D=BF=EF=BC=8C?= =?UTF-8?q?=E8=A1=A5=E5=85=85=E8=B7=AF=E7=94=B1=E5=8F=82=E6=95=B0=E5=92=8C?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E7=BB=93=E6=9E=84=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 页面开发数据模板.md | 745 ++++++++++++-------------------------------- 1 file changed, 191 insertions(+), 554 deletions(-) diff --git a/页面开发数据模板.md b/页面开发数据模板.md index 8865672..889fb6d 100644 --- a/页面开发数据模板.md +++ b/页面开发数据模板.md @@ -1,570 +1,207 @@ -# 页面开发数据模板 +# 页面开发指南 -> 基于 uspscale (秤台设备管理) 页面开发经验总结的完整开发模板 +## 路由配置 +1. 路由参数 + ```typescript + // 路由定义 + { + path: '/admin/device', + name: 'admin/device', + component: () => import('/@/views/admin/device/index.vue'), + meta: { + title: '设备管理', + icon: 'ele-Setting', + roles: ['admin'] + } + } + ``` -## 1. 基本信息配置 +2. 权限控制 + ```typescript + // 按钮权限 + v-auth="'api:admin:device:add'" // 新增权限 + v-auth="'api:admin:device:update'" // 修改权限 + v-auth="'api:admin:device:soft-delete'" // 删除权限 + ``` -```typescript -{ - // 页面基本信息 - pageInfo: { - moduleName: "uspscale", // 模块名称（小写，用于路径） - displayName: "秤台设备管理", // 显示名称 - baseRoute: "admin/uspscale", // 路由路径 - referenceModule: "admin/room" // 参考的现有模块（用于复制结构） - } -} -``` +## 数据结构 +1. 列表查询参数 + ```typescript + interface PageInput { + currentPage: number + pageSize: number + filter: { + keyWord?: string + startTime?: string + endTime?: string + } + } + ``` -## 2. API接口定义 +2. 表单数据结构 + ```typescript + interface FormData { + id?: number + deviceNo: string + assetNo?: string + ip: string + port: string + serviceName?: string + status: boolean + } + ``` -```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. API 接口 + ```typescript + // 列表接口 + 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 + ``` -## 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: "选择结束时间" - } - ] - } -} -``` +2. 编辑页面 + - 基本信息模块 + - 网络配置模块 + - 设备配置模块 -## 4. 权限定义 +## 样式规范 +1. 对话框配置 + ```html + + ``` -```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" // 软删除 - ] -} -``` +2. 表单布局 + ```html + +
+
模块标题
+ + + + + + + +
+ + ``` -## 5. 表格列配置 +3. 样式定义 + ```scss + .form-section { + margin-bottom: 24px; + &:last-child { margin-bottom: 0; } + } -```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" - } - ] - } - ] -} -``` + .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; + } + } + ``` -## 6. 表单布局配置 +## 开发规范 +1. 组件命名 + - 目录：小写字母，用横线分隔 + - 组件：PascalCase + - 组合函数：camelCase -```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" - ] - } - } - ] - } -} -``` +2. 代码组织 + ```typescript + // 1. 导入声明 + import { reactive, ref } from 'vue' + + // 2. 类型定义 + interface State { + showDialog: boolean + form: FormData + } + + // 3. 组件定义 + const props = defineProps({ + title: String + }) + + // 4. 状态定义 + const state = reactive({ + showDialog: false, + form: {} + }) + + // 5. 方法定义 + const handleSubmit = async () => { + // 处理逻辑 + } + ``` -## 7. 完整示例配置 +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) + } + } + ``` -```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 技术栈，使用时请根据实际项目技术栈进行调整。 \ No newline at end of file +## 注意事项 +1. 保持与 uspscale 页面风格一致 +2. 使用响应式布局适配不同屏幕 +3. 统一表单验证规则和错误提示 +4. 优化用户交互体验 +5. 保持代码风格统一 +6. 注意性能优化 +7. 遵循 TypeScript 类型规范 \ No newline at end of file