DM-ROW 接口文档

Appearance

移动端组件开发 ​

**本文引用的文件** - [baseForm.vue](file://app/devicemate-app/components/dd-form/baseForm.vue) - [mescroll-uni.vue](file://app/devicemate-app/components/mescroll-uni/mescroll-uni.vue) - [mescroll-uni.js](file://app/devicemate-app/components/mescroll-uni/mescroll-uni.js) - [mescroll-uni-option.js](file://app/devicemate-app/components/mescroll-uni/mescroll-uni-option.js) - [mescroll-mixins.js](file://app/devicemate-app/components/mescroll-uni/mescroll-mixins.js) - [mescroll-uni.css](file://app/devicemate-app/components/mescroll-uni/mescroll-uni.css) - [mescroll-down.css](file://app/devicemate-app/components/mescroll-uni/components/mescroll-down.css) - [mescroll-up.css](file://app/devicemate-app/components/mescroll-uni/components/mescroll-up.css) - [mixins.js](file://app/devicemate-app/components/mescroll-uni/wxs/mixins.js) - [renderjs.js](file://app/devicemate-app/components/mescroll-uni/wxs/renderjs.js) - [dictMixins.js](file://app/devicemate-app/utils/dictMixins.js) - [index.vue](file://app/devicemate-app/pages/equipment/index.vue)

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

引言 ​

本指南面向 DeviceMate 移动端组件开发，聚焦两类关键组件：dd-form 表单组件与 mescroll-uni 滚动组件。文档从设计原则、开发模式、功能特性、配置选项、使用方法、集成流程、性能优化到常见问题，提供系统化、可落地的实践指导，帮助开发者高效构建高质量的移动端组件。

项目结构 ​

  • 组件集中于 app/devicemate-app/components 下，按功能域划分：
    • dd-form：基础表单组件，支持多种输入类型、字典联动、上传、校验与禁用态控制。
    • mescroll-uni：高性能滚动容器，内置下拉刷新、上拉加载、空数据处理、回到顶部等能力，支持小程序、App、H5 多端差异化实现（wxs、renderjs）。
  • 工具与混入：
    • dictMixins：统一字典获取与名称解析。
    • mescroll-mixins：页面级生命周期与回调混入，简化下拉/上拉接入。

图表来源

章节来源

核心组件 ​

  • dd-form 基础表单
    • 支持输入框、下拉选择、日期/时间选择、图片上传、禁用态展示、必填校验、按钮状态联动。
    • 内置上传头像、文件列表展示与下载。
    • 通过 props 接收配置，emit 事件驱动父组件交互。
  • mescroll-uni 滚动容器
    • 统一下拉刷新、上拉加载、空布局、回到顶部、安全区适配、多端差异处理（wxs/renderjs）。
    • 通过 down/up 配置项灵活控制行为；通过 init/call 回调与父组件通信。

章节来源

架构总览 ​

  • 组件职责分离：表单负责数据采集与校验，滚动容器负责内容承载与交互。
  • 事件驱动：表单通过 submit/approval/change 等事件与父组件协作；滚动容器通过 down/up/emptyclick/topclick 等事件与父组件协作。
  • 多端适配：mescroll-uni 通过 wxs 与 renderjs 实现高性能手势与滚动控制，保证在小程序、App、H5 的一致性体验。

图表来源

详细组件分析 ​

dd-form 基础表单组件 ​

  • 设计原则
    • 配置驱动：通过 formConfig.props 定义字段清单，统一渲染与校验。
    • 类型丰富：支持普通输入、下拉、日期、时间、图片上传等。
    • 禁用态友好：根据类型切换编辑态/只读态，避免误操作。
    • 事件解耦：通过 change/disable 等事件通知父组件状态变化。
  • 关键实现要点
    • 字典联动：通过 dictMixins.getDict 获取字典列表，映射 label/value。
    • 上传集成：beforeUpload 中逐文件上传，维护 fileList 并与模型同步。
    • 禁用控制：checkDisabled 综合必填与上传进行按钮可用性判断。
    • 文件下载：downloadFile 使用 uni.downloadFile/uni.saveFile/uni.openDocument 打开文档。
  • 配置项与使用
    • formConfig.model：表单数据模型。
    • formConfig.props：字段数组，每项包含 type、prop、label、required、dictCode、customFunc、list、align、inputType、maxCount 等。
    • formConfig.type：表单类型（如 apply/approval），决定按钮与禁用态。
    • emit 事件：submit、change、disabled、approval。
  • 样式与布局
    • 通过 labelStyle、label-position 控制标签样式与位置。
    • 输入区域统一右对齐与间距，图片上传采用 u-parse 渲染预览。

图表来源

章节来源

mescroll-uni 滚动组件 ​

  • 设计原则
    • 低耦合：通过 down/up 配置与事件回调解耦业务。
    • 多端一致：通过 wxs/renderjs 屏蔽平台差异，统一手势与滚动行为。
    • 可扩展：支持空布局、回到顶部、安全区、固定定位等。
  • 关键实现要点
    • 核心逻辑：mescroll-uni.js 管理下拉刷新与上拉加载状态机，提供 endSuccess/endErr/resetUpScroll 等 API。
    • 全局配置：mescroll-uni-option.js 提供常用文案与尺寸默认值。
    • 多端桥接：wxs/mixins.js 与 renderjs.js 在不同平台桥接逻辑层与视图层。
    • 页面混入：mescroll-mixins.js 提供 onPullDownRefresh/onReachBottom/onPageScroll 生命周期适配。
  • 配置项与使用
    • down：下拉刷新配置（offset、text*、beforeEndDelay、native 等）。
    • up：上拉加载配置（offset、text*、toTop、empty、noMoreSize 等）。
    • props：top/bottom/safearea/fixed/height 等布局属性。
    • emit：down/up/emptyclick/topclick/init 等事件。
  • 样式与布局
    • mescroll-uni.css 定义容器定位与溢出；mescroll-down.css/mescroll-up.css 定义下拉/上拉指示样式。

图表来源

章节来源

依赖关系分析 ​

  • 组件内聚与耦合
    • dd-form 与 uView 组件强耦合，依赖 u-form/u-input/u-upload 等；通过 dictMixins 解耦字典服务。
    • mescroll-uni 与 mescroll-uni.js 强耦合，与 wxs/renderjs 形成跨层桥接，页面通过 mescroll-mixins.js 间接接入。
  • 外部依赖
    • uni.request/uni.uploadFile/uni.downloadFile/uni.saveFile/uni.openDocument 等 uni API。
    • 第三方样式库（uView）。
  • 潜在循环依赖
    • 组件间无直接循环依赖；若业务页面引入多个 mescroll 实例，需注意命名空间与事件隔离。

图表来源

章节来源

性能考虑 ​

  • 表单组件
    • 防抖：inputChange 使用防抖减少频繁校验与渲染。
    • 上传并发：beforeUpload 逐文件上传并维护 uploadSuccessCount，避免阻塞提交。
    • 条件渲染：禁用态与只读态通过计算属性与 v-if/v-show 控制，降低 DOM 数量。
  • 滚动组件
    • wxs/renderjs：在高帧率场景下减少 JS 与视图层通信成本，提升滚动流畅度。
    • 状态机：mescroll-uni.js 严格管理下拉/上拉状态，避免重复触发与无效渲染。
    • 动画与过渡：通过 setScrollTop 与 getStep 实现平滑滚动，避免卡顿。
  • 通用建议
    • 合理拆分组件，避免单文件过大。
    • 使用 v-show/v-if 控制复杂子树渲染。
    • 对高频事件（如滚动）使用节流/防抖。

[本节为通用指导，无需列出章节来源]

故障排查指南 ​

  • 表单上传失败或未完成
    • 现象：提交按钮禁用或提示“仍有图片在上传”。
    • 排查：确认 beforeUpload 中 uploadSuccessCount 是否正确累加/递减；检查接口返回与 fileList 同步。
    • 参考路径：baseForm.vue:360-394、baseForm.vue:396-404
  • 选择器字典为空
    • 现象：下拉列表未显示或为空。
    • 排查：确认 dictCode 正确；检查 dictMixins.getDict 返回；确认 item.list 是否被缓存。
    • 参考路径：baseForm.vue:275-310、dictMixins.js:9-20
  • 滚动容器高度异常
  • 多端手势冲突
    • 现象：下拉刷新与侧滑返回冲突或 bounce 影响体验。
    • 排查：renderjs 已在顶部禁止 bounce；确认 optDown/native 配置与平台限制。
    • 参考路径：renderjs.js:13-46、mescroll-uni.js:41-80

章节来源

结论 ​

  • dd-form 与 mescroll-uni 分别覆盖“数据采集”和“内容承载”的核心场景，具备良好的可配置性与可扩展性。
  • 通过事件驱动与多端桥接，两类组件在多端环境下保持一致的交互体验。
  • 建议在业务中遵循“配置驱动、事件解耦、状态机管理”的开发范式，结合本指南的性能与排障建议，持续优化组件质量与用户体验。

[本节为总结性内容，无需列出章节来源]

附录 ​

组件开发标准流程 ​

  • 表单组件
    • 明确字段类型与校验规则，统一在 props 中声明。
    • 使用 dictMixins 管理字典联动，避免重复请求。
    • 上传文件时维护 fileList 与模型同步，提交前校验上传状态。
  • 滚动组件
    • 在页面中引入 mescroll-mixins.js，注册生命周期回调。
    • 通过 down/up 配置控制行为；在回调中调用 endSuccess/endErr/resetUpScroll。
    • 注意多端差异，必要时通过 wxs/renderjs 优化性能。

章节来源

代码规范与最佳实践 ​

  • 命名规范
    • 组件文件使用 kebab-case，如 mescroll-uni.vue；工具函数使用 camelCase，如 getDict。
  • 事件命名
    • 统一使用语义化事件名，如 submit/change/disabled/approval/down/up/emptyclick/topclick。
  • 数据绑定
    • 表单使用 v-model 或显式赋值；滚动容器通过 mescroll 实例方法控制滚动与状态。
  • 样式组织
    • 将公共样式抽离至 mescroll-uni.css，局部样式使用 scoped，避免污染。

章节来源

实际使用示例（路径指引） ​

  • dd-form 示例页面（设备首页）
    • 页面路径：index.vue:1-287
    • 说明：该页面为入口页，展示菜单与统计信息，表单组件可在对应模块页面中使用。
  • mescroll-uni 示例页面（设备列表页）
    • 页面路径：equipment.vue:1-200
    • 说明：引入 mescroll-mixins.js，配置 down/up 回调，实现列表分页加载与空数据处理。

章节来源