更新记录

1.0.1（2026-09-02）

• 新增 HarmonyOS 支持，三端支持二维码和条形码多码识别、冻结画面、位置标记与结果选择。
• HarmonyOS 扫码改为插件内部原生窗口，并修复连续扫码预览黑屏。
• 统一扫码结果、权限处理和错误码校验。
• 优化文档，补充 uni-app x UTS 页面中的显式类型声明和调用示例。
• 完善发布元数据，补充 HBuilderX 版本和 iOS 相册权限声明。

1.0.0（2026-01-21）

• feat(iOS): 补齐相机扫码 + 图片扫码（ScanKitFrameWork）
• feat(iOS): 补齐相机权限 check/request，并处理用户取消扫码的快速失败
• feat: 区分扫码取消与扫码失败（新增 9010010）
• chore: 同步插件文档与平台支持标记

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-hw-ml-kit

一个基于 UTS 开发的跨平台扫码插件，Android 使用 Huawei ML Kit，iOS 使用 Apple Vision，HarmonyOS 使用系统 Scan Kit。

功能特性

• ✅ 支持QR码和条码识别
• ✅ Android/iOS/HarmonyOS 相机扫码和图片扫码支持一次返回多个码
• ✅ 原生扫码引擎（Android：Huawei ML Kit Scan；iOS：Apple Vision；HarmonyOS：@kit.ScanKit）
• ✅ 相机实时多码扫码和图片扫码两种模式
• ✅ 完善的权限检查和申请机制
• ✅ 三端同一套 API
• ✅ 完善的错误处理和类型定义

支持平台

• ✅ Android (华为 ML Kit Scan)
• ✅ iOS (Apple Vision，iOS 12+)
• ✅ HarmonyOS (系统 Scan Kit；当前构建按 HarmonyOS 5.0.1 / API 13 验证)

最低 HBuilderX 版本：4.81（付费 UTS 插件的 HarmonyOS 支持要求）。

扫码页面

相机扫码由插件内部打开原生扫码窗口，调用方无需注册扫码页面，也无需在应用层声明额外的 HarmonyOS UIAbility。HarmonyOS 不再依赖 hans-hw-scan-view.uvue；Android/iOS 的现有行为保持不变。

API 说明

uni-app x 页面调用（UTS）

uni-app x 页面使用的是 UTS，不是普通 JavaScript。请在 .uvue 页面中显式声明 lang="uts"，并为插件的 Options、Result、Fail 类型显式标注。页面只从插件根路径导入，不要直接引用 utssdk 内部文件。

<script setup lang="uts">
import { ref } from 'vue'
import {
  initScanCode,
  scanCode,
  type InitFail,
  type InitOptions,
  type InitResult,
  type ScanCodeFail,
  type ScanCodeOptions,
  type ScanCodeResult,
} from '@/uni_modules/hans-hw-ml-kit'

const scanResult = ref<ScanCodeResult | null>(null)
const errorMessage = ref<string>('')

function initializePlugin(): void {
  const options: InitOptions = {
    success: (res: InitResult): void => {
      console.log('初始化成功，当前平台支持:', res.isSupported)
    },
    fail: (err: InitFail): void => {
      errorMessage.value = err.errMsg
    },
  }
  initScanCode(options)
}

function startCameraScan(): void {
  const options: ScanCodeOptions = {
    scanType: 'all',
    mode: 'camera',
    success: (res: ScanCodeResult): void => {
      scanResult.value = res
      console.log('识别数量:', res.count)
    },
    fail: (err: ScanCodeFail): void => {
      errorMessage.value = err.errMsg
    },
  }
  scanCode(options)
}

initializePlugin()
</script>

scanResult 的类型是 ScanCodeResult | null，扫码结果通过 res.results 读取；每一项是 ScanCodeItem，包含 text、format 和 scanType。如果需要在页面按钮事件中调用，只需将 startCameraScan 绑定到 @click 即可。

传统 uni-app 页面使用普通 Vue/JavaScript 写法即可，下面的 API 示例适用于传统 uni-app；在 uni-app x 中请按上面的 UTS 写法补充显式类型。

初始化插件

import { initScanCode } from '@/uni_modules/hans-hw-ml-kit'

initScanCode({
  success: (res) => {
    console.log('初始化成功:', res)
    // res.isSupported - 是否支持华为ML Kit
  },
  fail: (err) => {
    console.error('初始化失败:', err)
  }
})

说明：

• 建议应用启动/页面 onLoad 调一次 initScanCode；未初始化直接调用 scanCode 会走失败回调（9010003）。
• 三端都按“单次扫码”设计，同一时刻只能发起一次 scanCode；重复调用返回 9010012。

扫码功能

import { scanCode } from '@/uni_modules/hans-hw-ml-kit'

// 相机扫码
scanCode({
  scanType: 'all', // 'qr' | 'barcode' | 'all'
  mode: 'camera',
  success: (res) => {
    console.log('扫码结果:', res)
    // res.count - 识别数量
    // res.results - 扫码结果数组，每项包含 text / format / scanType
  },
  fail: (err) => {
    console.error('扫码失败:', err)
  }
})

// 图片扫码
scanCode({
  scanType: 'qr',
  mode: 'image',
  imagePath: '/path/to/image.jpg',
  success: (res) => {
    console.log('图片扫码结果:', res)
  },
  fail: (err) => {
    console.error('图片扫码失败:', err)
  }
})

参数约定：

• scanType：'qr' | 'barcode' | 'all'（默认 all）。
• mode：'camera' | 'image'（默认 camera）。
• 非法 scanType / mode 会返回 9010011。
• imagePath：仅 mode: 'image' 必填；支持 uni.chooseImage 返回的临时路径、普通文件路径、file://...，Android 侧也支持 content://...。
• 同一时刻只能发起一次 scanCode；重复调用会返回 9010012。
• 返回值：ScanCodeResult 为 { count, results }，不再返回顶层 text / format / scanType。
• Android/iOS/HarmonyOS 相机扫码和图片扫码都可能返回多个结果。
• 相机同一帧识别到多个码时会冻结画面并显示编号；可点击编号返回单个结果，也可选择返回全部结果。

权限管理

import { checkPermission, requestPermission } from '@/uni_modules/hans-hw-ml-kit'

// 检查相机权限
checkPermission({
  permissions: ['ohos.permission.CAMERA'], // Android 使用 android.permission.CAMERA
  success: (res) => {
    if (res.allGranted) {
      console.log('相机权限已授权')
    } else {
      console.log('相机权限未授权:', res.deniedList)
    }
  },
  fail: (err) => {
    console.error('权限检查失败:', err)
  }
})

// 申请相机权限
requestPermission({
  permissions: ['ohos.permission.CAMERA'], // Android 使用 android.permission.CAMERA
  success: (res) => {
    if (res.allGranted) {
      console.log('权限申请成功')
    } else {
      console.log('部分权限被拒绝:', res.deniedList)
    }
  },
  fail: (err) => {
    console.error('权限申请失败:', err)
  }
})

说明（跨端一致性）：

• Android 使用 android.permission.CAMERA，HarmonyOS 使用 ohos.permission.CAMERA。
• iOS 侧仅识别“相机权限”这一类权限；为了方便同一套代码复用，上述任一相机权限字符串都会被识别。

日志开关

import { setLogEnabled } from '@/uni_modules/hans-hw-ml-kit'

// 默认开启；关闭后插件内部将不再输出日志
setLogEnabled(true)
setLogEnabled(false)

说明：setLogEnabled 控制插件 UTS 层和各平台原生实现的日志输出；日志统一前缀为 [hans-hw-ml-kit]。

错误码说明

权限配置

Android：插件已自动配置以下权限：

• android.permission.CAMERA - 相机权限（见 utssdk/app-android/AndroidManifest.xml）

iOS：请在应用侧配置权限描述（插件提供了示例片段，需合并到你的 iOS 工程/配置中）：

• NSCameraUsageDescription（相机扫码）
• NSPhotoLibraryUsageDescription（若使用“相册选图 + 图片识别”）
• 示例：utssdk/app-ios/Info.plist

HarmonyOS：插件已通过 utssdk/app-harmony/module.json5 自动声明：

• ohos.permission.CAMERA

依赖说明

插件自动配置以下依赖：

• Android 华为 Scan Kit：com.huawei.hms:scanplus:2.13.0.303
• iOS：系统 Vision / AVFoundation / CoreImage，无第三方 CocoaPods 依赖
• HarmonyOS：系统 @kit.ScanKit，无第三方 ohpm 扫码依赖

技术实现

本插件采用 UTS + 原生混编：

• UTS层：负责接口定义、参数校验、权限管理和线程调度
• Android（Kotlin）：负责 Huawei ML Kit Scan 的具体实现和回调处理
• iOS（Swift）：负责 Apple Vision 多码识别、相机预览、冻结选择和回调处理
• HarmonyOS（ArkTS / ArkUI）：负责 Scan Kit 自定义预览、多码冻结、坐标标记与选择