Flutter通信插件telpo_flutter_sdk的使用

telpo_flutter_sdk 是一个用于处理与Telpo热敏打印机设备连接和通信的Flutter插件。本文将详细介绍如何在Flutter项目中集成并使用该插件。

一、动机

在开发MASHINPAY支付解决方案时，我们购买了Telpo热敏打印机（具体型号为"M1"），以便在用户成功交易后打印发票文件。Telpo设备自带原生SDK和相关文档。由于没有官方的Flutter插件，我们自行定制了这个插件，并添加了许多有用的方法来更好地处理异常情况、自定义打印布局等。

二、Android设置

1. 添加JitPack仓库

在项目的build.gradle文件（位于android/build.gradle）中添加以下内容：

allprojects {
    repositories {
        ...
        maven { url "https://jitpack.io" }
        ...
    }
}

2. 设置最低SDK版本

在应用级别的build.gradle文件（位于android/app/build.gradle）中将minSdkVersion设置为19：

android {
    defaultConfig {
        ...
        minSdkVersion 19
        ...
    }
}

三、使用方法

初始化

首先，创建一个TelpoFlutterChannel实例：

final _telpoFlutterChannel = TelpoFlutterChannel();

连接Telpo设备

final bool connected = await _telpoFlutterChannel.connect();
// 结果：true 或 false

检查Telpo设备状态

final TelpoStatus status = await _telpoFlutterChannel.checkStatus();
// 结果：ok, noPaper, overHeat, cacheIsFull, unknown

检查连接状态

final bool status = await _telpoFlutterChannel.isConnected();
// 结果：true 或 false

打印数据

// 创建一个新的打印表单
final sheet = TelpoPrintSheet();

// 创建文本元素
const textData = PrintData.text(
  'TelpoFlutterSdk',
  alignment: PrintAlignment.center,
  fontSize: PrintedFontSize.size34,
);

// 创建8行空白间隔
const spacing = PrintData.space(step: 8);

// 将文本元素插入到表单中
sheet.addElement(textData);

// 将空白间隔插入到表单中
sheet.addElement(spacing);

final PrintResult result = await _telpoFlutterChannel.print(sheet);
// 结果：success, noPaper, lowBattery, overHeat, dataCanNotBeTransmitted, other

四、完整示例Demo

下面是一个完整的示例代码，展示了如何初始化、连接、检查状态以及打印数据：

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:telpo_flutter_sdk/telpo_flutter_sdk.dart';

const telpoColor = Color(0xff005AFF);

void main() {
  runApp(const App());
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      debugShowCheckedModeBanner: false,
      home: HomeScreen(),
    );
  }
}

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

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  bool _connected = false;
  String _telpoStatus = 'Not initialized';
  bool _isLoading = false;

  final _telpoFlutterChannel = TelpoFlutterChannel();

  Future<void> _connect() async {
    final bool connected = await _telpoFlutterChannel.connect();
    setState(() {
      _connected = connected;
      _telpoStatus = _connected ? 'Connected' : 'Telpo not supported';
    });
  }

  Future<void> _checkStatus() async {
    final TelpoStatus status = await _telpoFlutterChannel.checkStatus();
    setState(() => _telpoStatus = status.name);
  }

  Future<void> _printData() async {
    setState(() => _isLoading = true);

    // 创建一个新的打印表单
    final sheet = TelpoPrintSheet();

    // 创建文本元素
    final textData = PrintData.text(
      'TelpoFlutterSdk',
      alignment: PrintAlignment.center,
      fontSize: PrintedFontSize.size34,
    );

    // 创建8行空白间隔
    final spacing = PrintData.space(line: 8);

    // 将文本元素插入到表单中
    sheet.addElement(textData);

    // 将空白间隔插入到表单中
    sheet.addElement(spacing);

    final PrintResult result = await _telpoFlutterChannel.print(sheet);
    setState(() {
      _telpoStatus = result.name;
      _isLoading = false;
    });
  }

  @override
  void dispose() {
    _telpoFlutterChannel.disconnect();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        elevation: 0.0,
        systemOverlayStyle: SystemUiOverlayStyle.light,
        backgroundColor: const Color(0xffFF8D49),
        title: const Text('Telpo plugin example'),
        actions: [
          if (_isLoading)
            Container(
              alignment: Alignment.center,
              padding: const EdgeInsets.only(right: 16.0),
              child: const CircularProgressIndicator(
                color: Colors.white,
              ),
            )
        ],
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              'Telpo status: $_telpoStatus',
              style: const TextStyle(fontSize: 16.0),
            ),
            const SizedBox(height: 32.0),
            CupertinoButton(
              color: telpoColor,
              onPressed: _isLoading ? null : _connect,
              child: const Text('Initialize'),
            ),
            if (_connected) ...[
              const SizedBox(height: 24.0),
              CupertinoButton(
                color: telpoColor,
                onPressed: _isLoading ? null : _checkStatus,
                child: const Text('Check status'),
              ),
              if ([PrintResult.success.name, TelpoStatus.ok.name].contains(_telpoStatus)) ...[
                const SizedBox(height: 24.0),
                CupertinoButton(
                  color: telpoColor,
                  onPressed: _isLoading ? null : _printData,
                  child: Text(
                    _isLoading ? 'Printing' : 'Print',
                  ),
                ),
              ]
            ],
          ],
        ),
      ),
    );
  }
}

五、后续计划

• [x] 编写详细的文档
• [x] 记录平台特定配置
• [x] 解释 PrintResult 和 TelpoStatus 枚举值
• [ ] 实现图像文件打印功能
• [ ] 使用NFC切换打印事件
• [ ] 使用蓝牙切换打印事件
• [ ] 检查设备上是否支持Telpo

希望上述内容能帮助您快速上手使用 telpo_flutter_sdk 插件。如果有任何问题或建议，请随时提交Issue或Pull Request。