Appearance
表单组件开发
**本文引用的文件** - [baseForm.vue](file://app/devicemate-app/components/dd-form/baseForm.vue) - [dictMixins.js](file://app/devicemate-app/utils/dictMixins.js) - [request.js](file://app/devicemate-app/config/request.js) - [form.vue](file://app/devicemate-app/pages/user/form.vue) - [baseUrl.js](file://app/devicemate-app/config/baseUrl.js)目录
简介
本指南围绕 DeviceMate 表单组件（dd-form）进行系统性解析，重点覆盖以下方面：
- 基础表单组件的设计与实现：动态字段生成、数据绑定、交互控制与事件流
- 字典与远程数据联动：下拉选择、字典加载与本地缓存策略
- 表单校验与禁用态控制：必填项检测、上传进度阻塞、按钮可用性联动
- 数据收集、格式化与提交：模型拼装、文件列表合并、异步上传与提交
- 实战示例与扩展开发：字段类型、验证规则、样式定制与最佳实践
项目结构
- 组件层：dd-form/baseForm.vue 提供统一表单容器与交互行为
- 工具层：dictMixins.js 提供字典加载与名称映射能力
- 请求层：config/request.js 封装统一请求与鉴权头注入
- 页面示例：pages/user/form.vue 展示如何配置与使用表单组件
- 基础配置：baseUrl.js 提供上传与接口域名
图表来源
章节来源
核心组件
组件职责
- 动态渲染表单字段：根据配置 props 逐项生成输入控件
- 数据绑定与变更：双向绑定 model，实时更新字段值
- 交互控制：下拉选择、日期/时间选择、图片上传、审核弹窗
- 禁用态与按钮联动：基于必填与上传状态动态控制提交按钮
- 事件发射：提交、选择变更、禁用状态变化、审核操作
关键特性
- 字典联动：支持静态 list、远程字典编码 dictCode、自定义函数
- 文件上传：多文件上传、上传进度计数、上传完成前禁止提交
- 审核流程：弹窗选择“通过/不通过”，可选填写意见
- 只读模式：根据 formConfig.type 切换只读或编辑态
章节来源
架构总览
下图展示从页面到组件再到服务的整体调用链路。
图表来源
详细组件分析
组件类图
图表来源
章节来源
字段类型与动态生成
- 支持类型
- 普通输入框：normal-input（文本/数字/文本域）
- 下拉选择：select-input（支持静态 list、远程字典 dictCode、自定义函数）
- 日期选择：calendar-input（日期/范围等）
- 时间选择：time-input（可配置年月日/时分秒）
- 图片上传：upload-input（多文件、带进度、只读态显示图片/文件列表）
- 渲染逻辑
- 通过 props 数组逐项渲染 u-form-item，并根据 type 切换对应控件
- 必填标记与占位符逻辑：未赋值时显示占位提示
- 只读态：根据 formConfig.type 切换是否可编辑
章节来源
数据绑定与事件流
- 输入绑定
- 普通输入：inputChange 同步更新 model[prop]
- 选择/日期/时间：选择确认后写回 model 并触发禁用态检查
- 禁用态控制
- checkDisabled：若存在未完成上传或必填字段为空，则禁用提交按钮
- 通过 emit('disabled', flag) 通知父级按钮状态
图表来源
章节来源
字典与远程数据联动
- 优先级
- 若 item.list 存在且非空：直接使用本地 list
- 若 item.customFunc 存在：调用自定义函数获取数据
- 否则按 dictCode 远程拉取字典并缓存到 item.list
- 名称映射
- getDictName：根据 dictValue 在 list 中匹配 name
图表来源
章节来源
上传与文件处理
- 上传入口
- beforeUpload：并发上传多个文件，维护 uploadSuccessCount 计数
- 成功后将服务端返回的文件对象写入 fileList
- 只读态展示
- getImg：筛选图片并以 HTML 形式渲染
- getFiles：筛选非图片文件并展示下载链接
- 提交拦截
- submit：若仍有上传任务未完成则提示并阻止提交
图表来源
章节来源
审核流程
- 弹窗选择：通过/不通过
- 不通过时可选填写意见
- confirmModal：将选择与意见通过事件传递给父级
章节来源
页面使用示例
- 页面 form.vue 通过传入 formConfig 定义字段、模型与默认值
- 支持多种字段类型：普通输入、数字输入、时间选择、文本域、上传
- 提交时接收 model，结合 fileList 进行业务提交
章节来源
依赖关系分析
- 组件对工具与配置的依赖
- 字典：通过 dictMixins.js 的 getDict 与 getDictName
- 请求：通过 request.js 的 get/post 注入鉴权头
- 上传：通过 baseUrl.js 拼接上传地址
- 组件内部耦合
- 与 uView 组件组合使用（u-form、u-form-item、u-input、u-select、u-calendar、u-picker、u-upload、u-modal、u-button）
- 与 uni API 交互（uni.uploadFile、uni.downloadFile、uni.showToast、uni.showLoading）
图表来源
章节来源
性能考量
- 防抖与节流
- 输入变更采用防抖策略，降低频繁计算与渲染压力
- 上传并发与计数
- 多文件上传并发执行，使用计数器确保全部完成后才允许提交
- 懒加载与缓存
- 字典按需加载并缓存到字段配置中，避免重复请求
- 渲染优化
- 条件渲染与只读态切换，减少不必要的 DOM 更新
章节来源
故障排查指南
- 上传未完成即提交
- 现象：点击提交提示“还有图片在上传中”
- 排查：确认 uploadSuccessCount 是否归零；检查 beforeUpload 的 complete 回调是否执行
- 必填字段导致按钮不可用
- 现象：按钮始终禁用
- 排查：检查 formConfig.props 中 required 字段是否赋值；确认 checkDisabled 逻辑
- 下拉字典不显示
- 现象：选择框空白
- 排查：确认 dictCode 是否正确；若使用自定义函数，确认返回值结构；检查 getDict 返回结果
- 上传地址或鉴权问题
- 现象：上传失败或 401
- 排查：确认 baseUrl.js 地址；检查 request.js 注入的 Authorization 是否有效
章节来源
结论
dd-form 基础表单组件通过清晰的配置驱动与完善的交互控制，实现了字段动态生成、字典联动、文件上传与禁用态联动等关键能力。结合页面示例与工具层封装，开发者可以快速搭建复杂表单场景，并通过扩展字段类型、自定义校验与样式定制进一步提升用户体验与开发效率。
附录
配置项与使用要点
- formConfig
- type：表单类型（如 apply/approval 等），决定只读与底部按钮显示
- props：字段数组，每项包含 label、prop、type、required、align、position、inputType、maxlength、timeParams、calendarMode、customFunc、dictCode、list 等
- model：字段值模型，初始值在此定义
- labelWidth、maxDate：标签宽度与日期最大值
- 事件
- submit：提交时触发，返回 model 与 fileList
- baseForm-selectChange：选择变更时触发，返回 prop 与选中项
- change：表单值或文件列表变化时触发
- disabled：禁用态变化时触发
- approval：审核弹窗确认时触发，返回选择与意见
章节来源