uni-app x uni.scanCode 扫码 API 完全指南参数、跨端实现原理与实战示例【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app x 提供的uni.scanCode是调用系统扫码能力一维码与二维码的统一接口。本文以 docs/api/scan-code.md 为核心结合仓库内 uni-scanCode 模块源码、uni-camera 组件 与 示例页面系统讲解 API 的参数定义、各平台实现差异、调用链原理与权限注意事项帮助读者在 AppAndroid/iOS/HarmonyOS和小程序平台上快速落地扫一扫功能。一、API 概览与平台兼容性uni.scanCode(options?)用于唤起扫码界面扫描一维码条形码和二维码通过回调返回识别结果。它的底层实现是一个开源的 uvue 页面页面内嵌了camera组件由 camera 组件提供扫码模式鸿蒙和小程序平台则直接调用平台自身提供的扫码 API。| 平台 | 兼容性 | 备注 | | :- | :- | :- | | Web | x | 不支持 | | 微信小程序 | 4.41 | 直接调用 wx.scanCodeUI 不可自定义 | | Android | 4.71 | 基于 camera 组件的自绘扫码界面 | | iOS | 4.71 | 基于 camera 组件的自绘扫码界面 | | HarmonyOS | 4.61 | 直接调用系统 Scan KitUI 不可自定义 |兼容性版本信息以 docs/api/scan-code.md 文档与 interface.uts 中的 uniPlatform 标注 为准。从接口标注还可以看到该 API 在 Android/iOS 上不仅支持 uni-app xunix 4.71也支持传统 uni-appuniVer 为 √微信小程序端 uniVer 同样为 √即 uni-app 和 uni-app x 均可用。二、参数详解ScanCodeOptionsoptions的类型为ScanCodeOptions所有字段均为可选兼容性列中的 Web: x 表示 Web 平台不支持该 API。| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | onlyFromCamera | boolean | 否 | 是否只能从相机扫码不允许从相册选择图片 | | scanType | Arraystring | 否 | 扫码类型可组合多个 | | success | (res: ScanCodeSuccess) void | 否 | 成功回调 | | fail | (res: ScanCodeFail) void | 否 | 失败回调 | | complete | (res: any) void | 否 | 完成回调成功、失败都会执行 |对应到 interface.uts 中的类型定义onlyFromCamera与scanType均允许传入null回调同样以| null声明为可空调用时可以只传需要的字段。scanType 合法值| 合法值 | 说明 | 兼容性 | | :- | :- | :- | | barCode | 一维条形码 | Web: x; 微信小程序: 4.41; Android: 4.71; iOS: 4.71; HarmonyOS: 4.61 | | qrCode | 二维码 | 同上 | | datamatrix | Data Matrix 码 | 同上 | | pdf417 | PDF417 码 | 同上 |在源码中这四个合法值被定义为联合类型ScanCodeSupportedTypes见 interface.uts。需要注意默认不传 scanType 时识别全部类型传了之后只识别指定类型。这一行为在三个平台实现中均有体现Android/iOS 的入口函数将传入的 scanType 用逗号拼接成 query 参数传给扫码页见 app-android/index.uts页面解析时通过isSupportedScanType过滤非法值HarmonyOS 实现中若解析后scanTypes.length 0则回退为[scanCore.ScanType.ALL]见 app-harmony/index.uts。ScanCodeSuccess 返回值| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | result | string | 是 | 识别到的码内容 | | scanType | string | 是 | 识别到的码类型 | | charSet | string | 否 | 所扫码的字符集微信小程序 4.41 支持 | | path | string | 否 | 当所扫的码为当前小程序二维码时返回二维码携带的 path微信小程序 4.41 支持 | | rawData | string | 否 | 原始数据base64 编码微信小程序 4.41 支持 |需要说明的是App 端Android/iOS的ScanCodeSuccess类型在接口文件中仅声明了result与scanType两个必备字段见 interface.uts但扫码页在emitSuccess时会额外携带charset、rawData、scanArea等扩展信息见 scanCode.uvue这些字段通过 UTSJSONObject 透传给回调属于平台实现细节。三、快速上手最小可用示例以下是 hello uni-app x 的官方示例页面 的完整代码与 scan-code.md 文档示例 一致可直接复制使用template view page-head :titletitle/page-head view classuni-padding-wrap uni-common-mt view classuni-title扫码结果/view view v-ifresult classscan-result {{result}} /view view classuni-btn-v button typeprimary clickscan扫一扫/button /view /view /view /template script setup languts const title ref(scanCode) const result ref() const scan () { uni.scanCode({ success: (res: ScanCodeSuccess) { console.log(res: , res); result.value res.result }, fail: (err: ScanCodeFail) { console.log(err: , err); // 需要注意的是小程序扫码不需要申请相机权限 } }); } /script style .scan-result { min-height: 25px; line-height: 25px; } /style要点解读回调类型为ScanCodeSuccess/ScanCodeFail在 uts 中可直接作为类型标注使用该 API不支持 Web需运行到 App 平台体验小程序平台扫码不需要申请相机权限微信小程序扫码由宿主 App 提供能力。进阶限制扫码类型与相册uni.scanCode({ onlyFromCamera: true, // 只允许相机扫码隐藏相册入口 scanType: [qrCode, barCode], // 只识别二维码和一维码 success: (res: ScanCodeSuccess) { console.log(识别结果, res.result, 类型, res.scanType) }, fail: (err) { console.log(扫码失败) }, complete: () { console.log(流程结束) } })从源码可以确认参数的实际走向onlyFromCamera通过 query 传给扫码页后控制相册按钮isShowAlbum的显隐isShowAlbum.value (options[onlyFromCamera] as string) ! true见 scanCode.uvue 的initPageOptions在 HarmonyOS 端则映射为 Scan Kit 的enableAlbum: !options.onlyFromCamera见 app-harmony/index.uts。四、App 端实现原理从 API 调用到 camera 组件的调用链4.1 一个开源的 uvue 扫码页面uni-app x 的扫码 API 本质上是一个uni_modules 模块 对话框页面。调用链如下以 Android/iOS 为例见 app-android/index.uts 与 app-ios/index.uts生成随机uuid构造事件名uni_scan_code_${uuid}_success与..._fail并用uni.$on注册回调调用uni.openDialogPage打开 pages/scanCode/scanCode.uvue以 query 形式传入successEventName、failEventName、onlyFromCamera与scanType扫码页内嵌camera组件resolutionhigh、frame-sizelarge支持flash手电筒并在initdone后启动帧分析startAnalysis()识别成功后页面uni.$emit事件 → 入口函数回调中还原ScanCodeSuccess并依次触发success、complete失败则触发fail、completeuni.openDialogPage打开失败时会通过uni.$off清理已注册的事件监听避免泄漏。4.2 帧识别ML Kit / MLKit 驱动从 scanCode.uvue 的 startAnalysis 可以看到页面通过uni.createCameraContext()订阅相机原始帧onAndroidCameraOriginalFrame/onIosCameraOriginalFrame再把帧交给扫描器处理Android构造AndroidFrameScannerOptions含imageProxy、scanType、autoZoom等调用getAndroidScanner()?.processScanBarCode(options)iOS构造IosFrameScannerOptions含CMSampleBuffer调用getIosScanner()?.processScanBarCode(options)。扫描器来自依赖模块 uni-barcode-scanning其职责是实现 camera 组件modescanCode时的扫码能力仅 Android/iOS 支持。依赖库版本来自 docs/api/scan-code.mdAndroidandroidx.camera:camera-core:1.4.1、com.google.mlkit:barcode-scanning:17.2.0、com.github.albfernandez:juniversalchardet:2.0.4后者用于字符集探测对应返回值中的 charSetiOSpod GoogleMLKit/BarcodeScanning, 6.0.0。文档说明Android/iOS 平台的扫码基于Google 机器学习库对各种一维、二维码都有较好的识别效果。4.3 多码识别与选择 UI当一帧中出现多个码时扫码页会冻结当前帧画面在画面上叠加可点击的选择标记marker提示文案随语言环境变化中/英/西/法见 scanCode.uvue 的 i18n 配置用户点选后返回对应结果同时支持双击画面自动变焦setZoom每次放大 1.2 倍、上限为相机maxZoom。相册扫码未设置onlyFromCamera时走uni.chooseImage选图再调用processScanBarCodeWithPhoto识别图片中的码若返回no barcode found则展示图片预览并提示未识别到一维/二维码。五、HarmonyOS 实现基于系统 Scan Kit与 App 端不同HarmonyOS 直接调用系统扫码能力UI 不可自定义但各种一维、二维码均可识别。核心实现见 app-harmony/index.uts通过canIUse(SystemCapability.Multimedia.Scan.Core)判断系统是否支持扫码能力不支持时直接exec.reject(not support)将 uni 的四种扫码类型映射为 Scan Kit 的scanCore.ScanTypeONE_D_CODE、TWO_D_CODE、DATAMATRIX_CODE、PDF417_CODE不传则默认ScanType.ALL调用scanBarcode.startScanForResult(UTSHarmony.getUIAbilityContext()!, scanOptions, callback)拉起系统扫码界面enableMultiMode: true开启多码模式enableAlbum由onlyFromCamera决定系统返回的原始类型如QR_CODE、EAN_13等 20 余种通过UniScanTypeMap归一化映射为统一返回值。六、权限、隐私与合规注意事项相机权限App 端扫码需要摄像头权限扫码界面的相册图标点击后需要相册读取权限。应用商店合规部分 Android 应用商店要求权限申请前进行声明可使用uni-registerRequestPermissionTips插件在权限申请前展示提示。小程序小程序平台直接调用宿主扫码能力无需申请相机权限。连续扫码场景uni.scanCode是一次性交互扫到即返回如需连续扫码如扫码枪式场景推荐改用 camera 组件 的modescanCode模式。参考示例 camera-scan-code.uvue设置:modescanCode并监听scancode事件即可持续收到识别结果。七、常见问题Web 平台为什么不支持文档兼容性表明确标注 Web 为 x浏览器缺乏统一条码识别与相机扫码协议uni-app x 未在 Web 端实现该 API需要在 App 平台运行体验。scanType 传了没效果请确认传入值必须是barCode/qrCode/datamatrix/pdf417四者之一源码会对非法值做过滤App 端为空时默认全类型识别HarmonyOS 端为空时回退ScanType.ALL。微信小程序的 path / rawData 为什么拿不到这两个字段仅当所扫的码为当前小程序二维码时才有 path 值且需微信小程序 4.41rawData为 base64 编码的原始数据与 App 端返回字段集合不同。识别慢或失败怎么办App 端基于 ML Kit / MLKit 帧识别可在光线不足时点击手电筒图标flash: torch补光或双击画面放大相册识别失败no barcode found会给出图片预览提示。八、深入阅读API 文档docs/api/scan-code.md类型与接口定义interface.uts、protocol.utsAndroid 实现app-android/index.utsiOS 实现app-ios/index.utsHarmonyOS 实现app-harmony/index.uts扫码对话框页面源码pages/scanCode/scanCode.uvue官方示例页面pages/API/scan-code/scan-code.uvue连续扫码camera 组件 scanCode 模式camera-scan-code.uvuecamera 组件文档docs/component/camera.md【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考