@capacitor/barcode-scanner

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/barcode-scanner是capacitor生态系统中的核心插件，基于Scan Kit（扫码服务）开发，提供高效、精准的二维码及条形码扫描能力，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档只说明在OpenHarmony系统中的使用。

API 提供 scanBarcode 方法，可直接调起原生的扫码界面，支持多种扫码模式和界面定制，满足各类扫码场景需求。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/barcode-scanner

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/barcode-scanner

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/barcode-scanner",
  "classpath": "CapacitorBarcodeScanner"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(CapacitorBarcodeScanner)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  CapacitorBarcodeScanner
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/CapacitorBarcodeScanner目录下的CapacitorBarcodeScanner.h、CapacitorBarcodeScanner.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/CapacitorBarcodeScanner目录下。

将源码中src/main/ets/components/CapacitorBarcodeScanner目录下的CapacitorBarcodeScanner.ets文件引入到capacitor模块中src/main/ets/components/CapacitorBarcodeScanner目录下。

4. 添加 ArkTS 配置

在capacitor模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

{
  "buildOption": {
    // ...
    "arkOptions": {
      "runtimeOnly": [
        // ...
        "./src/main/ets/components/CapacitorBarcodeScanner/CapacitorBarcodeScanner.ets"
        // ...
      ]
    }
  }
}

卸载

# 卸载 barcode-scanner 插件
hionic plugin remove @capacitor/barcode-scanner

约束与限制

兼容性

在以下版本中已测试通过：

• capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony系统中，扫码功能需申请相机权限，需在主工程的 module.json5 的 requestPermissions 中添加 ohos.permission.CAMERA 权限，配置示例如下：

{
  "name": "ohos.permission.CAMERA",
  "reason": "$string:camera_reason",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

使用示例

示例1：基础扫码并处理结果

import { CapacitorBarcodeScanner } from '@capacitor/barcode-scanner';

const startScan = async () => {
  try {
    const { ScanResult, format } = await CapacitorBarcodeScanner.scanBarcode({
      scanInstructions: '请对准条码',
      scanOrientation: 1
    });
    console.log(`扫码结果: ${ScanResult}, 格式: ${format}`);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('扫码出错:', errorMsg);
  }
};

示例2：高级扫码（显示切换摄像头按钮）

import { CapacitorBarcodeScanner } from '@capacitor/barcode-scanner';

const startAdvancedScan = async () => {
  try {
    const result = await CapacitorBarcodeScanner.scanBarcode({
      scanInstructions: '请扫码',
      web: {
        showCameraSelection: true
      }
    });
    console.log('结果:', result.ScanResult);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('扫码出错', errorMsg);
  }
};

使用说明

CapacitorBarcodeScanner是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用。

| 方法名 | 返回类型 | 描述 | 备注 | |---------------------------------------------------|--------------------------------------------|------------|---------| | scanBarcode(options: ScanOptions) | Promise<BarcodeData> | 调起扫码界面进行扫码 | 需申请相机权限 |

数据结构

ScanOptions

调用 scanBarcode 方法时的入参对象，用于配置扫码界面和扫码规则。

| 属性 | 类型 | 描述 | 默认值 | 备注 | |-------------------------|---------|-------------------------------------------|---------|----------------| | hint | number | 提示信息类型。可选值参考 ScanType | 17 | 无 | | scanInstructions | string | 扫码界面上显示的指示文字 | '扫描二维码' | 无 | | scanButton | boolean | 是否在界面上显示“扫码”按钮。如果为 true，则需要用户点击按钮后才处理结果 | false | 无 | | scanText | string | 扫码按钮上的文字 | '立即扫描' | 无 | | cameraDirection | number | 摄像头方向。1: 后置摄像头, 2: 前置摄像头 | 1 | 无 | | scanOrientation | number | 屏幕方向。1: 竖屏, 2: 横屏, 3: 自适应 | 1 | 无 | | web.showCameraSelection | boolean | 是否显示切换摄像头按钮 | false | 需在 web 对象内定义 |

ScanType

hint 属性的可选值定义，用于指定扫描时识别的条码类型，基于Scan Kit实现。

| 名称 | 数值 | OpenHarmony适配支持 | 说明 | |-------------------|----|-----------------|--------------------| | QR_CODE | 0 | ✅ 支持 | 二维码 | | AZTEC | 1 | ✅ 支持 | Aztec 码 | | CODABAR | 2 | ✅ 支持 | 库德巴码 | | CODE_39 | 3 | ✅ 支持 | Code 39 条形码 | | CODE_93 | 4 | ✅ 支持 | Code 93 条形码 | | CODE_128 | 5 | ✅ 支持 | Code 128 条形码 | | DATA_MATRIX | 6 | ✅ 支持 | Data Matrix 码 | | MAXICODE | 7 | ❌ 不支持 | MaxiCode（暂不支持） | | ITF | 8 | ✅ 支持 | ITF-14 条形码 | | EAN_13 | 9 | ✅ 支持 | EAN-13 商品条码 | | EAN_8 | 10 | ✅ 支持 | EAN-8 商品条码 | | PDF_417 | 11 | ✅ 支持 | PDF417 二维码 | | RSS_14 | 12 | ❌ 不支持 | RSS-14（暂不支持） | | RSS_EXPANDED | 13 | ❌ 不支持 | RSS Expanded（暂不支持） | | UPC_A | 14 | ✅ 支持 | UPC-A 商品条码 | | UPC_E | 15 | ✅ 支持 | UPC-E 商品条码 | | UPC_EAN_EXTENSION | 16 | ❌ 不支持 | UPC/EAN 扩展码（暂不支持） | | ALL | 17 | ✅ 支持 | 所有支持的码制（推荐使用） |

使用建议：

• 默认值为 17（ALL），可识别所有支持的条码类型，适用于大多数场景。

• 如需提高识别速度和准确率，建议指定具体的条码类型。

• 基于 Scan Kit 实现，部分码制（MAXICODE、RSS_14、RSS_EXPANDED、UPC_EAN_EXTENSION）暂不支持。

BarcodeData

scanBarcode 方法返回的结果对象，包含扫码结果及条码格式信息。

| 属性 | 类型 | 描述 | |------------|--------|-------------------------------------------------------------------------------| | ScanResult | string | 扫描到的条码/二维码内容字符串 | | format | number | 扫描到的条码格式代码（数字），对应 ScanType 表中的数值（如 0 表示 QR_CODE，9 表示 EAN_13） |

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。