更新记录
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}
引擎说明
- 相机扫码:Android 调
ScanUtil.startScan()拉起 Scan Kit 官方界面;ScanKitActivity默认支持多码,识别到多个码会在预览上绘制多个指示框/箭头,点击即返回该码。结果通过 ActivityonActivityResult回传,插件内部已处理,业务侧无需关心。 - 生成码:Android 优先
ScanUtil.buildBitmap(),异常时降级 ZXing;返回的engine字段标明实际生效引擎。 - 图片解析:统一用 ZXing(整图 + 2x2 分块,按内容去重),无需相机与 HMS。
- 鸿蒙端:
scanBarcode.startScanForResult()+enableMultiMode: true,同样支持多码点选;生成码为降级模式(鸿蒙官方推荐 ArkUIQRCode组件绘制)。
集成步骤
- 把
uni-scan-pro放入项目uni_modules/。 - 在项目
manifest.json声明相机权限(插件 aar 自带AndroidManifest.xml,无需手动加 Activity):
"app-android": {
"distribute": {
"permissions": ["android.permission.CAMERA"]
}
}
- 制作自定义调试基座(发行 → 原生App-制作自定义调试基座),或直接云端打包。
- 运行基座切换到「自定义调试基座」再运行。
错误码
| 码 | 含义 |
|---|---|
| 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。

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 69
赞赏 0
下载 12775967
赞赏 1960
赞赏
京公网安备:11010802035340号