更新记录

2.0.2(2026-11-19)

首次发布:完成 Android / HarmonyOS 双端实现与真机验证。

2.0.1(2026-11-19)

首次发布:完成 Android / HarmonyOS 双端实现与真机验证。

2.0.0(2026-11-19)

首次发布:完成 Android / HarmonyOS 双端实现与真机验证。

查看更多

平台兼容性

uni-app x(4.25)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ × √ ×

其他

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

uni-scan-pro

增强扫码 UTS 插件:相机多码点选 + 相册识别 + 内容智能解析 + 码生成(样式/logo)+ 能力诊断。相机扫码基于华为 Scan Kit——同屏出现多个码时自动框选、画箭头,用户点一下即选中,这是 uni.scanCode 内置能力做不到的;Android / 鸿蒙一套 API。

需要自定义基座:插件集成华为 Scan Kit 官方 aar(含原生 so 与扫码界面资源),必须打自定义基座后才能运行,标准基座会提示原生依赖不可用。

效果预览

MuMu 模拟器(Android 12)真机运行截图,图片托管在插件市场 CDN。

扫码插件运行效果

差异化能力

能力 内置 uni.scanCode uni-scan-pro
单码扫码 ✅ ✅
同屏多码 · 箭头标注 · 点击选中 ❌ ✅
多码结果数组返回 ❌ ✅
码生成(10 种格式) ❌ ✅
相册图片多码解析 ❌ ✅
扫码内容智能识别(URL/WiFi/名片…) ❌ ✅
码生成 · 圆点/圆角样式 · 中心 logo ❌ ✅
取消 / 权限失败精细区分 ❌ ✅(9020009 / 9020008)

平台支持

平台 相机扫码 生成引擎 图片解析引擎
Android ✅ 华为 Scan Kit 华为 Scan Kit(主)+ ZXing(兜底) ZXing 多码
鸿蒙 HarmonyOS ✅ Scan Kit(enableMultiMode) 降级(建议 ArkUI QRCode 组件) Scan Kit
iOS 🚧 后期版本 🚧 🚧

快速开始

import { scanCode, generateCode, decodeImage, diagnose } from '@/uni_modules/uni-scan-pro'

// 1. 相机扫码(多码时界面自动标注,用户点选)
scanCode({
  scanType: 'all',
  success: (res) => {
    console.log('识别到', res.count, '个码')
    res.codes.forEach((c) => console.log(c.get('format'), c.get('text')))
  },
  fail: (err) => {
    if (err.errCode == 9020009) console.log('用户取消')
    if (err.errCode == 9020008) console.log('相机权限被拒')
  }
})

// 2. 从相册选图识别(无需相机权限)
scanFromAlbum({ success: (res) => console.log(res.count, res.codes) })

// 3. 生成带样式的二维码(圆点 + 中心文字,自动保证可扫)
generateCode({
  content: 'https://example.com',
  style: 'dot',            // square / round / dot
  logoText: '小铺',         // 中心文字,也可用 logoPath 传图片
  margin: 12,
  returnBase64: true,      // 免读文件,可直接给 <image>
  success: (res) => console.log(res.path, res.base64)
})

// 4. 解析相册图片里的码(支持多码)
decodeImage({ path: '/sdcard/qr.png', success: (res) => console.log(res.codes) })

// 5. 扫码内容智能识别:url / wifi / vcard / tel / sms / email / geo / text
parseContent({
  content: 'WIFI:T:WPA;S:MyWiFi;P:12345678;;',
  success: (info) => console.log(info.type, info.title, info.fields)
})

// 6. 诊断当前生效能力
diagnose({ success: (res) => console.log(res.canScanCamera, res.supportedFormats) })

API 清单

方法 参数 说明
scanCode(options) {scanType?, viewType?, errorCheck?, showGuide?} 相机扫码,返回 codes[](多码)、count、fromCamera
scanCode(options) {scanType?, viewType?, errorCheck?, showGuide?} 相机扫码,返回 codes[]、count、fromCamera
scanFromAlbum(options) {scanType?} 相册选图识别,返回同 scanCode(fromCamera:false)
generateCode(options) {content, format?, width?, height?, foregroundColor?, backgroundColor?, path?, logoPath?, logoText?, style?, margin?, returnBase64?} 生成码,返回 path/format/width/height/base64/engine
decodeImage(options) {path?, base64?, scanType?, includePoints?} 图片解析,返回 codes[](多码)与 count
parseContent(options) {content} 内容识别,返回 type/title/subtitle/raw/fields
getVersion(options) {success?} 版本信息 pluginVersion/scanKitVersion/zxingVersion/engine
diagnose(options) {success?} 诊断:canGenerate/canDecode/canScanCamera/supportedFormats/engine/huaweiAvailable

生成样式(style)

  • square:标准方形,Android 优先用华为引擎生成
  • round:圆角码点
  • dot:圆点码点(数据区圆点,定位角/时序线/对齐图案保持方形以保证识别率)

生成后插件会自检可扫性:若样式或中心 logo 影响识别,会自动回退(圆点→方形→去 logo),保证交付的码一定能扫。静区自动按 4 个模块计算,无需手动补边距。

码类型(format / scanType)

qrCode(默认)、code128、code39、code93、ean13、ean8、upcA、aztec、pdf417、datamatrix

返回结构

  • scanCode / scanFromAlbum 成功:{errCode:0, errMsg:'ok', codes:[{text, format, hasPoints, points, engine}], count, fromCamera}
  • generateCode 成功:{errCode:0, errMsg:'ok', path, format, width, height, base64, engine}
  • parseContent 成功:{errCode:0, errMsg:'ok', type, title, subtitle, raw, fields:{...}}
  • decodeImage 成功:{errCode:0, errMsg:'ok', codes:[{text, format, hasPoints, engine}], count}
  • diagnose 成功:{errCode:0, errMsg:'ok', canGenerate, canDecode, canScanCamera, supportedFormats, engine}

引擎说明

  1. 相机扫码:Android 调 ScanUtil.startScan() 拉起 Scan Kit 官方界面;ScanKitActivity 默认支持多码,识别到多个码会在预览上绘制多个指示框/箭头,点击即返回该码。结果通过 Activity onActivityResult 回传,插件内部已处理,业务侧无需关心。
  2. 生成码:Android 优先 ScanUtil.buildBitmap(),异常时降级 ZXing;返回的 engine 字段标明实际生效引擎。
  3. 图片解析:统一用 ZXing(整图 + 2x2 分块,按内容去重),无需相机与 HMS。
  4. 鸿蒙端:scanBarcode.startScanForResult() + enableMultiMode: true,同样支持多码点选;生成码为降级模式(鸿蒙官方推荐 ArkUI QRCode 组件绘制)。

集成步骤

  1. 把 uni-scan-pro 放入项目 uni_modules/。
  2. 在项目 manifest.json 声明相机权限(插件 aar 自带 AndroidManifest.xml,无需手动加 Activity):
"app-android": {
  "distribute": {
    "permissions": ["android.permission.CAMERA"]
  }
}
  1. 制作自定义调试基座(发行 → 原生App-制作自定义调试基座),或直接云端打包。
  2. 运行基座切换到「自定义调试基座」再运行。

错误码

码 含义
9020001 参数错误(content/path/base64 为空)
9020002 生成码失败
9020003 图片解码失败
9020004 未识别到码
9020005 文件不可写/不存在
9020006 平台不支持
9020007 内部错误(SDK 未就绪)
9020008 相机权限被拒绝
9020009 用户取消扫码
9020010 相册未选中图片

权限与隐私

  • 相机扫码需 android.permission.CAMERA,由 Scan Kit 在首次扫码时向用户申请,插件不额外收集信息。
  • 码生成、图片解析均在本地完成,不联网、不上传数据。
  • 依赖已内置:utssdk/app-android/libs/ 内已包含华为 Scan Kit 全套依赖(scanplus 及其 17 个传递依赖,共 18 个 aar + 1 个 jar)与 ZXing,插件开箱即用,无需配置 maven 仓库,离线打包也可用。

常见问题

Q:为什么不用内置 uni.scanCode? A:内置扫码只能返回单个码,遇到"一张桌上贴了 5 个二维码,让用户挑一个"的场景无法处理。本插件的 Scan Kit 界面会把同屏所有码都标出来,用户点哪个返回哪个。

Q:标准基座能跑吗? A:不能。Scan Kit 含原生 so 与扫码界面资源,必须自定义基座或正式打包。

Q:华为引擎什么时候生效? A:Android 端 aar 已内置,扫码界面与生成码都走华为引擎,不依赖设备是否装 HMS Core;diagnose() 可查看 huaweiAvailable / canScanCamera。

Q:能识别一张图里的多个码吗? A:可以。decodeImage 先整图解析,失败时按 2x2 分块再解析,按内容去重后返回 codes[]。

更新记录

见 changelog.md。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

相机扫码需 android.permission.CAMERA,由 SDK 在首次扫码时向用户申请;图片解析由业务方传入路径或 base64,读取权限由业务方申请

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件集成华为 Scan Kit 与 ZXing SDK(用于相机扫码、码生成与解析,全部本地处理);不上传用户数据,不采集隐私信息

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。