2025-06-06 11:35:06 +08:00

13 KiB

Raw Blame History

页面开发数据模板

基于 uspscale (秤台设备管理) 页面开发经验总结的完整开发模板

1. 基本信息配置

{
  // 页面基本信息
  pageInfo: {
    moduleName: "uspscale",           // 模块名称（小写，用于路径）
    displayName: "秤台设备管理",      // 显示名称
    baseRoute: "admin/uspscale",      // 路由路径
    referenceModule: "admin/room"     // 参考的现有模块（用于复制结构）
  }
}

2. API接口定义

{
  // API配置
  apiConfig: {
    baseEndpoint: "/api/admin/usp-scale",  // API基础路径
    endpoints: {
      getPage: "get-page",      // 分页查询
      get: "get",               // 单条查询  
      add: "add",               // 新增
      update: "update",         // 更新
      softDelete: "soft-delete" // 软删除（推荐）
      // delete: "delete"       // 硬删除（可选）
    }
  }
}

3. 数据字段定义

{
  // 字段定义
  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. 权限定义

{
  // 权限配置
  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. 表格列配置

{
  // 表格列定义
  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. 表单布局配置

{
  // 表单配置
  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. 完整示例配置

设备管理页面示例

{
  "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 技术栈，使用时请根据实际项目技术栈进行调整。

13 KiB Raw Blame History Unescape Escape

页面开发数据模板

1. 基本信息配置

2. API接口定义

3. 数据字段定义

4. 权限定义

5. 表格列配置

6. 表单布局配置

7. 完整示例配置

设备管理页面示例

8. 开发步骤清单

8.1 准备阶段

8.2 后端准备

8.3 前端开发

8.3.1 基础文件创建

8.3.2 功能实现

8.3.3 用户体验优化

8.4 测试阶段

8.5 优化阶段

9. 开发最佳实践

9.1 命名规范

9.2 代码组织

9.3 用户体验

9.4 性能优化

10. 常见问题和解决方案

10.1 下拉选择优化

10.2 表单字段分组

10.3 权限控制

10.4 数据关联

13 KiB

Raw Blame History