qr_code_scanner_plus

本项目基于 qr_code_scanner_plus 开发，已完成 HarmonyOS（OpenHarmony）平台适配，提供二维码 / 条形码扫描能力。

1. 安装与使用

1.1 安装方式

进入到工程目录并在 pubspec.yaml 中添加以下依赖：

dependencies:
  qr_code_scanner_plus:
    git:
      url: https://gitcode.com/CPF-Flutter/fluttertpc_qr_code_scanner_plus
      ref: TAG #根据下面框架版本选择TAG 名称

1.2 TAG 版本对应表

Flutter 框架版本	TAG	分支
3.22	2.0.10_1-ohos-1.0.1	master
3.27	2.0.10_1-ohos-1.0.1	master
3.35	2.0.10_1-ohos-1.0.1	master

当前鸿蒙化版本统一使用 TAG 2.0.10_1-ohos-1.0.0 与 master 分支；上表按 Flutter 框架版本列出已验证组合，升级时请保持 TAG 与目标 OHOS Flutter 版本一致。

执行命令：

flutter pub get

1.3 版本升级与迁移

• 从旧 TAG 升级：修改 pubspec.yaml 中 ref 为目标 TAG（当前为 2.0.10_1-ohos-1.0.0），随后执行 flutter pub get 即可。
• 兼容性提示：升级 HarmonyOS Flutter 框架版本时，请确认本库的 TAG 与目标 Flutter OHOS 版本一致（见上方对应表），否则可能出现平台视图（PlatformView）加载异常。
• Breaking change：当前版本接口与上游 qr_code_scanner_plus Dart API 保持一致，鸿蒙化仅扩展了 OHOS 平台实现，不改变 Dart 层签名。

1.4 使用案例

完整使用案例详见 example。

2. 约束与限制

2.1 兼容性

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

1. Flutter: 3.22.4-ohos-1.1.3; SDK: 5.0.5(17); IDE: DevEco Studio: 6.1.1.290; ROM: 6.1.0.135.SP8;
2. Flutter: 3.27.5-ohos-1.0.6; SDK: 5.0.5(17); IDE: DevEco Studio: 6.1.1.290; ROM: 6.1.0.135.SP8;
3. Flutter: 3.35.8-ohos-0.0.1; SDK: 5.0.5(17); IDE: DevEco Studio: 6.1.1.290; ROM: 6.1.0.135.SP8;

2.2 OHOS 环境配置

使用本库前，请按以下步骤配置 OHOS 开发环境：

1. 安装 DevEco Studio：从华为开发者官网下载并安装对应版本的 DevEco Studio（见上方兼容性列表）。
2. 配置 OpenHarmony SDK：在 DevEco Studio 中通过 File > Settings > SDK 安装匹配版本的 HarmonyOS / OpenHarmony SDK。
3. 安装命令行工具：确保 ohpm（OpenHarmony 包管理器）、hvigor（构建工具）已随 DevEco Studio 安装并加入 PATH。
4. 编译 ohos 工程：在 example/ 目录执行 flutter build hap --debug 构建 HAP；如需单独构建 ohos 模块，使用 hvigorw assembleHar。
5. 真机运行：连接 HarmonyOS 设备，配置签名（*.p12 / *.p7b），在 DevEco Studio 中运行 example 工程。

2.3 所需权限

扫码需要访问设备摄像头，该能力在 HarmonyOS 上为系统授权权限。宿主应用（非插件模块本身）需在其 module.json5 中声明以下权限：

权限名	授权级别	说明
ohos.permission.CAMERA	user_grant	扫码需要打开相机预览流，必须声明。

在宿主应用模块的 entry/src/main/module.json5 的 requestPermissions 中声明，示例：

"requestPermissions": [
  {
    "name": "ohos.permission.CAMERA",
    "reason": "$string:camera_permission_desc",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

2.4 平台差异（OHOS）

能力	OHOS 支持	说明
scanInvert / invertScan	空操作（no-op，无实际效果）	仅 Android 支持反色扫描；ScanKit 无对应 API
formatsAllowed	是	通过 startScan 传递条码格式索引给 ScanKit
rawBytes	部分支持	ScanKit 不提供原始字节，回调中该字段为 null
updateDimensions / changeScanArea	是	将扫描区域裁剪后送入 ScanKit，与 Android setFramingRect 行为对齐
多 QRView 实例	是	通过 viewId 注册表隔离各 PlatformView

3. API

3.1 接口列表

Name	Description	Type	Input	Output	ohos Support
getCameraInfo	获取当前使用的相机信息	function		Future	yes
flipCamera	切换前后相机	function		Future	yes
getFlashStatus	获取闪光灯状态	function		Future<bool?>	yes
toggleFlash	切换闪光灯开关	function		Future	yes
pauseCamera	暂停相机和条形码扫描	function		Future	yes
stopCamera	停止相机和条形码扫描	function		Future	yes
resumeCamera	恢复相机和条形码扫描	function		Future	yes
getSystemFeatures	获取设备支持的功能	function		Future	yes
scannedDataStream	扫描结果的数据流	property		Stream	yes
hasPermissions	当前是否已获得相机权限	property		bool	yes
disposed	控制器是否已释放	property		bool	yes
updateDimensions	更新扫描区域尺寸（Android/OHOS）	static function	GlobalKey, MethodChannel, overlay	Future	yes
changeScanArea	OHOS 原生侧接收扫描框参数并裁剪识别区域	native method	scanAreaWidth, scanAreaHeight, cutOutBottomOffset	bool	yes
scanInvert	反色扫描开关（仅 Android；OHOS 上为空操作 no-op）	function	isScanInvert: bool	Future	no（空操作）
dispose	已废弃的空操作（no-op）；控制器随视图自动释放	function		void	yes
onPermissionSet	相机权限授予/拒绝时的回调	callback		(QRViewController, bool)	yes
formatsAllowed	QRView 构造参数：允许的条码格式列表	field	List	—	yes
QRViewCreatedCallback	QRView 创建完成回调 typedef	type	QRViewController	void	yes
PermissionSetCallback	权限结果回调 typedef	type	QRViewController, bool	void	yes

3.1.1 QrScannerOverlayShape（扫描区域覆盖层）

Name	Description	Type	ohos Support
borderColor	边框颜色	field	yes
borderWidth	边框宽度	field	yes
overlayColor	遮罩颜色	field	yes
borderRadius	边框圆角	field	yes
borderLength	边框角长度	field	yes
cutOutSize	扫描框尺寸（同时设置宽高）	field	yes
cutOutWidth	扫描框宽度	field	yes
cutOutHeight	扫描框高度	field	yes
cutOutBottomOffset	扫描框底部偏移	field	yes
dimensions	形状边距	property	yes
getInnerPath / getOuterPath / paint / scale	绘制与缩放方法	method	yes

3.1.2 数据类型

类型	说明	ohos Support
Barcode	扫描结果：code（String?）、format（BarcodeFormat）、rawBytes（List?；OHOS 为 null）	partially
BarcodeFormat	18 种条码类型枚举（aztec、qrcode、code128、ean13 等）及 unknown	yes
BarcodeTypesExtension	扩展：asInt()、formatName、fromString()	yes
CameraFacing	枚举：back、front、unknown	yes
SystemFeatures	设备能力：hasFlash、hasBackCamera、hasFrontCamera	yes
CameraException	平台错误对象，含 code（String）与 description（String?），相机失败时抛出	yes

3.2 调用链路（导入 → 创建 → 使用）

import 'package:qr_code_scanner_plus/qr_code_scanner_plus.dart';

class ScanPage extends StatefulWidget {
  const ScanPage({super.key});
  @override
  State<ScanPage> createState() => _ScanPageState();
}

class _ScanPageState extends State<ScanPage> {
  final GlobalKey qrKey = GlobalKey(debugLabel: 'QR');
  QRViewController? controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: QRView(
        key: qrKey,
        // OHOS：通过 formatsAllowed 限制 ScanKit 识别的条码类型
        formatsAllowed: const [BarcodeFormat.qrcode, BarcodeFormat.code128],
        overlay: QrScannerOverlayShape(
          cutOutWidth: 250,
          cutOutHeight: 250,
          borderColor: Colors.red,
        ),
        onPermissionSet: (ctrl, granted) {
          // OHOS：权限授予/拒绝均会回调
        },
        onQRViewCreated: (QRViewController ctrl) {
          controller = ctrl;
          ctrl.scannedDataStream.listen((Barcode barcode) {
            // barcode.code 为扫描内容
          });
        },
      ),
    );
  }
}

// 通过 controller 调用相机 / 闪光灯控制接口
// await controller!.flipCamera();        // 切换前后相机
// await controller!.toggleFlash();       // 切换闪光灯
// final status = await controller!.getFlashStatus(); // 获取闪光灯状态
// await controller!.pauseCamera();       // 暂停相机
// await controller!.resumeCamera();      // 恢复相机
// final features = await controller!.getSystemFeatures(); // 获取设备能力
// await QRViewController.updateDimensions(qrKey, channel, overlay: overlay); // 更新扫描区域

4. 遗留问题

无

5. 开源协议

本项目基于 The MIT License，请自由地享受和参与开源。