Flutter二维码账单生成插件qr_bill的使用

二维码账单库是一个用于开发瑞士支付二维码账单和支付单据的Flutter库。以下是该库的基本功能和使用方法。

功能

该库由三个类组成：

• QRBill：这个类主要用于存储和传输二维码账单数据，类似于一个POJO（Plain Old Java Object）。此外，该类还可以验证包含的数据是否符合瑞士支付标准（当前版本为2.2）。

• QRGenerator：此类允许生成实际的二维码图像，用于二维码账单，但不包括支付单据。输入为QRBill对象，输出可以是Widget或PNG二进制数据。

• BillGenerator：此类将生成完整的格式化二维码账单支付单据，并以PNG二进制数据的形式输出单个二维码账单，或者以PDF文档形式输出多个二维码账单（每页一个）。输入为单个二维码账单的QRBill对象，对于PDF文档则为QRBill列表。支持的语言有英语、德语、法语和意大利语。

使用方法

通常情况下，QRBill 类必须始终被导入，因为它作为输入与其他两个类一起使用——QRGenerator（用于生成二维码）或BillGenerator（用于生成支付单据/发票）。

生成二维码账单Widget

import 'package:flutter/material.dart';
import 'package:qr_bill/qr_bill.dart';
import 'package:qr_bill/qr_generator.dart';

// 获取二维码账单Widget
Future<Widget> getQRBillWidget(String rawQrCode, double size) async {
  // 创建QRBill实例
  QRBill qrBill = QRBill(data: rawQrCode);
  Widget? qrWidget;
  
  // 验证二维码数据是否有效
  if (qrBill.isValid()) {
    // 创建QRGenerator实例
    QRGenerator qr = QRGenerator(qrBill);
    // 获取二维码Widget
    qrWidget = await qr.getWidget(size: size);
  }

  // 如果二维码数据无效，则返回错误提示
  if (qrWidget == null) {
    return SizedBox(
      width: size,
      height: size,
      child: const Center(child: Text("QR数据格式错误！")),
    );
  } else {
    return qrWidget;
  }
}

输出包含多个二维码支付单据的PDF文档

import 'package:qr_bill/qr_bill.dart';
import 'package:qr_bill/bill_generator.dart';

// 获取包含多个二维码支付单据的PDF文档
Future<File?> getInvoicesBinary(List<QRBill> qrBills, File fileToWrite) async {
  // 创建BillGenerator实例并设置语言为德语
  BillGenerator bills = BillGenerator(language: BillGenerator.german);
  // 生成包含多个二维码支付单据的PDF文档
  Uint8List? bill = await bills.generateInvoices(qrBills);
  // 将PDF文档写入文件
  return bill == null ? null : await fileToWrite.writeAsBytes(bill);
}

快速API参考

QRBill

• QRBill QRBill({String data = ""})：基本构造函数。
• QRBill QRBill.fromJson(Map<String, dynamic> json)：从JSON格式反序列化QRBill对象。
• Map<String, dynamic> toJson()：将QRBill对象序列化为JSON格式。
• String toString()：返回QRBill对象的原始字符串，用于二维码。
• bool isValid()：返回QRBill是否严格遵循规范。
• List<QRBillException> qrExceptions：如果QRBill不严格遵循规范，则返回错误列表，否则返回空列表。
• 包含了众多用于各种瑞士QR账单属性的getter和setter。

QRGenerator

• QRGenerator QRGenerator(QRBill data)：基本构造函数。
• Future<Widget?> getWidget({required double size, double margin = 0.05})：通过构造函数输出单个二维码作为Flutter Widget。
• Future<ByteData?> getBinary({required double size, double margin = 0.05})：通过构造函数输出单个二维码的二进制数据（PNG格式）。
• void drawCanvas(Canvas c, {double margin = 0.0, required double size, Offset offset = const Offset(0.0, 0.0)})：通过构造函数将单个二维码绘制到画布上。主要由BillGenerator使用。

BillGenerator

• BillGenerator BillGenerator({BillGenerator language = BillGenerator.english})：基本构造函数。还设置了要使用的语言。
• Future<Uint8List?> getBinary(QRBill qrBill)：输出单个瑞士QR账单支付单据的二进制数据（PNG格式）。
• Future<Widget?> getWidget(QRBill qrBill)：根据给定的QRBill对象生成并返回瑞士QR账单支付单据的Widget版本。
• Future<List<Widget?>> getWidgets(List<QRBill> qrBills)：根据输入的QRBill对象列表生成并返回瑞士QR账单支付单据的Widget列表。
• Future<Uint8List?> generateInvoices(List<QRBill> qrBills)：输出给定QRBill的瑞士QR账单支付单据的二进制数据，以PDF格式输出，每页一个。

完整示例

以下是在Dart项目中如何使用qr_bill插件的完整示例：

import 'package:flutter/material.dart';
import 'package:qr_bill/qr_bill.dart';
import 'package:qr_bill/bill_generator.dart';

void main() => runApp(QrBillExample());

class QrBillExample extends StatefulWidget {
  const QrBillExample({Key? key}) : super(key: key);

  [@override](/user/override)
  State<QrBillExample> createState() => _QrBillExampleState();
}

class _QrBillExampleState extends State<QrBillExample> {
  Widget? qr = null;

  [@override](/user/override)
  void initState() {
    _getQR();
    super.initState();
  }

  Future<void> _getQR() async {
    // 创建QRBill实例
    QRBill qrBill = QRBill();
    
    // 设置账单信息
    qrBill.setIBAN("CH4431999123000889012");
    qrBill.setActor(
        typeId: QRBill.actorUCR,
        addressType: QRBill.addTypeStructured,
        name: "Max Muster & Söhne",
        address1: "Musterstrasse",
        address2: "123",
        postalcode: "8000",
        location: "Seldwyla",
        country: "CH");
    qrBill.setActor(
        typeId: QRBill.actorUDR,
        addressType: QRBill.addTypeStructured,
        name: "Sandro Bellucci",
        address1: "Musterstrasse",
        address2: "1",
        postalcode: "8000",
        location: "Seldwyla",
        country: "CH");
    qrBill.setAlternativeSchema(schemas: [
      "Name AV1: UV;UltraPay005;12345",
      "Name AV2: XY;XYService;54321"
    ]);
    qrBill.setAmount(1949.75);
    qrBill.setReference(QRBill.refTypeQRR, "210000000003139471430009017");
    qrBill.setAdditionalInfo(
        "//S1/10/1234/11/201021/30/102673386/32/7.7/40/0:30");

    // 创建BillGenerator实例并设置语言为德语
    BillGenerator qrGen = BillGenerator(language: BillGenerator.german);
    // 生成二维码账单Widget
    qr = await (qrGen.getWidget(qrBill));
    setState(() {});
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Center(child: qr ?? Container());
  }
}