在 react-native-vision-camera 中使用 Barcode Scanner 扫码：安装、四种调用方式与 API 详解

在 react-native-vision-camera 中使用 Barcode Scanner 扫码安装、四种调用方式与 API 详解【免费下载链接】react-native-vision-camera A powerful, high-performance React Native Camera library.项目地址: https://gitcode.com/GitHub_Trending/re/react-native-vision-camerareact-native-vision-camera-barcode-scanner是基于 Google ML Kit 的 VisionCamera 扫码插件可对实时相机帧、附加为CameraOutput的会话输出以及静态 Nitro Image 三种数据源进行条形码 / QR 码识别。读完本文你将掌握该插件的完整安装流程含 iOS 最低版本要求、四种实战调用方式、BarcodeScanner核心 API 与返回的Barcode数据结构以及坐标系转换方法。一、安装与依赖配置1. 安装插件与 Nitro Image该插件托管在 packages/react-native-vision-camera-barcode-scanner 目录下通过 npm 安装npm install react-native-vision-camera-barcode-scanner react-native-nitro-imagereact-native-vision-camera-barcode-scanner本插件主体基于 ML Kit 实现扫码能力见 package.json 中的描述 Barcode scanning plugin for react-native-vision-camera powered by ML Kitreact-native-nitro-image提供静态图片扫码所需的Image类型loadImage等 API用于scanCodesInImageAsync(...)。2. 依赖关系VisionCamera Barcode Scanner 依赖两层基础库请确保一并安装VisionCamera Core即react-native-vision-camera本体提供Frame、Camera、CameraSession、CameraOutput、useFrameOutput等基础设施Nitro Modules插件通过 Nitro 混合对象HybridObject与原生层通信安装时会自动带入无需单独操作。注意本文档中的依赖声明与示例均为文档撰写时的仓库现状实际安装时以 npm 上发布的版本为准。3. 最低系统要求iOS 15.5插件的 iOS 实现依赖GoogleMLKit/BarcodeScanning依赖声明版本为9.0.0该依赖要求iOS 最低部署目标为 15.5。如果项目的Podfile中platform :ios低于此版本需要手动调高例如platform :ios, 15.54. 安装原生依赖并重新构建配置完 iOS 部署目标后在项目根目录执行npx pod-install然后重新构建你的应用iOS/Android 均需完整 rebuild因为涉及原生代码与 Nitro 生成代码。二、四种调用方式官方文档 docs/content/docs/barcode-scanner.mdx 给出了四种使用形态按控制粒度从低到高排列如下。方式一CodeScanner /视图组件开箱即用CodeScanner是一个自包含的视图组件内部自动选取默认后置摄像头并挂载扫码输出只需传入barcodeFormats与两个回调即可function App() { const isFocused useIsFocused() return ( CodeScanner isActive{isFocused} barcodeFormats{[all-formats]} onBarcodeScanned{(barcodes) { console.log(Scanned ${barcodes.length} barcodes!) }} onError{(error) { console.error(Error scanning barcodes:, error) }} / ) }从源码 src/views/CodeScanner.tsx 可以看到它的内部实现通过useCameraDevice(back)获取后置设备再用useBarcodeScannerOutput(barcodeScannerOptions)创建输出最终渲染一个Camera device{device} outputs{[output]} /。isActive用于暂停/恢复相机建议结合页面焦点与 App 前后台状态控制style最常见的取值是{ flex: 1 }。方式二useBarcodeScannerOutput挂载为 CameraOutput精确控制会话如果你已经在使用Camera /或CameraSession并希望扫码作为其中的一路输出用useBarcodeScannerOutput(...)创建输出对象后传入outputs数组function App() { const barcodeOutput useBarcodeScannerOutput({ barcodeFormats: [all-formats], onBarcodeScanned(barcodes) { console.log(Scanned ${barcodes.length} barcodes!) }, onError(error) { console.error(Failed to scan barcodes!, error) } }) return ( Camera style{{ flex: 1 }} isActive{true} deviceback outputs{[barcodeOutput]} / ) }useBarcodeScannerOutput的实现见 src/useBarcodeScannerOutput.ts通过useRef保存最新的onBarcodeScanned/onError回调避免闭包过期通过useMemo按barcodeFormats、outputResolution依赖创建输出对象二者变化时才会重建outputResolution默认值为preview。该方法同样适用于命令式的CameraSession场景const camera useCamera({ isActive: true, device: device, outputs: [scannerOutput] })方式三Frame Processor 插件最高控制力如果需要完全掌控扫描时机与坐标系换算可以直接创建BarcodeScanner混合对象在 Frame Processor 中逐帧同步扫描function App() { const barcodeScanner useBarcodeScanner({ barcodeFormats: [all-formats], }) const frameOutput useFrameOutput({ onFrame(frame) { worklet const barcodes barcodeScanner.scanCodes(frame) console.log(Detected ${barcodes.length} barcodes!) frame.dispose() } }) return ( Camera style{{ flex: 1 }} isActive{true} deviceback outputs{[frameOutput]} / ) }useBarcodeScanner在 src/useBarcodeScanner.ts 中基于useMemo按barcodeFormats缓存实例。scanCodes(frame)为同步调用直接返回Barcode[]适合在 worklet 中使用。方式四静态图片扫码scanCodesInImageAsync对于已经存在的图片本地磁盘、打包资源或网络 URL通过react-native-nitro-image的loadImage加载成Image再调用scanCodesInImageAsync异步识别import { loadImage } from react-native-nitro-image import { createBarcodeScanner } from react-native-vision-camera-barcode-scanner async function scanBarcodeImage() { const image await loadImage({ url: https://example.com/barcode.png }) const barcodeScanner createBarcodeScanner({ barcodeFormats: [all-formats], }) try { const barcodes await barcodeScanner.scanCodesInImageAsync(image) console.log(Detected ${barcodes.length} barcodes!) } finally { image.dispose() barcodeScanner.dispose() } }createBarcodeScanner/createBarcodeScannerOutput定义于 src/factory.ts内部通过NitroModules.createHybridObjectBarcodeScannerFactory(BarcodeScannerFactory)获取原生工厂。注意最后务必dispose()释放Image与扫描器。三、BarcodeScanner 核心 API接口定义见 src/specs/BarcodeScanner.nitro.tsAndroid 端实现位于 android/src/main/java/com/margelo/nitro/camera/barcodescanner/HybridBarcodeScanner.kt。方法同步/异步说明scanCodes(frame: Frame): Barcode[]同步在给定Frame中检测条码返回坐标相对于Frame坐标系scanCodesAsync(frame: Frame): PromiseBarcode[]异步异步检测在 Promise 落定前不得调用frame.dispose()scanCodesInImageAsync(image: Image): PromiseBarcode[]异步在静态Image中检测条码坐标相对于该Image坐标系坐标系转换由于scanCodes返回的坐标位于 Frame/Image 坐标系若需将其映射到界面上的预览视图坐标需要两步转换参见 BarcodeScanner.nitro.ts 中的示例const scanner // ... const frame // ... const previewView // ... const barcodes scanner.scanCodes(frame) for (const barcode of barcodes) { console.log(Barcode value:, barcode.rawValue) for (const point of barcode.cornerPoints) { const cameraPoint frame.convertFramePointToCameraPoint(point) const previewPoint previewView.convertCameraPointToViewPoint(cameraPoint) console.log(Corner Point:, previewPoint) } }先用Frame.convertFramePointToCameraPoint(...)将 Frame 坐标转为 Camera 坐标再用PreviewViewMethods.convertCameraPointToViewPoint(...)将 Camera 坐标转为预览视图坐标。四、Barcode 数据结构与格式配置1. Barcode 对象字段每个检测到的条码是一个 Nitro 混合对象Barcode接口定义见 src/specs/Barcode.nitro.ts字段类型说明formatBarcodeFormat条码的视觉格式如qr-code、code-128boundingBoxRect条码外接矩形坐标相对于输入 Frame/ImagecornerPointsPoint[]条码四角点坐标相对于输入 Frame/ImagedisplayValuestring \| undefined面向用户的友好格式值rawBytesArrayBuffer \| undefined原始字节内容rawValuestring \| undefined原始字符串值valueTypeBarcodeValueType内容语义类型URL、电话、WiFi 配置等2. 支持的条码格式BarcodeFormatBarcodeFormat定义于 src/specs/BarcodeFormat.ts取值包括unknown、code-128、code-39、code-93、codabar、data-matrix、ean-13、ean-8、itf、qr-code、upc-a、upc-e、pdf-417、aztec。配置扫描目标时使用TargetBarcodeFormat它是除unknown外所有格式的联合类型另加all-formats表示识别全部格式。3. 收窄格式以提升性能官方文档 barcode-scanner.mdx 明确指出示例中默认的[all-formats]会检测所有格式为了提升性能应当只声明你真正需要的格式。例如电商场景通常只需[code-128]二维码场景只需[qr-code]。这一配置最终在 Android 端映射为 ML Kit 的BarcodeScannerOptions.Builder.setBarcodeFormats(...)见 android/src/main/java/com/margelo/nitro/camera/barcodescanner/extensions/BarcodeScannerOptionstoMLBarcodeScannerOptions.kt格式越少ML Kit 的识别路径越短。4. 内容语义类型BarcodeValueTypeBarcodeValueType描述条码内容“是什么”而非视觉格式定义于 src/specs/BarcodeValueType.tsunknown、contact-info、email、isbn、phone、product、sms、text、url、wifi、geo、calendar-event、driver-license。例如识别到 WiFi 配置码时valueType wifi识别到网址时valueType url可用于业务分流。5. 输出分辨率CameraOutput 专属当使用useBarcodeScannerOutput/createBarcodeScannerOutput时可额外配置outputResolution定义见 src/specs/BarcodeScannerOutputResolution.ts取值行为适用场景preview默认优先使用预览尺寸缓冲延迟更低高频实时扫码full优先使用最高可用缓冲细节更好需要识别远处/小尺寸条码选项接口完整定义见 src/specs/BarcodeScannerFactory.nitro.tsBarcodeScannerOptions只需barcodeFormatsBarcodeScannerOutputOptions额外包含outputResolution、onBarcodeScanned、onError。五、平台能力与验证跨平台与仅支持 iOS 的 Object Output 不同Barcode Scanner 在 iOS 与 Android 双平台均可用见 barcode-scanner.mdx验证方式可扫描文档提供的 Code 128 示例图即本文开头插图验证CodeScanner /是否工作正常仓库内 apps/simple-camera/src/assets/code-128-mrousavy.png 与 apps/simple-camera/src/assets/qr-code-margelo.png 也是现成的测试素材可用于scanCodesInImageAsync的静态图片验证Harness 测试仓库在 apps/simple-camera/tests/visioncamera.barcode-scanner.harness.ts 中提供了扫码能力的测试 harness可供集成测试参考。六、小结react-native-vision-camera-barcode-scanner将 Google ML Kit 的条码识别能力以四种形态接入 VisionCamera 生态零配置的CodeScanner /视图、可挂载会话的CameraOutput、逐帧控制的 Frame Processor 同步扫描以及针对静态图片的异步识别。安装时牢记 iOS 部署目标需 ≥ 15.5使用时尽量收窄barcodeFormats以换取性能并依据BarcodeValueType对识别结果做业务分流——这便是构建高质量扫码体验的完整路径。【免费下载链接】react-native-vision-camera A powerful, high-performance React Native Camera library.项目地址: https://gitcode.com/GitHub_Trending/re/react-native-vision-camera创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考