更新记录

1.0.1（2026-08-11） 下载此版本

uniapp 非 uts 下 : ios main thread

1.0.0（2026-08-11） 下载此版本

第一版发布

平台兼容性

uni-app(5.14)

uni-app x(5.14)

ohyes-scan

基于 HMS Scan Kit (Android) + Vision Kit (iOS) 的多码 UTS 扫码插件。

与 ohyes-hw-scan 的差异（AB 对比维度）

功能特性

• Android / iOS 双端，原生弹层模式（仿旧插件 startScan）
• 多码检测（仅 iOS）：原生页在每帧识别到的码的中心点绘制圆形标记，用户点击其一即选中；Android 端由 HMS Default View 接管，仅返回单码
• 取景框颜色、遮罩颜色由调用方传入，iOS 端实际生效；Android 端由 HMS Default View 接管
• iOS 智能自动放大：持续无观测超过 1.5s 时（远距离小码典型场景）按光学档位序列渐进 ramp 放大（如 iPhone 15 Pro: 1.0x → 2.0x → 3.0x → 4.5x，每档落在最佳画质点；每档间隔可配置 rampInterval 默认 5s；上限基于光学档位动态计算 maxOpticalZoom × 1.5），iOS 15+ 开启多摄自动切换（光学无损），识别到任何观测后停止放大（autoZoom 默认 true，仅 iOS 生效）
• iOS 弱光优化：自动帧率调整（iOS 14+ 弱光下延长曝光时间）+ 自动 HDR（高对比度场景），底部手动补光按钮（默认显示，点击开/关手电筒 0.7 亮度避免过曝反光）
• 自动处理相机权限申请与错误回调
• 返回 data / format / sceneType / extra / error 五字段

码制式支持

本插件 Android 端基于 HMS Scan Kit（华为统一扫码），iOS 端基于 Apple Vision Kit（VNDetectBarcodesRequest）。两端底层 SDK 的码制式集合并不完全对齐，本节给出官方文档整理后的对照表，便于按业务需要选择 formats 字段。

数据来源：

• HMS Scan Kit：业务介绍 与本地 ScanKitFrameWork.framework/Headers/HmsScanFormat.h、Android HmsScan 常量
• Apple Vision Kit：VNDetectBarcodesRequest / VNBarcodeSymbology

1. 插件统一码制式（ScanCodeFormat）

插件对外暴露统一的字符串枚举，由 UTS 层映射到各平台 SDK 常量。下表为 formats 入参可使用的值及双端支持情况：

说明：

• formats 不传或传空数组时，iOS 端默认仅识别二维码（.qr），以避免 Vision 默认全码制带来的误识别；Android 端默认 ALL_SCAN_TYPE。
• upcA 在 iOS Vision 中无独立枚举（UPC-A 实际由 .ean13 覆盖），传入 upcA 时 iOS 端会被过滤掉、不生效；Android 端正常识别。
• codabar 与 dataMatrix 在 iOS 15.0 以下会被忽略（Vision 在 iOS 15 才加入这两个 symbology），Android 端始终可用。
• 未识别/不支持的值在两端均被过滤，不影响其他有效码制。

2. HMS Scan Kit 完整码制式（Android + iOS）

HMS Scan Kit 在 Android 与 iOS 双端均提供相同的 13 种主流码制式，并额外支持「多功能码」识别。最低系统版本：Android 4.4+、iOS 9.0+。

HMS Scan Kit 还可直接返回码值解析后的结构化场景类型（联系人、Wi-Fi、URL、日历、ID 卡、短信、电话、邮件、地理位置、商品条码、ISBN），iOS Vision 端无此能力，故本插件 sceneType 字段在 iOS 固定为空字符串。

3. Apple Vision Kit 完整码制式（iOS）

Apple Vision Kit 通过 VNBarcodeSymbology 枚举暴露支持的码制式，下表为完整列表及最低 iOS 版本要求。表中加粗项为本插件实际启用的 symbology。

说明：

• Vision Kit 不提供独立的 UPC-A symbology：UPC-A 编码的码值会被 .ean13 识别（UPC-A 是 EAN-13 的子集，前导位为 0）。本插件 upcA 在 iOS 端会被过滤。
• .i2of5（Interleaved 2 of 5）未在 formats 入参中暴露，且 formats 为空时默认仅识别 .qr，故本插件不会自动返回该 symbology。代码中保留 I2OF5 字符串映射仅作兜底。
• 启用 revision = VNDetectBarcodesRequestRevision3（iOS 16+）可提升复杂/小码识别精度，本插件在 iOS 16+ 自动启用。

4. 双端差异速查

目录结构

uni_modules/ohyes-scan/
├── package.json
├── readme.md
└── utssdk/
    ├── interface.uts                  # 对外 API 类型声明
    ├── app-android/
    │   ├── index.uts                  # Android UTS 入口
    │   ├── hybrid.kt                  # HMS Default View 扫码工具类
    │   ├── config.json                # HMS Gradle 依赖
    │   └── AndroidManifest.xml        # 权限声明
    └── app-ios/
        ├── index.uts                  # iOS UTS 入口
        ├── hybrid.swift               # 原生 ScanViewController + Vision
        ├── config.json                # Vision framework 依赖
        └── info.plist                 # 权限说明

安装与使用

1. 复制本插件到项目 uni_modules/ 目录。
2. 在业务页面引入：

import { startScan, checkPermission, requestPermission } from '@/uni_modules/ohyes-scan'

3. 启动扫码（默认开启多码点选 + iOS 智能自动放大）：

startScan({
  formats: ['qr', 'barcode'],
  frameColor: '#4d8bf7',
  maskColor: '#B3000000',
  multiCode: true,
  autoZoom: true, // iOS 智能自动放大远距离小码，默认 true
  rampInterval: 5.0, // iOS 渐进放大间隔（秒），默认 5.0
  success: (res) => {
    console.log('选中码值：', res.data)
    console.log('码制式：', res.format)
  },
  fail: (err) => {
    console.error('扫码失败：', err.error)
  }
})

类型定义

详见 utssdk/interface.uts。

type ScanOptions = {
  formats?: ScanCodeFormat[]
  frameColor?: string
  maskColor?: string
  multiCode?: boolean
  confidence?: number     // 仅 iOS 生效，默认 0.8
  autoZoom?: boolean      // 仅 iOS 生效，默认 true
  rampInterval?: number   // 仅 iOS 生效，渐进放大间隔（秒），默认 5.0
  success?: (res: ScanResult) => void
  fail?: (res: ScanResult) => void
  complete?: (res: ScanResult) => void
}

注意事项

1. 真机调试：双端扫码均需真机；HBuilderX 须使用自定义基座。
2. Android HMS 仓库配置：HMS Scan Kit 需在项目根目录 build.gradle 中配置华为 maven 仓库，已在仓库根目录提供 build.gradle 文件：

   allprojects {
      repositories {
          maven { url 'https://developer.huawei.com/repo/' }
          maven { url 'https://mirrors.huaweicloud.com/repository/maven/' }
      }
   }

   如仍报 Could not find com.huawei.hms:scanplus:2.15.0.301，请在 HBuilderX 中：manifest.json → App Android 配置 → 确认依赖源可用，或在自定义基座流程中手动编辑生成的 build.gradle。

3. Android HMS 配置：需保证 agconnect-services.json 已就绪，与 ohyes-hw-scan 共用一份。
4. iOS Vision 最低版本：deploymentTarget 12.0。
5. 不支持相册选图：本插件聚焦相机扫码，相册能力未实现。
6. 不支持连续扫码：每次 startScan 仅返回用户选中的一个码。

与 ohyes-hw-scan 共存的依赖说明

两个插件均依赖 com.huawei.hms:scanplus:2.15.0.301，可在同一工程共存，无依赖冲突。

错误码

许可

MIT