Flutter for OpenHarmony 扫一扫实战：从功能接入到踩坑修复全记录

这篇文章记录了我在一个 Flutter + OpenHarmony 项目中落地“扫一扫”功能的完整过程。hvigoruser_grant权限缺少reasonusedScene页面输入交互异常：弹层无法交互，随后出现崩溃最终方案是：先打通 Flutter 侧流程并提供降级路径，再按 OpenHarmony 规范补齐权限，最后用“无 controller 输入”规避平台兼容问题。先闭环再完善：先让用户

这个萌新有点帅

621人浏览 · 2026-02-24 20:10:21

这个萌新有点帅 · 2026-02-24 20:10:21 发布

关键词：Flutter、OpenHarmony、MethodChannel、权限配置、扫码、问题排查

摘要

这篇文章记录了我在一个 Flutter + OpenHarmony 项目中落地“扫一扫”功能的完整过程。
不仅包含功能实现思路，还重点复盘了两个典型问题：

hvigor 构建失败：user_grant 权限缺少 reason / usedScene
页面输入交互异常：弹层无法交互，随后出现 TextEditingController disposed 崩溃

最终方案是：先打通 Flutter 侧流程并提供降级路径，再按 OpenHarmony 规范补齐权限，最后用“无 controller 输入”规避平台兼容问题。

一、需求与目标

项目首页已有“扫一扫”按钮，但没有实际行为。
目标是实现一个“可上线联调”的版本：

点击“扫一扫”进入扫码流程
支持扫码结果展示与复制
原生扫码能力未接入时也能可用（降级输入）
保证 OpenHarmony 构建通过、页面交互稳定

二、实现策略：先闭环，再增强

我采用的是渐进式实现，而不是一开始就把所有端能力做满：

先打通入口与页面流转（用户可操作）
用 MethodChannel 预留原生扫码接口（后续可无缝补齐）
原生未接入时自动降级到手动输入（保障功能可用）
针对平台报错和交互问题逐个修复

这套策略的核心是：先确保业务流程可跑通，再处理平台细节与兼容性。

三、核心实现

1）首页接入扫一扫入口

在首页快捷功能区，把“扫一扫”按钮改为页面跳转：

文件：lib/pages/home/home_page.dart
行为：点击后 Navigator.push 到 ScanPage

  _buildActionButton(
              label: '扫一扫',
              icon: Icons.qr_code_scanner,
              onPressed: () => Navigator.of(
                context,
              ).push(MaterialPageRoute(builder: (_) => const ScanPage())),
  ),

2）新增扫码页：统一处理扫码与降级

新增页面：

文件：lib/pages/scan/scan_page.dart

页面能力包括：

调用 MethodChannel('app.scan/qr') 的 scan 方法
拿到结果后展示在页面中
支持“一键复制结果”
如果抛出 MissingPluginException（原生未实现），自动进入手动输入流程

static const MethodChannel _scanChannel = MethodChannel('app.scan/qr');
......
Future<void> _startScan() async {
    if (_isScanning) {
      return;
    }

    setState(() {
      _isScanning = true;
    });

    try {
      final dynamic value = await _scanChannel.invokeMethod<dynamic>('scan');
      final String scanned = (value ?? '').toString().trim();

      if (!mounted) {
        return;
      }

      if (scanned.isEmpty) {
        _showMessage('未识别到有效内容');
      } else {
        setState(() {
          _result = scanned;
        });
      }
    } on MissingPluginException {
      if (mounted) {
        setState(() {
          _isScanning = false;
        });
      }
      await _fallbackManualScan();
      return;
    } on PlatformException catch (e) {
      if (!mounted) {
        return;
      }
      _showMessage('扫码失败: ${e.message ?? e.code}');
    } finally {
      if (mounted && _isScanning) {
        setState(() {
          _isScanning = false;
        });
      }
    }
  }

这样做的好处是：Flutter 侧功能完整，原生能力可后续增量接入。
!](https://i-blog.csdnimg.cn/direct/be688130fbd74f36b8e8b499f0fd9512.png)

四、关键问题复盘

问题 1：hvigor 构建失败（00303218 Configuration Error）

现象

构建报错指出：

The reason and usedScene attributes are mandatory for user_grant permissions.

根因

我最初只添加了：

ohos.permission.CAMERA

但 OpenHarmony 对 user_grant 权限要求更严格，必须同时提供：

reason
usedScene

修复

在 module.json5 中补齐完整结构：

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