适用于海外GMS设备的UTS插件，支持自定义UI，能识别正反码

更新记录

1.0.1（2026-01-30）

1、更新配置文件

版本说明（changelog）

说明：版本号请以 uni_modules/zhs-scan-view/package.json 中的 version 为准。

1.0.0（2026-01-29）

连续扫码/多码场景友好：内置节流与去重，减少重复回调与抖动
反码识别优化：自动判断亮度并启用反码预处理，提高黑底白码/暗光场景识别率
长条形码识别优化：优先 CODE_128 通道，再回落全格式扫描，提升长码与物流码识别稳定性
无 16KB 限制问题：不走 Intent 结果传递，识别结果通过组件事件回传，适合长内容条码
适配上架：使用官方 CameraX/ML Kit 依赖，便于满足应用商店（含 Google Play）审核要求
overlay 性能优化：静态层缓存 + 局部刷新，提升雷达线流畅度

平台兼容性

uni-app(4.71)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
√	√	×	×	√	√	5.0	×	×

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
×	×	×	×	×	×	×	×	×	×	×	×

其他

多语言	暗黑模式	宽屏模式
√	×	×

插件名称

zhs-scan-view（UTS版）

插件简介

基于 Android CameraX + Google ML Kit 的实时扫码原生组件（UTS 组件），提供预览画面、识别回调，以及识别区域遮罩/取景框/雷达线（扫描线）UI。

插件特点

秒级识别体验：基于 CameraX 实时帧分析，低延迟回调（实际速度与机型/光线相关）
反码/弱光更稳：内置反色 + 二值化预处理，对反码、低对比度条码更友好
长条形码优化：优先走 Code128 专用识别通道，再回退全格式识别，提高速度与成功率
自带取景框 UI：遮罩识别区域 + 边框四角 + 雷达线/扫描线动画
事件体系完整：ready / marked / error / debug，方便业务埋点与线上排障
大数据回调更安全：事件 payload 使用对象传递，避免常见的 16KB 字符串限制问题
国际版技术栈：使用 Google 官方依赖（CameraX / ML Kit），适合海外发布与 Google Play 上架场景

适用场景

商品条码/快递单号/票据等一维码识别
二维码识别（如 URL、登录码、活动码等）
需要“类相机”取景框 UI 的扫码页面

平台支持

Android App：支持
iOS / H5 / 小程序：不支持（建议业务侧自行做降级方案）

国际版说明（重要）

本插件依赖 Google Play Services / ML Kit 相关能力，面向海外/国际版设备体验更稳定
在未预装或无法使用 GMS 的设备（常见于部分国内定制系统）可能出现初始化失败、无法识别等情况
如果你的应用主要面向国内无 GMS 设备，建议准备替代方案（例如厂商扫码 SDK 或其他离线识别实现）

依赖说明

AndroidX CameraX（camera-camera2 / camera-lifecycle / camera-view）
Google Play Services ML Kit Barcode Scanning

说明：依赖由插件侧引入，业务侧无需额外集成（以你当前项目的依赖与构建环境为准）。

权限说明（Android）

必须权限：

android.permission.CAMERA

建议：

建议业务侧提前申请相机权限，以获得更可控的交互体验

安装方式

方式一：插件市场安装（推荐）

在 HBuilderX 插件市场搜索 zhs-scan-view 并下载安装到项目。

方式二：本地引入

将插件目录放入项目：

uni_modules/zhs-scan-view/

使用方法

1）模板用法（页面中引入）

<template>
  <view class="page">
    <zhs-scan-view
      ref="scan"
      class="scanner"
      @ready="onReady"
      @marked="onMarked"
      @error="onError"
      @debug="onDebug"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onReady(e) {
      console.log('ready:', e.detail)
    },
    onMarked(e) {
      console.log('marked:', e.detail)
    },
    onError(e) {
      console.error('error:', e.detail)
    },
    onDebug(e) {
      console.log('debug:', e.detail)
    }
  }
}
</script>

<style>
.page { flex: 1; }
.scanner { flex: 1; }
</style>

2）手电筒控制

this.$refs.scan?.setFlash(true)  // 开灯
this.$refs.scan?.setFlash(false) // 关灯

界面自定义

1）自定义组件尺寸

取景框会根据组件实际宽高自适应计算（默认取短边的 70% 作为识别框）。你可以通过外层样式控制扫码区域大小：

<template>
  <view class="page">
    <zhs-scan-view class="scanner" />
  </view>
</template>

<style>
.page { flex: 1; }
.scanner { flex: 1; }
</style>

如果你只想在页面中间显示一个固定高度的扫码区域，也可以设置固定高度：

.scanner { height: 420px; }

2）自定义页面叠加 UI（按钮/提示文案/引导框）

插件自带遮罩/四角/扫描线，你仍然可以在页面上方叠加自己的 UI（例如“相册识别”“闪光灯按钮”“提示文案”等）。

App-nvue：可用 position: absolute + z-index 叠加普通组件
App-vue：建议使用 cover-view / cover-image（可覆盖原生视图）

示例（思路展示，按你的项目类型选择实现方式）：

<template>
  <view class="page">
    <zhs-scan-view class="scanner" />
    <view class="hud">
      <text class="tip">请将二维码/条形码置于框内</text>
      <view class="actions">
        <view class="btn">相册</view>
        <view class="btn">开灯</view>
      </view>
    </view>
  </view>
</template>

<style>
.page { flex: 1; }
.scanner { flex: 1; }
.hud {
  position: absolute;
  left: 0;
  right: 0;
  bottom: 40px;
  z-index: 10;
  align-items: center;
}
.tip { color: #ffffff; opacity: 0.9; margin-bottom: 16px; }
.actions { flex-direction: row; }
.btn {
  padding: 10px 16px;
  margin: 0 8px;
  border-radius: 6px;
  background-color: rgba(0, 0, 0, 0.45);
  color: #ffffff;
}
</style>

3）自定义取景框样式（颜色/线宽/扫描线速度/框大小）

当前版本的取景框样式为内置默认值（遮罩颜色、边框颜色、四角颜色、扫描线颜色/速度等）。如需深度定制，建议二开调整插件原生层参数：

文件：uni_modules/zhs-scan-view/utssdk/app-android/NativeScanView.kt
类：ScanOverlayLayer
可调整项示例：
- 遮罩颜色/透明度：maskPaint.color
- 边框/四角/扫描线颜色与线宽：framePaint / cornerPaint / laserPaint
- 扫描线速度：duration = 2000
- 识别框大小比例：frameSize = min(w, h) * 0.7f

如果你希望“运行时通过 props 动态配置这些样式”，可以在 index.vue 增加组件属性，并在 NativeScanView 中暴露对应 setter 方法（后续版本也可以按需加上）。

API 说明

组件

<zhs-scan-view />

方法（expose）

setFlash(enable: boolean)

功能：开关手电筒
参数：
- enable：true 开，false 关
说明：设备无闪光灯或相机未就绪时会自动忽略并通过 debug 事件输出状态

事件说明

ready

组件关键阶段回调（可用于判断权限/生命周期/是否已绑定相机）

payload（e.detail）：

phase：created / attached / bound / permission_required / permission_granted
hasPermission：是否已授予相机权限
hasActivity：是否能获取到 Activity
hasLifecycleOwner：是否能获取到 LifecycleOwner
hasFallback：是否启用生命周期回退
attached：视图是否已挂载到窗口

marked

识别成功回调

payload（e.detail）：

code：条码格式（ML Kit format 整数）
message：识别内容字符串
engine：固定为 "mlkit"

error

错误回调

payload（e.detail）：

code：错误码字符串（如 INIT_CAMERA_FAIL / BIND_FAIL / CAMERA_PERMISSION_REQUIRED 等）
message：错误详情文本

debug

调试信息回调（便于线上定位权限/绑定/帧处理等问题）

payload（e.detail）：

action：调试分类（permission / bind / frame / mlkit / torch 等）
message：调试详情文本
attached：视图是否已挂载

常见问题（FAQ）

1）为什么不显示取景框/扫描线？

请确认页面样式没有把组件高度压缩为 0（建议给容器 flex: 1）
若使用了特殊容器或层级，确保组件处于最上层可见（插件内部已尽量处理）

2）为什么一直提示相机权限？

请确认 Android 已授予相机权限
若为自定义基座，请确认已包含本插件并重新打包

3）识别结果频繁重复触发怎么办？

插件内部有默认的去重与冷却（cooldown）策略；如需更强的业务侧去重，请在 marked 回调中自行处理。

更新记录

详见 changelog.md

联系方式

手机： 微信： 邮箱：1500712995@qq.com 如果想自定义样式也可以联系我，我会根据你的需求定制。