init
This commit is contained in:
Developer
471
docs/usage.md
Normal file
471
docs/usage.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# Printer 插件使用指南
|
||||
|
||||
> 本文档介绍 Flutter Printer 插件的安装、配置和使用方法。该插件封装了 Android `autoreplyprint` SDK，提供了串口/USB 端口管理和票据打印功能。
|
||||
|
||||
## 目录
|
||||
|
||||
- [安装](#安装)
|
||||
- [快速开始](#快速开始)
|
||||
- [端口管理](#端口管理)
|
||||
- [票据打印](#票据打印)
|
||||
- [异常处理](#异常处理)
|
||||
- [完整示例](#完整示例)
|
||||
- [API 参考](#api-参考)
|
||||
|
||||
---
|
||||
|
||||
## 安装
|
||||
|
||||
### 1. 添加依赖
|
||||
|
||||
在 `pubspec.yaml` 中添加本地依赖：
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
printer:
|
||||
path: ../printer # 根据实际路径调整
|
||||
```
|
||||
|
||||
### 2. 配置 Android
|
||||
|
||||
将 `docs/autoreplyprint.aar` 文件放置到 Android 项目的 `app/libs/` 目录下：
|
||||
|
||||
```
|
||||
your_flutter_app/
|
||||
└── android/
|
||||
└── app/
|
||||
└── libs/
|
||||
└── autoreplyprint.aar
|
||||
```
|
||||
|
||||
在 `android/app/build.gradle` 中确保 `libs` 目录被引用：
|
||||
|
||||
```gradle
|
||||
dependencies {
|
||||
implementation files('libs/autoreplyprint.aar')
|
||||
// ... 其他依赖
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 基本打印流程
|
||||
|
||||
一个完整的打印流程包含三个步骤：**打开端口 → 打印内容 → 关闭端口**。
|
||||
|
||||
```dart
|
||||
import 'package:printer/printer.dart';
|
||||
|
||||
final printer = Printer();
|
||||
|
||||
// 1. 打开端口
|
||||
final handle = await printer.openComPort(
|
||||
portName: '/dev/ttyS0',
|
||||
baudRate: 115200,
|
||||
);
|
||||
|
||||
// 2. 设置编码并打印文本
|
||||
await printer.setMultiByteMode(handle);
|
||||
await printer.setMultiByteEncoding(handle, MultiByteEncoding.utf8);
|
||||
await printer.setAlignment(handle, PrinterAlignment.center);
|
||||
await printer.printText(handle, 'Hello 中文\n');
|
||||
await printer.feedLine(handle, 3);
|
||||
|
||||
// 3. 关闭端口
|
||||
await printer.closePort(handle);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 端口管理
|
||||
|
||||
### 枚举端口
|
||||
|
||||
```dart
|
||||
// 枚举串口
|
||||
final comPorts = await printer.enumComPorts();
|
||||
print('可用串口: $comPorts');
|
||||
|
||||
// 枚举USB端口
|
||||
final usbPorts = await printer.enumUsbPorts();
|
||||
print('可用USB口: $usbPorts');
|
||||
```
|
||||
|
||||
### 打开串口 (COM Port)
|
||||
|
||||
```dart
|
||||
final handle = await printer.openComPort(
|
||||
portName: '/dev/ttyS0', // 端口名称（必填）
|
||||
baudRate: 115200, // 波特率（必填），需与打印机保持一致
|
||||
dataBits: 8, // 数据位，默认8
|
||||
parity: SerialParity.none, // 校验位，默认无校验
|
||||
stopBits: SerialStopBits.one, // 停止位，默认1位
|
||||
flowControl: SerialFlowControl.none, // 流控制，默认无
|
||||
autoReplyMode: true, // 是否开启自动回传模式
|
||||
);
|
||||
```
|
||||
|
||||
**参数说明：**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| `portName` | `String` | 是 | - | 端口名称，如 `/dev/ttyS0` 或 `COM1` |
|
||||
| `baudRate` | `int` | 是 | - | 波特率，如 `9600`, `19200`, `38400`, `57600`, `115200` |
|
||||
| `dataBits` | `int` | 否 | `8` | 数据位，范围 `[4, 8]` |
|
||||
| `parity` | `SerialParity` | 否 | `none` | 校验位：`none`, `odd`, `even`, `mark`, `space` |
|
||||
| `stopBits` | `SerialStopBits` | 否 | `one` | 停止位：`one`, `onePointFive`, `two` |
|
||||
| `flowControl` | `SerialFlowControl` | 否 | `none` | 流控制：`none`, `xonXoff`, `rtsCts`, `dtrDsr` |
|
||||
| `autoReplyMode` | `bool` | 否 | `true` | 是否开启自动回传模式 |
|
||||
|
||||
### 打开 USB 端口
|
||||
|
||||
```dart
|
||||
final handle = await printer.openUsbPort(
|
||||
portName: 'USB001', // 端口名称（必填），可不指定以自动查找
|
||||
autoReplyMode: true, // 是否开启自动回传模式
|
||||
);
|
||||
```
|
||||
|
||||
### 检查端口状态
|
||||
|
||||
```dart
|
||||
final isOpen = await printer.isPortOpened(handle);
|
||||
if (isOpen) {
|
||||
print('端口已打开');
|
||||
}
|
||||
```
|
||||
|
||||
### 关闭端口
|
||||
|
||||
```dart
|
||||
final success = await printer.closePort(handle);
|
||||
```
|
||||
|
||||
### 使用安全句柄 (推荐)
|
||||
|
||||
使用 `PrinterPortHandle` 可以更安全地管理端口资源，避免资源泄漏：
|
||||
|
||||
```dart
|
||||
// 打开带句柄的串口
|
||||
final portHandle = await printer.openComPortWithHandle(
|
||||
portName: '/dev/ttyS0',
|
||||
baudRate: 115200,
|
||||
);
|
||||
|
||||
try {
|
||||
// 执行打印操作
|
||||
await printer.printText(portHandle.handle, 'Hello\n');
|
||||
} finally {
|
||||
// 确保端口被关闭
|
||||
await portHandle.close();
|
||||
}
|
||||
```
|
||||
|
||||
同样支持 USB 端口：
|
||||
|
||||
```dart
|
||||
final portHandle = await printer.openUsbPortWithHandle(
|
||||
portName: 'USB001',
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 票据打印
|
||||
|
||||
### 打印文本
|
||||
|
||||
在打印文本之前，需要先设置多字节编码模式：
|
||||
|
||||
```dart
|
||||
// 设置多字节模式
|
||||
await printer.setMultiByteMode(handle);
|
||||
|
||||
// 设置编码为 UTF-8（支持中文等多语言字符）
|
||||
await printer.setMultiByteEncoding(handle, MultiByteEncoding.utf8);
|
||||
|
||||
// 打印文本
|
||||
await printer.printText(handle, 'Hello 中文\n');
|
||||
```
|
||||
|
||||
**支持的编码类型 (`MultiByteEncoding`)：**
|
||||
|
||||
| 编码 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| `gbk` | `0` | GBK 编码（简体中文） |
|
||||
| `utf8` | `1` | UTF-8 编码（Unicode，推荐） |
|
||||
| `big5` | `3` | BIG5 编码（繁体中文） |
|
||||
| `shiftJis` | `4` | Shift-JIS 编码（日文） |
|
||||
| `eucKr` | `5` | EUC-KR 编码（韩文） |
|
||||
|
||||
### 设置文本对齐
|
||||
|
||||
```dart
|
||||
// 左对齐
|
||||
await printer.setAlignment(handle, PrinterAlignment.left);
|
||||
|
||||
// 居中对齐
|
||||
await printer.setAlignment(handle, PrinterAlignment.center);
|
||||
|
||||
// 右对齐
|
||||
await printer.setAlignment(handle, PrinterAlignment.right);
|
||||
```
|
||||
|
||||
### 设置文本缩放
|
||||
|
||||
宽度和高度缩放值范围为 `1` 到 `8`：
|
||||
|
||||
```dart
|
||||
await printer.setTextScale(
|
||||
handle,
|
||||
widthScale: 2, // 宽度放大2倍
|
||||
heightScale: 2, // 高度放大2倍
|
||||
);
|
||||
|
||||
await printer.printText(handle, 'Large Text\n');
|
||||
```
|
||||
|
||||
### 设置文本加粗
|
||||
|
||||
```dart
|
||||
// 开启加粗
|
||||
await printer.setTextBold(handle, true);
|
||||
await printer.printText(handle, 'Bold Text\n');
|
||||
|
||||
// 关闭加粗
|
||||
await printer.setTextBold(handle, false);
|
||||
```
|
||||
|
||||
### 设置文本下划线
|
||||
|
||||
```dart
|
||||
// 0 = 无下划线
|
||||
// 1 = 1点下划线
|
||||
// 2 = 2点下划线
|
||||
await printer.setTextUnderline(handle, 1);
|
||||
await printer.printText(handle, 'Underlined Text\n');
|
||||
```
|
||||
|
||||
### 走纸
|
||||
|
||||
```dart
|
||||
// 走纸指定行数
|
||||
await printer.feedLine(handle, 5);
|
||||
|
||||
// 走纸指定点数
|
||||
await printer.feedDot(handle, 100);
|
||||
```
|
||||
|
||||
### 切纸
|
||||
|
||||
```dart
|
||||
// 半切（虚线切，纸张不完全分离）
|
||||
await printer.halfCutPaper(handle);
|
||||
|
||||
// 全切（实线切，纸张完全分离）
|
||||
await printer.fullCutPaper(handle);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 异常处理
|
||||
|
||||
所有端口打开操作在失败时会抛出 `PrinterException`：
|
||||
|
||||
```dart
|
||||
try {
|
||||
final handle = await printer.openComPort(
|
||||
portName: '/dev/ttyS0',
|
||||
baudRate: 115200,
|
||||
);
|
||||
} on PrinterException catch (e) {
|
||||
print('端口打开失败: ${e.code} - ${e.message}');
|
||||
}
|
||||
```
|
||||
|
||||
`PrinterException` 包含以下信息：
|
||||
|
||||
| 属性 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | `String` | 机器可读的错误码，如 `INVALID_ARGUMENT`, `PORT_OPEN_FAILED` |
|
||||
| `message` | `String` | 人类可读的错误消息 |
|
||||
| `details` | `dynamic` | 额外的错误详情（可能为 null） |
|
||||
|
||||
---
|
||||
|
||||
## 完整示例
|
||||
|
||||
以下是一个完整的票据打印示例：
|
||||
|
||||
```dart
|
||||
import 'package:printer/printer.dart';
|
||||
|
||||
/// 打印收据示例
|
||||
Future<void> printReceipt() async {
|
||||
final printer = Printer();
|
||||
PrinterPortHandle? portHandle;
|
||||
|
||||
try {
|
||||
// 1. 枚举可用端口
|
||||
final comPorts = await printer.enumComPorts();
|
||||
if (comPorts.isEmpty) {
|
||||
print('没有可用的串口');
|
||||
return;
|
||||
}
|
||||
|
||||
// 2. 打开第一个可用端口
|
||||
portHandle = await printer.openComPortWithHandle(
|
||||
portName: comPorts.first,
|
||||
baudRate: 115200,
|
||||
);
|
||||
final handle = portHandle.handle;
|
||||
|
||||
// 3. 设置编码
|
||||
await printer.setMultiByteMode(handle);
|
||||
await printer.setMultiByteEncoding(handle, MultiByteEncoding.utf8);
|
||||
|
||||
// 4. 打印标题（居中、加粗、放大）
|
||||
await printer.setAlignment(handle, PrinterAlignment.center);
|
||||
await printer.setTextBold(handle, true);
|
||||
await printer.setTextScale(handle, widthScale: 2, heightScale: 2);
|
||||
await printer.printText(handle, '收据标题\n');
|
||||
|
||||
// 5. 重置样式并打印内容
|
||||
await printer.setTextBold(handle, false);
|
||||
await printer.setTextScale(handle, widthScale: 1, heightScale: 1);
|
||||
await printer.setAlignment(handle, PrinterAlignment.left);
|
||||
await printer.printText(handle, '商品名称 数量 价格\n');
|
||||
await printer.printText(handle, '----------------------------\n');
|
||||
await printer.printText(handle, '商品A 2 ¥20.00\n');
|
||||
await printer.printText(handle, '商品B 1 ¥15.00\n');
|
||||
await printer.printText(handle, '----------------------------\n');
|
||||
await printer.printText(handle, '总计: ¥35.00\n');
|
||||
|
||||
// 6. 走纸并切纸
|
||||
await printer.feedLine(handle, 5);
|
||||
await printer.halfCutPaper(handle);
|
||||
|
||||
print('打印完成');
|
||||
} on PrinterException catch (e) {
|
||||
print('打印失败: ${e.code} - ${e.message}');
|
||||
} finally {
|
||||
// 7. 确保端口关闭
|
||||
await portHandle?.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 参考
|
||||
|
||||
### Printer 类
|
||||
|
||||
| 方法 | 返回值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `getPlatformVersion()` | `Future<String?>` | 获取平台版本 |
|
||||
| `enumComPorts()` | `Future<List<String>>` | 枚举可用串口 |
|
||||
| `enumUsbPorts()` | `Future<List<String>>` | 枚举可用USB端口 |
|
||||
| `openComPort({...})` | `Future<int>` | 打开串口 |
|
||||
| `openUsbPort({...})` | `Future<int>` | 打开USB端口 |
|
||||
| `openComPortWithHandle({...})` | `Future<PrinterPortHandle>` | 打开串口并返回安全句柄 |
|
||||
| `openUsbPortWithHandle({...})` | `Future<PrinterPortHandle>` | 打开USB端口并返回安全句柄 |
|
||||
| `closePort(int handle)` | `Future<bool>` | 关闭端口 |
|
||||
| `isPortOpened(int handle)` | `Future<bool>` | 检查端口是否打开 |
|
||||
| `setMultiByteMode(int handle)` | `Future<bool>` | 设置多字节编码模式 |
|
||||
| `setMultiByteEncoding(int, MultiByteEncoding)` | `Future<bool>` | 设置多字节编码类型 |
|
||||
| `printText(int handle, String text)` | `Future<bool>` | 打印文本 |
|
||||
| `setAlignment(int, PrinterAlignment)` | `Future<bool>` | 设置文本对齐 |
|
||||
| `setTextScale(int, {width, height})` | `Future<bool>` | 设置文本缩放 |
|
||||
| `setTextBold(int handle, bool bold)` | `Future<bool>` | 设置文本加粗 |
|
||||
| `setTextUnderline(int handle, int level)` | `Future<bool>` | 设置文本下划线 |
|
||||
| `feedLine(int handle, int numLines)` | `Future<bool>` | 走纸指定行数 |
|
||||
| `feedDot(int handle, int numDots)` | `Future<bool>` | 走纸指定点数 |
|
||||
| `halfCutPaper(int handle)` | `Future<bool>` | 半切纸 |
|
||||
| `fullCutPaper(int handle)` | `Future<bool>` | 全切纸 |
|
||||
|
||||
### 枚举类型
|
||||
|
||||
#### SerialParity (串口校验位)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `none` | 无校验 |
|
||||
| `odd` | 奇校验 |
|
||||
| `even` | 偶校验 |
|
||||
| `mark` | 标记校验 |
|
||||
| `space` | 空白校验 |
|
||||
|
||||
#### SerialStopBits (串口停止位)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `one` | 1位停止位 |
|
||||
| `onePointFive` | 1.5位停止位 |
|
||||
| `two` | 2位停止位 |
|
||||
|
||||
#### SerialFlowControl (串口流控制)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `none` | 无流控 |
|
||||
| `xonXoff` | XON/XOFF 软件流控 |
|
||||
| `rtsCts` | RTS/CTS 硬件流控 |
|
||||
| `dtrDsr` | DTR/DSR 硬件流控 |
|
||||
|
||||
#### PrinterAlignment (打印对齐)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `left` | 左对齐 |
|
||||
| `center` | 居中对齐 |
|
||||
| `right` | 右对齐 |
|
||||
|
||||
#### MultiByteEncoding (多字节编码)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `gbk` | GBK 编码（简体中文） |
|
||||
| `utf8` | UTF-8 编码（推荐） |
|
||||
| `big5` | BIG5 编码（繁体中文） |
|
||||
| `shiftJis` | Shift-JIS 编码（日文） |
|
||||
| `eucKr` | EUC-KR 编码（韩文） |
|
||||
|
||||
### PrinterPortHandle 类
|
||||
|
||||
| 属性/方法 | 类型 | 说明 |
|
||||
|-----------|------|------|
|
||||
| `handle` | `int` | 整数端口句柄 |
|
||||
| `isValid` | `bool` | 端口是否仍然有效 |
|
||||
| `close()` | `Future<void>` | 关闭端口，多次调用为 no-op |
|
||||
|
||||
### PrinterException 类
|
||||
|
||||
| 属性 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | `String` | 错误码 |
|
||||
| `message` | `String` | 错误消息 |
|
||||
| `details` | `dynamic` | 额外详情 |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 打印乱码怎么办？
|
||||
|
||||
- 确认编码设置与发送的文本编码一致，推荐使用 `MultiByteEncoding.utf8`
|
||||
- 确认打印机机型是否正确（票据机型使用 `CP_Pos_` 系列函数）
|
||||
- 检查波特率是否与打印机设置一致
|
||||
|
||||
### 2. 端口打开失败？
|
||||
|
||||
- 检查端口名称是否正确
|
||||
- 确认端口未被其他应用占用
|
||||
- 检查 USB 连接或串口线连接是否正常
|
||||
|
||||
### 3. 打印到一半停止？
|
||||
|
||||
- 检查电源是否充足（一般需要 2A 电源）
|
||||
- 检查是否缺纸
|
||||
Reference in New Issue
Block a user