rn-qr-generator

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

项目介绍

rn-qr-generator（鸿蒙适配包 @hxa-rn/rn-qr-generator 2.0.0-beta.1）是 React Native 二维码生成与识别工具库，基于 TurboModule RNQrGenerator 提供：

• generate：将文本编码为二维码 PNG，支持宽高、前/背景色、纠错等级、内边距、base64 输出与自定义文件名；
• detect：从本地图片 uri 或 base64 数据识别二维码及多种一维/二维条码，返回内容与 type 字段。

本库含鸿蒙原生 HAR（harmony/qr_generator/），编解码引擎为 @ohos/zxing。

集成指南

安装

npm install @hxa-rn/rn-qr-generator

业务代码通过 harmony.alias 仍使用原包名导入：

import RNQRGenerator from 'rn-qr-generator';

依赖要求

| 项 | 要求 | |----|------| | react-native | >=0.72（peerDependencies） | | react | *（peerDependencies） | | Node.js | >=18（engines） |

Autolinking

本模块支持 RNOH Autolinking（harmony.autolinking 配置 QrGeneratorPackage / CMake 目标 qr_generator）。工程已启用 Autolinking 时，无需手动注册。

Autolink 未生效时的备选（手动注册）：

1. 在 entry/oh-package.json5 添加 HAR 依赖：

"dependencies": {
  "@hxa-rn/rn-qr-generator": "file:../../node_modules/@hxa-rn/rn-qr-generator/harmony/qr_generator.har"
}

2. 在 entry/src/main/cpp/CMakeLists.txt 添加：

add_subdirectory("${OH_MODULES_DIR}/@hxa-rn/rn-qr-generator/src/main/cpp" ./qr_generator)
target_link_libraries(rnoh_app PUBLIC qr_generator)

3. C++ 侧 PackageProvider.cpp 注册 QrGeneratorPackage；ETS 侧 RNPackagesFactory.ets 注册 QrGeneratorPackage（自 @hxa-rn/rn-qr-generator 导入）。 执行 ohpm install --all 后重新编译 HAP。

使用说明

生成二维码

import RNQRGenerator from 'rn-qr-generator';

try {
  const result = await RNQRGenerator.generate({
    value: 'https://example.com/测试',
    width: 240,
    height: 240,
    backgroundColor: 'white',
    color: 'black',
    correctionLevel: 'M',
    base64: true,
    padding: { top: 10, left: 10, bottom: 10, right: 10 },
    fileName: 'my_qr',
  });
  // result: { uri: 'file://...', width, height, base64? }
} catch (e) {
  // value 缺失时 reject: Property "value" is missing
  console.error(String(e));
}

识别二维码 / 条码

uri 与 base64 至少传一项；同时传入时以 uri 为准。

import RNQRGenerator from 'rn-qr-generator';

try {
  // 方式 A：本地图片路径
  const scan = await RNQRGenerator.detect({ uri: 'file:///data/storage/.../qr.png' });
  // 方式 B：base64 图像数据（与 uri 同时传入时以 uri 为准）
  // const scan = await RNQRGenerator.detect({ base64: '<PNG base64 字符串>' });
  // 无识别结果：成功返回空数组，不 reject
  // scan: { values: [], type: '' }
} catch (e) {
  // uri 与 base64 都缺失时 reject: Property "uri" or "base64" are missing
  // 图片不存在或读取失败：reject，如 IMAGE_NOT_FOUND
  console.error(String(e));
}

从相册选图后识别时，需自行接入 @react-native-ohos/react-native-image-picker（或等价能力）获取本地 uri，再调用 detect({ uri })。

接口文档

RNQRGenerator.generate(options)

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | value | string | 是 | - | 待编码文本 | | width | number | 否 | 100 | 图片宽（px）；须为 10-2000 的整数，否则 JS 层 reject | | height | number | 否 | 100 | 图片高（px）；须为 10-2000 的整数，否则 JS 层 reject | | backgroundColor | string | 否 | 'white' | 背景色 | | color | string | 否 | 'black' | 前景色 | | base64 | boolean | 否 | false | 是否返回 PNG base64 | | padding | {top?,left?,bottom?,right?} | 否 | 各边 0 | 内边距（px） | | fileName | string | 否 | UUID | 输出文件名（无扩展名，库追加 .png） | | correctionLevel | 'L'\|'M'\|'Q'\|'H' | 否 | 'H' | 纠错等级 |

返回 Promise<{ uri: string; width: number; height: number; base64?: string }>

RNQRGenerator.detect(options)

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | uri | string | 条件必填 | 本地图片路径；与 base64 同时存在时优先使用 | | base64 | string | 条件必填 | PNG 等图像数据的 base64 |

返回 Promise<{ values: string[]; type: string }>

type 覆盖 QRCode、Code128、Ean13、DataMatrix、PDF417 等 17 种格式；无结果时 values=[]、type=''；未知格式时 type 为空字符串。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18（运行 Example 建议 >= 20，见 example/package.json） | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 13+（example/harmony 的 compatibleSdkVersion 为 5.0.1(13)） |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/rn-qr-generator.git
cd rn-qr-generator
git checkout br_rnoh0.72

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

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 生成 JS Bundle

npm run dev

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

4. 安装鸿蒙依赖

cd harmony
ohpm install

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 首次构建请在 File -> Project Structure -> Signing Configs 勾选 Automatically generate signature，Apply 后 Sync
• 等待 Sync 完成

6. 编译并运行 HAP

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

注意：Example 已预置 Autolinking Package 注册、Metro alias 与 HAR 依赖，无需手动 Link。编 HAP 前必须先执行 npm run dev。

约束与限制

| 项目 | 说明 | | --- | --- | | React Native / RNOH | 对等依赖 react-native >= 0.72。Example 使用 [email protected] 与 @react-native-oh/[email protected]（TurboModule 新架构） | | HarmonyOS SDK | example/harmony 的 compatibleSdkVersion 为 5.0.1(13)；example_auto 为 6.0.1(21) | | Node.js | 根目录 engines.node 为 >=18；运行 Example 建议 >=20 | | 权限 | 库 HAR requestPermissions 为空；生成文件写入应用沙箱 cacheDir。从相册识别需业务侧自行申请媒体访问权限 | | 架构 | TurboModule 新架构，支持 RNOH Autolinking；业务侧按 harmony.alias 以 rn-qr-generator 导入 | | 多码识别 | 鸿蒙端当前仅返回单码结果（values 长度通常为 1），与 Android decodeMultiple 多码语义存在差异 | | 大图识别 | 原生层对解码图片降采样（最长边 1280px），避免 OOM | | fileName | 鸿蒙端避免重复追加 .png 扩展名，与 Android 行为略有差异 |

开源license

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

问题反馈渠道

• GitCode 仓库：https://gitcode.com/hxa-rn/rn-qr-generator
• Issue：https://gitcode.com/hxa-rn/rn-qr-generator/issues