更新记录

v1.0.0（2026-05-09）

新版本

平台兼容性

uni-app(3.96)

其他

op-custom-scankit（UTS）：自定义华为扫码插件使用说明

本文面向 从 DCloud 插件市场安装或使用本插件的开发者，说明能力范围、环境要求、manifest/华为工程注意事项、权限说明、API 与回调约定。项目内演示源码见同目录 index1.vue（扫码结果填入输入框示例）。

插件目录：uni_modules/op-custom-scankit/。

一、插件能力简介

基于 华为 HMS ScanKit（RemoteView）封装的 全屏自定义扫码页，内置能力包括：

• 摄像头实时扫码（一维码 / 二维码等，与 HMS 支持的格式一致）。
• 中部文案提示（可配置 hintText）。
• 扫描线动画（WebView 内嵌 SVG，不依赖额外静态资源 URL）。
• 相册选图识别（ScanUtil.decode）。
• 手电筒开关（RemoteView switchLight）。
• 左上角关闭；可选 「手动添加」 按钮（业务侧自行弹窗输入内容）。

当前实现范围

本插件为常规 uni_modules UTS 包：业务侧只需从 @/uni_modules/op-custom-scankit 导入并使用导出 API；请勿依赖插件内部的 Kotlin / 原生私有符号。

二、集成前必读（插件市场发布与宿主工程）

2.1 HBuilderX 与运行方式

• 以 uni_modules/op-custom-scankit/package.json 中 engines.HBuilderX 为准（建议不低于该版本），需支持 UTS 编译。
• UTS 会参与 原生编译：仅保存 .vue 热刷新 不等于 已更新原生扫码页。
• 首次接入或升级插件版本后，必须至少执行其一：
  • 制作并安装 自定义调试基座 再真机运行；或
  • 云打包 / 本地离线打包生成新 APK。
• 若仍用不含本 UTS 的 标准基座，表现为点击扫码无原生页、501 或运行期异常。

2.2 Android 版本

• minSdkVersion 以插件内 utssdk/app-android/config.json 为准（当前一般为 28），请保证应用 manifest 中 Android 打包配置不低于此。

2.3 华为 ScanKit / Agconnect（重要）

本插件 config.json 依赖：

• Maven：com.huawei.hms:scanplus（版本以插件仓库内为准）。
• 工程插件：com.huawei.agconnect 及对应 agcp 依赖（与 HMS 扫码常见集成方式一致）。

宿主 App 仍需完成：在 HMS / 开发者联盟侧配置应用、agconnect-services.json 放入 原生工程/App 打包预期路径（与 DCloud/uni-app 工程中华为模块开通方式保持一致）。

若宿主 从未接入过 HMS，仅安装本插件但未配置 Agconnect，可能出现 扫码页闪退、SDK 初始化失败 等现象，请先按华为文档补全后再联调。

若工程中 曾为其它 HMS 能力配置过 Maven 仓库与 Agconnect，一般可减少重复踩坑；仍须在 pages.json 注册演示页（若使用演示）、并按上文确认 scanplus 版本与本插件 config.json 一致或可兼容。

三、权限与隐私（插件市场「声明」可引用）

插件通过 utssdk/app-android/AndroidManifest.xml 合并进宿主，典型包括：

隐私合规建议

• 隐私政策中说明：为实现扫码与相册识别，会使用相机及用户主动选择的相册图片；不通过本插件主动上传条码内容至插件作者服务器（业务方自行请求的接口除外）。
• 应用商店问卷中「收集了哪些数据」请以 宿主业务 + 自建服务端为准；本插件为端侧扫码 SDK 封装。

四、API 说明

4.1 导入

import { scan } from '@/uni_modules/op-custom-scankit'

4.2 scan(options | null, complete)

OpCustomScanOption（可选）

complete(result: OpCustomScanResult)

scanType 语义

• 与华为 HmsScan 类型映射后的字符串常量（如 QR_CODE、CODE128_CODE 等，便于业务分支判断）。
• MANUAL_INPUT：用户在扫码页点了「手动添加」；此时 originalValue 为空字符串，需业务自行弹输入框（演示见 index1.vue 使用 uni.showModal）。

4.3 常见 code 约定

具体 msg 以实际回调为准，请勿仅依赖英文字符串做国际化分支。

五、调用示例（与本目录 index1.vue 一致思路）

扫码成功将内容写入页面 data / 输入框：

import { scan } from '@/uni_modules/op-custom-scankit'

scan({
  manualEnable: true,
  manualText: '没有二维码，手动添加  ›',
  hintText: '请扫描设备上的条形码'
}, (res) => {
  if (res.code === 501) {
    uni.showToast({ title: '请使用 App Android 真机（自定义基座/安装包）', icon: 'none' })
    return
  }
  if (res.code === 401) {
    uni.showToast({ title: '请授予相机与相册相关权限', icon: 'none' })
    return
  }
  if (res.code === 500) {
    uni.showToast({ title: '已取消', icon: 'none' })
    return
  }
  if (res.code !== 0 || !res.data) {
    uni.showToast({ title: res.msg || '失败', icon: 'none' })
    return
  }
  const { scanType, originalValue } = res.data
  if (scanType === 'MANUAL_INPUT') {
    // 自行 uni.showModal / 跳转表单页让用户输入，再赋值给业务字段
    return
  }
  this.scanResult = originalValue
})

路由：将 pages/项目/utsExcelUploadDemo/index1 加入宿主 pages.json（其中的 项目 为你工程中实际的页面分包目录名，须与 path 一致）后可 navigateTo 打开演示页。

六、注意事项与排错

1. 必须自定义基座/新包：改插件后不重新打原生包，易出现旧基座无此模块。
2. 华为配置：扫码白屏或崩溃优先查 Agconnect、agconnect-services.json、应用签名与联盟后台一致性。
3. 与同工程其它原生扫码能力并存：避免多个模块在合并清单中注册 同名 Activity 或占用冲突的请求码；本插件使用独立 AndroidManifest package、Activity 类名与扫码请求码，接入第三方扫码时请各自核对清单合并结果。
4. 手动输入：原生仅回调「手动模式」标记，不内置输入 UI，便于各业务自定义样式。
5. 相册识别失败：与用户选图、contentResolver、图片损坏或条码过小有关；可 Toast 已由原生处理，业务可二次提示用户换图或直接用摄像头扫描。
6. 插件市场上架：建议在商品页「使用声明」中写明：仅 Android App、依赖 HMS ScanKit、需 自定义调试基座/云打包；并将「权限」与「数据」摘要与 package.json → dcloudext.declaration 保持一致或可互相引用。

七、文档与演示文件对照

版本号发布前请以 uni_modules/op-custom-scankit/package.json 中 version 为准同步更新插件市场文案。