DM-ROW 接口文档

Appearance

跨平台兼容性处理 ​

**本文引用的文件** - [manifest.json](file://app/devicemate-app/manifest.json) - [pages.json](file://app/devicemate-app/pages.json) - [main.js](file://app/devicemate-app/main.js) - [App.vue](file://app/devicemate-app/App.vue) - [uni.scss](file://app/devicemate-app/uni.scss) - [config/request.js](file://app/devicemate-app/config/request.js) - [utils/common.js](file://app/devicemate-app/utils/common.js) - [utils/userMixins.js](file://app/devicemate-app/utils/userMixins.js) - [utils/localstorage.js](file://app/devicemate-app/utils/localstorage.js) - [lib/nfc.js](file://app/devicemate-app/lib/nfc.js) - [directive/index.js](file://app/devicemate-app/directive/index.js) - [locale/index.js](file://app/devicemate-app/locale/index.js) - [static/iconfont/iconfont.json](file://app/devicemate-app/static/iconfont/iconfont.json)

目录 ​

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

简介 ​

本指南面向DeviceMate跨平台应用的开发者，围绕UniApp多端编译与平台差异，系统梳理iOS、Android、H5、小程序等平台的特性差异与适配策略；详解条件编译与平台检测、平台特定API使用、权限配置与功能限制；覆盖样式兼容、字体图标、图片资源与网络请求差异；并提供设备信息获取、系统版本判断、动态适配的实现方案与最佳实践。文中所有技术要点均基于仓库现有源码进行提炼与总结。

项目结构 ​

DeviceMate前端采用UniApp工程，核心入口与页面配置集中在app/devicemate-app目录，关键文件包括应用清单、页面路由、主入口、国际化、网络请求封装、本地存储、指令与平台特性模块等。

图表来源

章节来源

核心组件 ​

  • 应用入口与生命周期：在App.vue中处理启动、登录后处理、消息红点、工厂加载与权限跳转等。
  • 主入口与全局注册：main.js负责UI框架、全局组件、HTTP、提示、本地存储、国际化与登录判定等。
  • 页面与导航：pages.json集中声明页面、导航栏、tabBar、平台专属样式（如app-plus的titleNView按钮）。
  • 平台配置与权限：manifest.json定义5+App模块、Android/iOS打包配置、SDK配置、权限列表等。
  • 网络层：config/request.js统一封装GET/POST、超时、鉴权头、国际化区域、时区、错误处理与401处理。
  • 工具与混入：utils/common.js提供升级检测、消息红点；utils/userMixins.js提供权限跳转、菜单过滤与分组；utils/localstorage.js提供本地存储封装。
  • 平台特性：lib/nfc.js封装Android NFC读写流程；directive/index.js提供权限指令；locale/index.js提供国际化。
  • 样式与图标：uni.scss提供主题变量；static/iconfont/iconfont.json提供图标元数据。

章节来源

架构总览 ​

下图展示从应用启动到页面渲染、网络请求与平台特性调用的关键交互：

图表来源

详细组件分析 ​

应用入口与生命周期（App.vue） ​

  • 启动阶段清理临时状态、执行升级检查、根据权限跳转至对应tabBar首页。
  • onShow阶段处理外部scheme回调，解析token与用户信息，保存至本地并加载默认工厂，随后再次执行权限跳转。
  • 使用plus.runtime.arguments接收外部参数，结合本地存储afterLogin避免重复处理。

章节来源

主入口与全局注册（main.js） ​

  • 引入uView UI并注册全局组件（表单、滚动容器等）。
  • 注入全局HTTP、提示、本地存储、登录判定方法至Vue原型。
  • 设置App.mpType为'app'，确保在5+App环境下运行。

章节来源

页面与导航（pages.json） ​

  • easycom自动映射uView组件，简化引用。
  • tabBar配置包含四个页面，图标来自static/tarIcon目录。
  • 多数模块页面在style.app-plus下配置titleNView按钮，使用iconfont字体图标资源，实现平台差异化标题栏按钮。
  • 导航栏标题文本支持国际化占位符，便于多语言切换。

章节来源

平台配置与权限（manifest.json） ​

  • app-plus节点：
    • splashscreen配置、useragent、模块（Speech/Camera/Record）、SSL忽略校验。
    • android权限列表覆盖网络、相机、振动、NFC、存储等。
    • iOS打包配置与SDK（百度语音）配置。
    • 应用图标与scheme。
  • mp-weixin/mp-alipay/mp-baidu/mp-toutiao节点开启usingComponents。
  • 全局vueVersion为2，locale为en。

章节来源

网络请求封装（config/request.js） ​

  • 统一loading、国际化区域头、时区头、鉴权头（Authorization）。
  • 超时时间120秒，网络状态监听提示无网。
  • 成功/失败统一处理，401统一跳转登录。
  • 支持filter开关以绕过统一结果包装的接口。

章节来源

工具与混入（utils/common.js、utils/userMixins.js、utils/localstorage.js） ​

  • common.js：升级检测（plus.runtime.getProperty读取版本号）、消息红点控制。
  • userMixins.js：权限跳转、菜单过滤与分组、工厂加载、菜单点击处理。
  • localstorage.js：封装set/get/remove/clear，统一JSON序列化/反序列化。

章节来源

平台特性（lib/nfc.js） ​

  • 仅在Android 5+App环境下生效，通过plus.android导入原生类。
  • 监听NFC状态、前台调度系统、读写流程；对无NFC或未启用场景给出提示。
  • 读取NDEF消息payload并转换为字符串，写入前校验可写与容量。

章节来源

权限指令与国际化（directive/index.js、locale/index.js） ​

  • 权限指令v-auth：根据菜单权限隐藏/显示元素。
  • 国际化：根据系统语言缓存选择en_US或zh-Hans，注入全局_i18n。

章节来源

样式与图标（uni.scss、static/iconfont/iconfont.json） ​

  • uni.scss提供颜色、尺寸、边距、透明度等变量，统一uView主题。
  • iconfont.json定义字体图标集，配合pages.json中titleNView的fontSrc使用。

章节来源

依赖关系分析 ​

  • App.vue依赖main.js注入的全局方法与工具；依赖utils/localstorage.js读取用户信息；依赖config/request.js发起HTTP请求；依赖utils/userMixins.js进行权限跳转；在Android 5+App环境依赖lib/nfc.js。
  • main.js依赖pages.json中的easycom映射与全局组件注册；依赖manifest.json中的平台配置；依赖locale/index.js进行国际化。
  • config/request.js依赖utils/localstorage.js读取用户token；依赖uni.request进行网络请求；依赖locale/index.js获取区域信息。
  • pages.json依赖static资源（图标、字体）与manifest.json平台配置。

图表来源

性能考量 ​

  • 网络请求：统一超时与loading，避免并发过多导致UI卡顿；按需展示提示，减少频繁toast。
  • 图标与资源：iconfont复用字体图标，减少HTTP请求；静态资源集中管理，避免重复加载。
  • 权限与菜单：在进入页面前完成权限跳转与可见性设置，减少无效渲染。
  • NFC：仅在Android 5+App环境启用，避免在H5/小程序触发无意义逻辑。

故障排查指南 ​

  • 升级检测与版本比较

    • 现象：未弹出更新或提示已是最新。
    • 排查：确认服务端返回latestVersionCode大于本地plus.runtime.getProperty读取的versionCode；检查网络连通与sslVerify配置。
    • 参考路径：utils/common.js:35-60，manifest.json:86-88

  • 消息红点显示异常

    • 现象：tabBar红点不显示或不消失。
    • 排查：确认消息查询接口返回msgStatus字段；检查uni.showTabBarRedDot/uni.hideTabBarRedDot调用时机。
    • 参考路径：utils/common.js:13-33

  • 权限指令无效

  • NFC不可用

    • 现象：提示设备不支持或未启用。
    • 排查：确认Android设备支持NFC且已启用；检查manifest.json权限与5+App模块配置；验证前台调度系统是否正确启用。
    • 参考路径：lib/nfc.js:37-104，manifest.json:24-30

  • 国际化显示异常

    • 现象：界面语言未按系统语言切换。
    • 排查：确认locale缓存键与系统语言一致；检查messages中是否存在对应语言包。
    • 参考路径：locale/index.js:10-24

  • 页面标题栏按钮不显示

结论 ​

DeviceMate通过统一的入口与配置、完善的网络层封装、严格的权限与国际化机制，以及针对Android 5+App的NFC能力，实现了在iOS、Android、H5与小程序等多平台上的稳定运行。遵循本文的适配策略与最佳实践，可有效规避平台差异带来的兼容性问题，提升用户体验与开发效率。

附录 ​

平台差异与适配策略速览 ​

  • iOS

    • 特性：系统导航栏、tabBar样式与手势；不支持NFC。
    • 适配：避免在iOS使用NFC相关逻辑；注意iOS刘海屏与安全区域；使用pages.json的全局样式统一导航栏背景与文字颜色。
    • 参考路径：pages.json:532-537

  • Android（5+App）

    • 特性：支持NFC、前台调度系统、原生模块；可配置splashscreen与useragent。
    • 适配：在Android平台启用NFC监听与读写；配置必要权限；注意plus.runtime与plus.android API的兼容性。
    • 参考路径：lib/nfc.js:37-104，manifest.json:10-88

  • H5

    • 特性：浏览器环境，不支持原生模块；可使用uni.request与本地存储。
    • 适配：避免调用5+App与NFC API；统一网络请求与国际化；注意H5路由与历史模式。
    • 参考路径：config/request.js:42-128

  • 小程序（微信/支付宝/百度/头条）

    • 特性：使用usingComponents；限制原生模块与部分API。
    • 适配：启用usingComponents；避免使用plus与NFC；统一使用uni.xxx API；注意小程序端的网络与权限限制。
    • 参考路径：manifest.json:93-108

条件编译与平台检测 ​

  • 平台检测：使用uni.getSystemInfoSync或plus.runtime属性获取平台信息；在Android 5+App环境启用NFC。
  • 条件编译：在需要的地方通过平台判断分支处理，避免在非目标平台执行无效逻辑。
  • 参考路径：App.vue:18-61，lib/nfc.js:41-104

样式兼容与图标适配 ​

网络请求差异 ​

  • 统一处理：config/request.js封装GET/POST、鉴权头、国际化区域与时区；401统一跳转登录。
  • 平台差异：H5与小程序端的uni.request行为略有差异，需关注超时与fail回调。
  • 参考路径：config/request.js:131-162