vision-camera-code-scanner

本项目基于 vision-camera-code-scanner 开发。如果在使用过程中有任何问题，欢迎在 AtomGit 提交 Issue，会及时跟进。

项目介绍

@hxa-rn/vision-camera-code-scanner 是 vision-camera-code-scanner 的鸿蒙（OpenHarmony）适配包，当前规范版本号为 0.2.4。

本模块采用 js-only 纯 JS 重实现（无原生代码、不生成 HAR）。鸿蒙版 @react-native-ohos/react-native-vision-camera v4 不提供 Frame Processor 插件机制，因此改为在 JS 层包装 vision-camera 内置 useCodeScanner / Camera.codeScanner（底层 Scan Kit customScan）实现实时扫码。

鸿蒙适配包版本	原始库版本	支持 RN 版本	Autolink	编译 API 版本
0.2.4	0.2.0	0.72	是	API 12+

集成指南

npm install @hxa-rn/vision-camera-code-scanner @react-native-ohos/react-native-vision-camera@~4.0.3

鸿蒙端模块通过 harmony.alias 将 vision-camera-code-scanner 重定向到 @hxa-rn/vision-camera-code-scanner，react-native-vision-camera 重定向到 @react-native-ohos/react-native-vision-camera。源码中 import 名保持不变。

模块为 js-only，无原生 HAR；依赖的原生能力由 @react-native-ohos/react-native-vision-camera 提供，其 Autolink 自动完成注册。

使用说明

import { useEffect } from 'react';
import { StyleSheet } from 'react-native';
import { Camera, useCameraDevice } from 'react-native-vision-camera';
import { useScanBarcodes, BarcodeFormat } from 'vision-camera-code-scanner';

export default function App() {
  const device = useCameraDevice('back');
  const [codeScanner, barcodes, clearBarcodes] = useScanBarcodes([
    BarcodeFormat.ALL_FORMATS,
  ]);

  useEffect(() => {
    Camera.requestCameraPermission();
  }, []);

  useEffect(() => {
    return () => {
      clearBarcodes();
    };
  }, [clearBarcodes]);

  return (
    device != null && (
      <Camera
        style={StyleSheet.absoluteFill}
        device={device}
        isActive={true}
        codeScanner={codeScanner}
      />
    )
  );
}

鸿蒙端 API 变更：返回值从 [frameProcessor, barcodes] 变为 [codeScanner, barcodes, clearBarcodes]。调用方需将 codeScanner 传给 <Camera codeScanner={codeScanner}>。停止扫描或组件卸载时应调用 clearBarcodes()，避免下次开始扫描时把上次结果当作新识别上报。barcodes 为当前识别结果列表，可按业务自行展示。

接口文档

useScanBarcodes 返回值变更

平台	返回值	传给 Camera 的属性
Android / iOS	[frameProcessor, barcodes]	<Camera frameProcessor={fp} />
HarmonyOS	[codeScanner, barcodes, clearBarcodes]	<Camera codeScanner={sc} />

属性 / API

API	描述	参数	返回值	HarmonyOS 支持
useScanBarcodes	声明式扫码钩子	types: BarcodeFormat[]、options?: CodeScannerOptions	[CodeScanner, Barcode[], () => void]	✅
scanBarcodes	Frame Processor 工作集函数	frame、types、options	Barcode[]	❌（抛错 stub）
BarcodeFormat	条码格式枚举	—	—	✅（数值不变）
CodeScannerOptions.checkInverted	反色条码识别	boolean	—	❌（忽略）
Barcode.content 结构化解析	联系人/WiFi/日历/驾照等	—	—	⚠️ 降级为 {type: TEXT, data: rawValue}

不支持功能（明确降级）

1. scanBarcodes 工作集函数：鸿蒙 vision-camera v4 无 Frame Processor 插件机制，请使用 useScanBarcodes 返回的 codeScanner。
2. checkInverted 反色条码：Scan Kit customScan / decodeImage 均无图像取反识别选项，该选项在鸿蒙端被忽略。
3. 条码内容结构化解析：Scan Kit ScanResult 仅返回 originalValue / scanType / scanCodeRect / cornerPoints，Barcode.content 统一降级为 { type: BarcodeValueType.TEXT, data: rawValue }。

上游 codeType→ScanType 映射缺陷补偿

鸿蒙版 vision-camera（4.0.3 / 4.7.1）ScanManager.codeType 数组多插了 'itf-14' 条目，导致 QR/PDF417/UPC_A/UPC_E 四种格式偏移 1。本模块在 JS 层实现双向补偿映射：

• 请求方向：QR_CODE→'pdf-417'、PDF417→'itf-14'、UPC_A→'qr'、UPC_E→'upc-a'
• 上报方向：反向翻译回原 BarcodeFormat

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>= 18
DevEco Studio	5.0+
HarmonyOS SDK	API 12+

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/vision-camera-code-scanner.git
cd vision-camera-code-scanner
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/vision-camera-code-scanner@0.2.4，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example          # 或 example_auto
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 或 example_auto/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。相机权限 ohos.permission.CAMERA 已在 Example 的 entry module.json5 中声明。

约束与限制

兼容性

• RNOH: 0.72
• HarmonyOS SDK: API 12+
• DevEco Studio: 5.0+
• 依赖 @react-native-ohos/react-native-vision-camera ~4.0.3（RN 0.72 线）

权限

• 宿主应用需声明 ohos.permission.CAMERA（本库不单独声明系统权限）

已知差异

• 鸿蒙内置 codeScanner（Scan Kit customScan）会叠加自定义扫码界面（扫描框/闪光灯/相册入口），视觉表现与 Android/iOS 的无 UI 帧处理器插件不同。
• boundingBox / cornerPoints 来自 Scan Kit 的 scanCodeRect（画面坐标，不是二维码 payload）。
• useCameraDevice('back') / Camera.requestCameraPermission() 返回 'granted' 等 v4 权限语义（非 v2 的 'authorized'）。
• customScan 不支持并行调用，需按 Camera 生命周期启停。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/vision-camera-code-scanner

https://gitcode.com/hxa-rn/vision-camera-code-scanner/issues