更新记录

1.0.1（2026-03-30）

补齐本地打基座包运行失败相关文档

1.0.0（2026-03-30）

1.版本发布

平台兼容性

uni-app(4.54)

uni-app x(4.22)

hw-custom-scankit

华为 ScanKit RemoteView（Android）/ HmsCustomScanViewController 持续扫（iOS）；底部栏交互对齐业务 ScanFooter（已扫描角标 + 扫描完成）。

产品优先级：以 Android 实现为基准。scanContinuous / closeContinuousScan 与 HWScanOption、各 code 约定在双端一致；观感与底层细节允许与 Android 有差异（见下「Android 与 iOS 功能差异」）。若业务以安卓为准验收，请不要仅凭 iOS 表现反推改公共协议。

本机 HBuilderX 编 UTS Android 若遇 Gradle / scanplus 等问题，见文末 「附录：HBuilderX 本地 UTS Android 编译踩坑与排查全记录」；可复制 utssdk/app-android/local-dev-init.gradle.example 为 init.gradle 使用。

Android 与 iOS 功能差异（以 Android 为准）

一致部分（双端应对齐测试）：code 0 / 498 / 499 / 497 / 401 的语义；498 / 499 不关页、只有 497 + closeContinuousScan 关页；results JSON 结构；minSuccessCallbackIntervalMs 全局节流（抑制时同样不写列表、不音效、不震动）；scanLineLocalPath / scanLineImageUrl 优先级；底栏与完成按钮、角标累计逻辑。

关闭行为（重要）

• 用户点 左上角返回、系统返回键、或底部 「扫描完成」：不会关闭相机页，只会在回调里收到 499 或 498，并附带当前已累计的 results 列表。
• 只有在你调用 closeContinuousScan() 时才会关闭扫码界面；关闭前会再回调 497，同样附带当时的 results。
• 业务收到 498 / 499 后若要退出页面或 navigateBack，请先按需处理列表数据，再调 closeContinuousScan()。

静态资源目录（Android / iOS 互不影响）

回调对象公共字段

scanType：插件内映射的码制英文名（如 QR_CODE、CODE128_CODE 等）。originalValue：扫码得到的原始字符串。同一条码多次识别会产生多条记录，去重请在业务侧处理。

各 code 返回参数字段说明

以下为 complete(res) 里 res 在各 code 下的约定（未列出的字段在该 code 下恒为 null）。

说明：

• 498 / 499：仅收到事件与列表，不会自动关相机；需要你再调 closeContinuousScan() 才会关页并再收到 497。
• 497：回调顺序是先 complete（497），再销毁原生 Activity；可在该分支里做页面跳转或清状态。
• 0 与 498 / 499 / 497 的「条数」：多次 0 累加进列表后，在 498 / 499 / 497 里的 results 与列表一致；若尚未扫到任何码就点完成或返回，results 为 []。

传入参数一览

与 utssdk/interface.uts 中 HWScanOption 一致，便于 IDE 悬停查看；摘要如下：

被节流 抑制 的识别：不会震动/音效、不会角标+1、不会写入 results 列表。

扫描线动画（Android / iOS）

总开关：必须 scanLineEnabled: true，否则不显示扫描线（不传或为 false 时无叠加层）。

效果说明

• 在 ScanKit 取景框矩形 内叠加一张横向拉伸的图，沿框高方向 单程平移，到顶后再 往返（ObjectAnimator + REVERSE），与常见「一道激光线」效果一致。
• scanLineDurationSec：单程耗时（秒），原生侧约限制在 0.6～60；数值越大线移动越慢。

图片来源与优先级（重要）

三者只能生效一套，按顺序判断（本地路径优先于网络）：

同时传 本地路径 与 网络 URL 时：只用本地；网络 URL 会被忽略。

本地图片 scanLineLocalPath

• 含义：设备上可读的 绝对路径 字符串（插件内用 File + BitmapFactory.decodeFile）。
• 推荐用法：先 uni.downloadFile（或你们自己的下载逻辑），再取返回的 tempFilePath（或等价本地路径）传给 scanLineLocalPath，与 scanContinuous 同一次调用传入（无需等下载完成再第二次拉起，只要在调用前路径已存在即可）。
• 路径格式：可直接 /storage/emulated/0/...；若为 file:///...，原生会尝试解析出 path 再读文件。
• 权限：文件须当前应用可读（应用私有目录、downloadFile 临时路径一般无额外存储权限问题；读公共目录需自行满足系统存储权限）。
• 格式：常见 PNG / JPEG 等 BitmapFactory 支持的格式；建议 横向条带状 PNG，与设计稿一致即可（显示为 FIT_XY，宽度铺满取景框，条带高度约为框高约 12%）。
• 失败：文件不存在、不可读或解码失败 → 自动使用内置扫描线图，动画仍会有。

网络图片 scanLineImageUrl

• 含义：完整 http:// 或 https:// 图片地址；原生 HttpURLConnection 下载（连接超时约 10s、读超时约 15s，跟随重定向）。
• 权限：插件 AndroidManifest 已声明 INTERNET；云打包合并后即可访问网络。
• HTTP 明文：若使用 http://，可能被系统 禁止明文流量，需在主应用 networkSecurityConfig / usesCleartextTraffic 等自行放行；生产环境建议 HTTPS。
• 体验说明：网络较慢时，会先看到 内置图 动画，下载完成后再 切换 为网络图（可能有一次视觉切换）。
• 失败：超时、非图片、解码失败等 → 保持内置图，不中断扫码。

示例：内置图（仅开启动画）

scanContinuous({
  scanLineEnabled: true,
  scanLineDurationSec: 3,
}, onResult)

示例：网络图

scanContinuous({
  scanLineEnabled: true,
  scanLineImageUrl: 'https://example.com/static/scan-line.png',
  scanLineDurationSec: 3,
}, onResult)

示例：先下载再本地路径（推荐替代明文 HTTP / 需鉴权头时）

uni.downloadFile({
  url: 'https://example.com/static/scan-line.png',
  success: (ret) => {
    if (ret.statusCode === 200 && ret.tempFilePath) {
      scanContinuous({
        scanLineEnabled: true,
        scanLineLocalPath: ret.tempFilePath,
        scanLineDurationSec: 3,
      }, onResult)
    }
  },
})

（若下载失败，可降级为不传 scanLineLocalPath、只传 scanLineImageUrl，或仅用内置图。）

给前端同学：常见场景

footerExtraBottomPx 为 Android 像素，与 rpx 不同。closeContinuousScan() 关的是原生扫码 Activity，不是 uni.navigateBack。

回调推荐顺序

scanContinuous({ /* ... */ }, (res) => {
  if (res.code === 401) {
    // data/results 均为 null；引导用户开权限
    return
  }
  if (res.code === -1) {
    // data/results 均为 null；非 Android 或未实现
    return
  }
  if (res.code === 0 && res.data) {
    // 仅此分支有 res.data；res.results 为 null
    return
  }
  if (res.code === 498 || res.code === 499) {
    // res.results 为数组（可能 []）；不关页
    return
  }
  if (res.code === 497) {
    // res.results 为数组；随后原生页关闭
    return
  }
})

选项示例

import { scanContinuous, closeContinuousScan } from '@/uni_modules/hw-custom-scankit'

scanContinuous({
  closeShowBackIcon: true,
  closeButtonText: '',
  closeButtonColor: '#FFFFFF',
  finishButtonText: '扫描完成',
  footerBackgroundColor: '#2c2c2c',
  finishButtonColor: '#1C86EE',
  finishButtonTextColor: '#FFFFFF',
  footerLabelColor: '#FFFFFF',
  footerScanLabel: '已扫描',
  badgeBackgroundColor: '#ff0000',
  badgeTextColor: '#FFFFFF',
  hapticOnSuccess: true,
  soundOnSuccess: true,
  useBundledSuccessSound: true,
  // 扫描线（可选，见上文「扫描线动画」）
  // scanLineEnabled: true,
  // scanLineLocalPath: '',
  // scanLineImageUrl: '',
  // scanLineDurationSec: 3,
}, (res) => { /* ... */ })

closeContinuousScan()

报错「回调函数已释放，不能再次执行」

需 HBuilderX 4.27+，插件已对 scanContinuous 使用 @UTSJS.keepAlive。详见 UTS keepAlive。

附录：HBuilderX 本地 UTS Android 编译踩坑与排查全记录

下文记录本插件在 补充 iOS 实现后，本机 Android 侧 UTS 编译陆续出现的问题、判断思路与最终可行方案，便于团队复现与自查。云打包/自定义基座若正常，仅本地失败，多半属于 Gradle 环境，与 scankit.kt 业务代码无矛盾。

A. 背景：为什么在「增加 iOS」之后才频繁报错？

• hw-custom-scankit 是 UTS 插件：修改 utssdk/app-ios、调整 package.json 等，会让 HBuilderX 认为 整模块有变更，从而 对 Android 端 utssdk/app-android 也重新走一遍本地 UTS → Gradle 流程。
• 此前若很少本地编 Android，或未清空插件缓存，问题可能被「盖住」；全量重编后环境问题会一次性暴露。
• 结论：不是说 iOS Swift 与 Kotlin「冲突」，而是 触发了完整的本机 Android 编译链，对 Gradle 版本、临时工程目录、Maven 仓库 提出了要求。

B. 现象一：gradle.bat 不是可执行程序

日志特征：提示某路径下的 gradle.bat 不是可执行程序或找不到。

思路：

• HBuilderX 运行配置里指定的 Gradle 安装目录 必须真实存在，且 bin\gradle.bat 可执行。
• 路径中尽量少用异常字符；安装 Gradle 后可用 CMD 执行：
  "D:\你的路径\gradle-x.x\bin\gradle.bat" -v
  确认能输出 Gradle 版本。

注意：这与后面「scanplus 找不到」是 不同阶段 的问题——Gradle 都起不来时，优先修这一项。

C. 现象二：Configuring project ':app' without an existing directory is not allowed

日志特征：失败路径类似
%AppData%\Roaming\HBuilder X\.uts-development-android\gradle\hw-custom-scankit_<时间戳>\app
不存在、不可写或非目录。

思路：

• Gradle 9 起，对 settings / include ':app' 等行为变严：被包含工程的目录在配置阶段就必须已存在；而 HBuilderX 为 UTS 生成的流程往往是 先拉起 Gradle / 再解压或生成子工程，与 Gradle 9 的假设 容易冲突。
• 以管理员身份运行 HBuilderX 通常 解决不了 这一类错误——根因是 Gradle 大版本行为，不是单纯权限。

处理：

• 在运行配置中使用 Gradle 8.x（实践常用 8.14.x 等与 HBuilderX 文档接近的版本），避免 Gradle 9.x 作为本机 UTS 开发用的 Gradle。
• Gradle 8.x 官方下载：Gradle Releases — 8.14.4（Gradle 官方发布页；同一 Releases 列表亦可选用其它 8.x 补丁版本）。下载 binary-only 或 complete ZIP，解压到本机目录后，在 HBuilderX 运行配置中指向 …\gradle-8.14.4\bin\gradle.bat（版本号与文件夹名以实际为准）。
• 清理损坏的临时目录（见下文 H. 操作清单）后重试。

D. 现象三：找不到名称 "huawei" / UTS 提示参考 compiler-known-issues error18

日志特征：指向 scankit.kt 里 import com.huawei.hms... 一行，UTS 报 找不到 huawei。

思路：

• 本质是 本地编译时 classpath 上没有 HMS 依赖，编译器把 com.huawei... 未解析，有时错误信息显示在 huawei 片段上。
• DCloud 文档 compiler-known-issues error18 说明：含 三方依赖 的 UTS 插件需 配置好本机 Android/Gradle 运行环境；与 云打包机已预置仓库 不同。

处理：

• 先保证 Gradle 可运行（见 B），再保证 能拉到华为依赖（见 E、G）。Gradle 能把 scanplus 解析下来后，这类「找不到名称」通常会消失。

E. 现象四：Could not find com.huawei.hms:scanplus:2.12.0.301

日志特征：
Execution failed for task ':androidDependencies' 或 Could not resolve ... debugCompileClasspath，明确 找不到 scanplus；常伴随一句：
The project declares repositories, effectively ignoring the repositories you have declared in the settings.

思路（重要）：

1. 依赖本身放在公开仓库
   scanplus 在 https://developer.huawei.com/repo/（官方文档与 UTS 远程仓库说明 均列出华为源）。本插件 utssdk/app-android/config.json 中声明的
   com.huawei.hms:scanplus:2.12.0.301
   与 hw-scankit 等插件一致，版本在云打包环境可用；本机失败 不是 coordinates 写错，而是 Gradle 没去华为仓解析。

2. Gradle 8+ 的「仓库到底听谁的」

   • 工程可能同时使用 settings.gradle 里的 dependencyResolutionManagement 与各子工程 build.gradle 里的 repositories {}。
   • 日志里 「project 声明了 repositories，从而忽略 settings 里的」 意味着：实际参与某配置解析的很可能是子工程自己的 repositories，而 HBuilderX 生成的默认列表里 往往只有 google / mavenCentral 等，没有 developer.huawei.com/repo。
   • 因此：只改 settings 或只在 projectsLoaded 里给 allprojects 加仓库，在部分工程结构下 仍不够——这就是第一次只写「弱版」init.gradle 时 依然 Could not find 的原因。

3. 网络
   公司代理或防火墙拦截 华为域名 时，同样会表现为找不到 artifact；可浏览器访问
   https://developer.huawei.com/repo/
   做粗测；必要时配置代理或使用 repo.huaweicloud.com 镜像作补充（见 G）。

F. 云打包 vs 本机：为何「云上能过、本地不过」？

G. 最终方案：init.gradle 三处挂钩 + 双路径备份

原则：在 不修改 HBuilderX 内部生成脚本 的前提下，用用户级 init.gradle 在 尽量早、尽量全 的环节把华为 Maven 写进仓库列表。

推荐内容（与仓库内示例文件一致，便于同步）：

• 本仓库示例路径：
  utssdk/app-android/local-dev-init.gradle.example
  复制为当前机器上的 init.gradle（内容逐字一致即可）。

逻辑说明：

1. gradle.beforeSettings
   对 settings.dependencyResolutionManagement.repositories { ... } 注入华为与华为云镜像，覆盖 「统一在 settings 里声明依赖解析」 的工程。

2. gradle.beforeProject
   对每个即将配置的工程，向 buildscript.repositories 与 repositories 注入同样两个地址，覆盖 「实际以子工程 build.gradle 为准」 的解析路径（与 E.2 日志现象对应）。

3. gradle.projectsLoaded + rootProject.allprojects
   作为 兜底，再次对全部子工程注入，避免遗漏。

放置位置（务必读）：

编辑 init.gradle 时务必核对域名：须为 developer.huawei.com，避免出现拼写错误（如 huawaii）导致仍解析失败。

H. 每次调整 Gradle / init.gradle 后的推荐操作清单

1. 保存 init.gradle（上述一处或两处）。
2. 完全退出 HBuilderX 再启动（避免进程占用旧缓存）。
3. 删除 UTS Android 临时缓存（让脚手架按新环境重建）：
   %AppData%\Roaming\HBuilder X\.uts-development-android
   整个目录删除即可。
4. 重新对 hw-custom-scankit 执行 运行 / 编译 Android。
5. 若仍失败：用 CMD 执行
   "<你的gradle>\bin\gradle.bat" help -g "%USERPROFILE%\.gradle"
   观察是否有 init script 相关加载失败；并检查环境变量 GRADLE_USER_HOME 是否指向其它目录——若是，在该目录下也放置 init.gradle。

I. 参考链接（官方）

• Gradle 8.x 发行包下载：8.14.4 直达锚点 · 全部版本列表
• UTS Android 与远程仓库说明：
  https://doc.dcloud.net.cn/uni-app-x/plugin/uts-for-android.html
• UTS 编译已知问题（含 error18 / Unresolved reference）：
  https://doc.dcloud.net.cn/uni-app-x/uts/compiler-known-issues.html#error18
• Gradle 声明仓库（理解 project vs settings 提示）：
  https://docs.gradle.org/current/userguide/declaring_repositories.html

J. 小结（给维护者的一句话）

Gradle 9 不要用在本机 UTS 插件开发；scanplus 必须能从华为（及可选华为云镜像）Maven 拉到；单点 projectsLoaded 注入仓库不可靠，需 beforeSettings + beforeProject + projectsLoaded；init.gradle 可能要放两套路径；改完清 .uts-development-android。

基座

需 HMS + 自定义调试基座。