Flutter安全二维码生成插件secure_qr_generator的使用

Flutter安全二维码生成插件secure_qr_generator的使用

secure_qr_generator 是一个用于生成安全、自动刷新的二维码的 Flutter 插件。它支持AES加密、HMAC-SHA256签名、自动过期管理和自定义样式。

特性

• 安全性：支持AES加密和HMAC-SHA256签名。
• 自动过期：内置有效期管理。
• 自动刷新：二维码在过期前自动刷新。
• Flutter集成：现成的 Flutter 小部件。
• 可定制样式：完全控制二维码外观。
• 性能优化：高效再生，最小化开销。

安装

将以下内容添加到你的 pubspec.yaml 文件中：

dependencies:
  secure_qr_generator: ^1.0.4

然后运行：

flutter pub get

快速开始

基本用法

import 'package:secure_qr_generator/secure_qr_generator.dart';

// 创建配置
final config = GeneratorConfig.production(
  secretKey: 'your-32-character-secret-key-here!!!',
  validityDuration: Duration(minutes: 5),
);

// 初始化生成器
final generator = SecureQRGenerator(config);

// 创建二维码数据
final data = QRData(
  payload: {'userId': '123', 'access': 'granted'},
  metadata: {'purpose': 'access_control'},
  tags: ['entrance', 'visitor'],
);

// 生成二维码
final result = await generator.generateQR(data);

使用自动刷新的小部件

AutoRegeneratingQRView(
  data: data,
  generator: generator,
  size: 200,
  style: QrStyle(
    eyeStyle: QrEyeStyle(eyeShape: QrEyeShape.square),
    dataModuleStyle: QrDataModuleStyle(
      dataModuleShape: QrDataModuleShape.circle,
    ),
  ),
  onRegenerate: (result) {
    print('新二维码已生成: ${result.id}');
  },
  onError: (error) {
    print('错误: $error');
  },
)

配置选项

开发环境配置

final devConfig = GeneratorConfig.development();

生产环境配置

final prodConfig = GeneratorConfig.production(
  secretKey: 'your-secure-production-key-here!!!!!!',
  validityDuration: Duration(minutes: 5),
);

自定义配置

final customConfig = GeneratorConfig(
  secretKey: 'your-secret-key',
  validityDuration: Duration(minutes: 10),
  enableEncryption: true,
  enableSignature: true,
  dataVersion: 1,
  idPrefix: 'CUSTOM_',
);

高级功能

自定义二维码样式

QrStyle(
  eyeStyle: QrEyeStyle(
    eyeShape: QrEyeShape.square,
    color: Colors.blue,
  ),
  dataModuleStyle: QrDataModuleStyle(
    dataModuleShape: QrDataModuleShape.circle,
    color: Colors.black,
  ),
  embeddedImage: AssetImage('assets/logo.png'),
  embeddedImageStyle: QrEmbeddedImageStyle(
    size: Size(40, 40),
  ),
)

自定义刷新间隔

AutoRegeneratingQRView(
  data: data,
  generator: generator,
  regenerationInterval: Duration(minutes: 2),
  // 其他参数
)

自定义二维码构建器

AutoRegeneratingQRView(
  data: data,
  generator: generator,
  builder: (qrData) => Container(
    decoration: BoxDecoration(
      border: Border.all(color: Colors.blue),
    ),
    child: QrImageView(
      data: qrData,
      size: 200,
    ),
  ),
)

错误处理

该插件包括全面的错误处理：

try {
  final result = await generator.generateQR(data);
  // 使用结果
} on GenerationError catch (e) {
  switch (e.type) {
    case GenerationErrorType.configuration:
      print('配置错误: ${e.message}');
      break;
    case GenerationErrorType.encryption:
      print('加密错误: ${e.message}');
      break;
    case GenerationErrorType.payloadTooLarge:
      print('载荷过大: ${e.message}');
      break;
    // 处理其他错误类型...
  }
}

安全注意事项

• 保持你的 secretKey 安全，不要将其提交到版本控制系统。
• 在开发和生产环境中使用不同的密钥。
• 在添加数据时考虑二维码的大小限制。
• 根据使用场景选择合适的有效期。
• 在生产环境中定期更换加密密钥。

示例代码

以下是一个完整的示例代码，展示了如何使用 secure_qr_generator 插件：

import 'dart:developer';

import 'package:flutter/material.dart';
import 'package:qr_flutter/qr_flutter.dart';
import 'package:secure_qr_generator/secure_qr_generator.dart';

void main() async {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Secure QR Genrator Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const QRDisplayScreen(),
    );
  }
}

class QRDisplayScreen extends StatefulWidget {
  const QRDisplayScreen({super.key});

  [@override](/user/override)
  State<QRDisplayScreen> createState() => _QRDisplayScreenState();
}

class _QRDisplayScreenState extends State<QRDisplayScreen> {
  late TextEditingController phoneController;
  late TextEditingController secretKeyController;
  bool enableEncryption = true;
  bool enableSignature = true;
  int validityDuration = 60;
  String phoneNumber = '07070707';

  // 配置
  late GeneratorConfig secureConfig;
  late SecureQRGenerator generator;

  // 更新生成器
  void updateGenerator() {
    setState(() {
      secureConfig = GeneratorConfig(
        secretKey: secretKeyController.text,
        enableEncryption: enableEncryption,
        enableSignature: enableSignature,
        validityDuration: Duration(seconds: validityDuration),
      );
      generator = SecureQRGenerator(secureConfig);
    });
  }

  [@override](/user/override)
  void initState() {
    phoneController = TextEditingController(text: phoneNumber);
    secretKeyController =
        TextEditingController(text: '2024#@#qrcod#orange@##perform#==');
    // 初始化配置
    secureConfig = GeneratorConfig(
      secretKey: secretKeyController.text,
      enableEncryption: enableEncryption,
      enableSignature: enableSignature,
      validityDuration: Duration(seconds: validityDuration),
    );
    generator = SecureQRGenerator(secureConfig);
    super.initState();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Secure QR Generator Demo')),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            TextField(
              controller: secretKeyController,
              decoration: const InputDecoration(
                  labelText: 'AES-256 密钥（可选）'),
              onChanged: (_) => updateGenerator(),
            ),
            SwitchListTile(
              title: const Text('加密（可选）'),
              value: enableEncryption,
              onChanged: (value) {
                setState(() {
                  enableEncryption = value;
                  updateGenerator();
                });
              },
            ),
            SwitchListTile(
              title: const Text('签名（可选）'),
              value: enableSignature,
              onChanged: (value) {
                setState(() {
                  enableSignature = value;
                  updateGenerator();
                });
              },
            ),
            Text('有效期 ($validityDuration 秒)'),
            Slider(
              value: validityDuration.toDouble(),
              min: 10,
              max: 300,
              divisions: 29,
              label: '$validityDuration 秒',
              onChanged: (value) {
                setState(() {
                  validityDuration = value.toInt();
                  updateGenerator();
                });
              },
            ),
            TextField(
              decoration:
                  const InputDecoration(labelText: '电话号码'),
              controller: phoneController,
              onChanged: (value) {
                setState(() {
                  phoneNumber = value;
                });
              },
            ),
            const SizedBox(height: 40),
            // 二维码
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                AutoRegeneratingQRView(
                  data: QRData(
                    payload: {
                      'phoneNumber': phoneNumber,
                    },
                  ),
                  generator: generator,
                  size: 250,
                  style: const QrStyle(
                    eyeStyle: QrEyeStyle(
                      eyeShape: QrEyeShape.square,
                      color: Colors.deepOrangeAccent,
                    ),
                  ),
                  onRegenerate: (result) =>
                      log('新二维码已生成: ${result.toMap()}'),
                  onError: (error) {
                    ScaffoldMessenger.of(context).showSnackBar(
                      SnackBar(content: Text('错误: $error')),
                    );
                  },
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }

  [@override](/user/override)
  void dispose() {
    secretKeyController.dispose();
    super.dispose();
  }
}