Flutter for OpenHarmony 实战：Barcode — 纯 Dart 条形码与二维码生成全指南

前言

随着 HarmonyOS NEXT（鸿蒙原生）生态的飞速发展，越来越多的企业级应用开始在鸿蒙平台上落地。在商业零售、现代物流、社交分享以及移动支付等核心场景中，条形码（Barcode）与二维码（QR Code）作为信息交互的“桥梁”，扮演着至关重要的角色。

对于 Flutter for OpenHarmony 开发者而言，在选择三方库时，兼容性与性能是首要考量因素。本文推荐的 barcode 及其 UI 封装库 barcode_widget 是纯 Dart 实现的精品库，不仅避开了复杂的鸿蒙底层 Native 适配坑点，更凭借 SVG 矢量绘制能力，在不同比例的鸿蒙设备（如 Mate 系列手机、MatePad 平板及智慧屏）上展现了卓越的清晰度。

本文将带你从零开始，深度掌握 Barcode 的进阶用法，并最终构建一个实战级别的扫码支付界面。

---

一、条码生成的核心原理

在正式进入代码之前，了解 barcode 库的工作原理有助于我们更好地进行性能优化。

1.1 纯 Dart 的力量

与许多依赖 Android 或 iOS 原生 API 绘图的方法不同，barcode 库完全由 Dart 编写。它内部封装了各种条码协议（如 EAN、UPC、Code 128、QR 等）的数学模型。当给出一个字符串时，它会计算出对应条码的“条”与“空”的比例，或二维码的像素矩阵。

1.2 SVG 矢量化渲染

barcode_widget 最终利用 Flutter 的 CustomPainter 或直接生成 SVG 代码进行渲染。

• ✅ 优点：无限缩放不失真，特别适合高清屏幕。
• ✅ 跨平台：在鸿蒙、Android、iOS 甚至 Web 端表现高度一致。

---

二、配置环境与基础集成

2.1 引入依赖 📦

首先，在项目的 pubspec.yaml 文件中添加 barcode_widget 依赖。

dependencies:
  # 推荐使用 barcode_widget，它封装了直接可用的 Flutter 组件
  barcode_widget: ^2.0.4

💡 技巧：建议定期运行 flutter pub upgrade 以确保鸿蒙环境下的兼容性。

2.2 常见条码格式预览

目前该库在鸿蒙平台上支持以下主流格式：

• 二维码 (QR Code)：最通用的支付与链接识别码。
• Code 128 / 39：工业与物流领域最常用的条形码。
• EAN 13 / 8：全球通用的商品条码。

---

三、核心功能：3 个场景化小示例

3.1 社交与链接分享 (QR Code)

生成一个带自定义品牌色（配合鸿蒙系统深蓝主题）和内边距的官方网站链接二维码。

BarcodeWidget(
  barcode: Barcode.qrCode(), // 指定二维码类型
  data: 'https://openharmonycrossplatform.csdn.net', // 扫描后的链接内容
  width: 150,
  height: 150,
  color: const Color(0xFF007DFF), // 采用 HarmonyOS 标志性的极光蓝
  backgroundColor: Colors.white,
  padding: const EdgeInsets.all(12), // 增加留白，提高扫码成功率
)

3.2 现代物流单号 (Code 128)

生成一个标准的物流快递单条码。在鸿蒙设备上，我们可以通过 style 调整字体，使其更符合系统视觉。

BarcodeWidget(
  barcode: Barcode.code128(),
  data: 'OHOS-LOGISTICS-2026',
  width: 320,
  height: 90,
  drawText: true, // 必须显示单号文字，便于手动录入
  style: const TextStyle(
    fontSize: 14,
    color: Colors.black87,
    letterSpacing: 2, 
    fontWeight: FontWeight.bold,
  ),
)

2.3 商品零售场景 (EAN 13)

商品条码有严格的校验位逻辑。

BarcodeWidget(
  barcode: Barcode.ean13(),
  data: '690123456789', // EAN-13 码需要符合 12 位数据+1 位校验位的规则
  width: 280,
  height: 120,
)

---

四、OpenHarmony 平台适配指南

在鸿蒙系统上运行 Flutter 时，针对条码展示有以下几点优化建议：

4.1 屏幕对比度与亮度 🎨

⚠️ 注意：鸿蒙设备在高亮或深色模式（Dark Mode）下，扫码枪或摄像头对屏幕条码的识别率受对比度影响显著。

• ✅ 正确做法：无论系统是否开启深色模式，条码的背景（Container 或 Widget 内部）建议始终通过 backgroundColor 强制设为纯白色。
• ✅ 推荐颜色：前景色使用 Colors.black 或鸿蒙深蓝，以确保最大对比度。

4.2 折叠屏与分屏适配

鸿蒙拥有众多折叠屏设备（如 Mate X 系列）。

• 💡 技巧：由于是 SVG 矢量绘制，当你利用 MediaQuery 获取屏幕宽度动态调整条码大小时，图像依然能够保持极高的锐利度，不会出现传统位图图片的锯齿感。

---

五、完整实战示例：构建鸿蒙原生感支付看板

我们将模拟一个扫码收银台场景。该场景模拟了移动支付中的核心逻辑：生成动态支付码、定时自动刷新以及界面加密保护感官设计。

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:barcode_widget/barcode_widget.dart';

/// 鸿蒙风格支付页面实战
class OhosPayPage extends StatefulWidget {
  const OhosPayPage({super.key});

  @override
  State<OhosPayPage> createState() => _OhosPayPageState();
}

class _OhosPayPageState extends State<OhosPayPage> {
  // 模拟初始支付码
  String _payCode = "1345889900334455";
  late Timer _timer;

  @override
  void initState() {
    super.initState();
    // 💡 技巧：模拟每 30 秒自动刷新一次支付码，保障安全性
    _timer = Timer.periodic(const Duration(seconds: 30), (timer) {
      if (mounted) {
        setState(() {
          _payCode = (DateTime.now().millisecondsSinceEpoch % 10000000000000000).toString();
        });
      }
    });
  }

  @override
  void dispose() {
    _timer.cancel(); // 销毁页面时务必取消定时器
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: const Color(0xFFF1F3F5), // 采用鸿蒙系统浅灰色背景
      appBar: AppBar(
        title: const Text('收银台', style: TextStyle(color: Colors.black)),
        centerTitle: true,
        backgroundColor: Colors.white,
        elevation: 0,
      ),
      body: SingleChildScrollView(
        child: Center(
          child: Column(
            children: [
              const SizedBox(height: 40),
              // 模拟华为钱包风格的支付卡片
              Container(
                margin: const EdgeInsets.symmetric(horizontal: 24),
                padding: const EdgeInsets.all(24),
                decoration: BoxDecoration(
                  color: Colors.white,
                  borderRadius: BorderRadius.circular(24),
                  boxShadow: [
                    BoxShadow(
                      color: Colors.black.withOpacity(0.05),
                      blurRadius: 15,
                      offset: const Offset(0, 5),
                    )
                  ],
                ),
                child: Column(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    const Row(
                      mainAxisAlignment: MainAxisAlignment.center,
                      children: [
                        Icon(Icons.payment, color: Color(0xFF007DFF), size: 20),
                        SizedBox(width: 10),
                        Text('付款码支付', style: TextStyle(fontSize: 16, fontWeight: FontWeight.w600)),
                      ],
                    ),
                    const SizedBox(height: 30),
                    // 1. 支付条形码 (动态数据)
                    BarcodeWidget(
                      barcode: Barcode.code128(),
                      data: _payCode,
                      width: double.infinity,
                      height: 85,
                      drawText: false, // 条码下方不显示原始数字，由独立 Text 展示
                    ),
                    const SizedBox(height: 12),
                    // 格式化输出四位一组的数字，方便用户阅读
                    Text(
                      _payCode.replaceAllMapped(RegExp(r".{4}"), (match) => "${match.group(0)} "),
                      style: const TextStyle(fontSize: 16, letterSpacing: 1.5, color: Colors.black54),
                    ),
                    const SizedBox(height: 40),
                    // 2. 备用二维码
                    BarcodeWidget(
                      barcode: Barcode.qrCode(),
                      data: 'https://pay.example.com/ohos/$_payCode',
                      width: 190,
                      height: 190,
                      color: Colors.black,
                    ),
                    const SizedBox(height: 30),
                    const Divider(height: 1),
                    const SizedBox(height: 20),
                    const Row(
                      mainAxisAlignment: MainAxisAlignment.center,
                      children: [
                        Icon(Icons.security, color: Color(0xFF2E7D32), size: 16),
                        Text(' 每 30s 自动更新 | 支付安全受鸿蒙内核保护', 
                          style: TextStyle(color: Color(0xFF2E7D32), fontSize: 12)),
                      ],
                    )
                  ],
                ),
              ),
              const SizedBox(height: 30),
              const Text('查看交易记录', style: TextStyle(color: Color(0xFF007DFF), fontSize: 14)),
            ],
          ),
        ),
      ),
    );
  }
}

---

六、更多高级应用场景

6.1 生成电子名片 (vCard)

你可以通过 data 传入 vCard 格式的字符串，扫码即可直接保存联系人至鸿蒙通讯录。

final String vCard = "BEGIN:VCARD\nVERSION:3.0\nN:鸿蒙开发者\nTEL:123456789\nEND:VCARD";
// 使用 Barcode.qrCode() 生成

6.2 矢量图导出

如果你的鸿蒙应用需要支持将条码导出为图片保存到相册，可以先生成 SVG 字符串：

final barcode = Barcode.code128();
final svgString = barcode.toSvg('DATA', width: 200, height: 80);
// 随后利用 flutter_svg 等库转换或直接解析

---

七、总结与展望

barcode_widget 在 Flutter for OpenHarmony 生态中展现了极高的成熟度。它规避了底层 Native 平台的复杂性，利用 Dart 的高性能计算能力为用户提供了毫秒级的生成体验。

在 HarmonyOS NEXT 全面推广的背景下，掌握这类“零适配、高产出”的三方库用法，能让我们的应用在短期内迅速对齐原生体验。后续大家可以尝试将条码生成与鸿蒙的 CameraKit（扫码能力）相结合，构建完整的 O2O 闭环。

---

🌐 欢迎加入开源鸿蒙跨平台社区：开源鸿蒙跨平台开发者社区