158 lines
5.6 KiB
Markdown
158 lines
5.6 KiB
Markdown
# 打印机插件设计文档
|
||
|
||
**日期:** 2026-04-22
|
||
**状态:** 已确认
|
||
**目标:** 将 printer 插件开发为完整的打印插件，支持通过 CH34 串口 + autoreplyprint.aar 进行打印
|
||
|
||
## 1. 项目概述
|
||
|
||
### 用途
|
||
公司内部多个 Flutter 项目共用的打印插件，用于打印拉曼检测结果（简单文字票据）。
|
||
|
||
### 技术架构
|
||
- CH34 插件提供串口通道
|
||
- 本项目 Android 原生层集成 autoreplyprint.aar
|
||
- Dart 层通过 MethodChannel 调用原生层
|
||
- 底层指令式 API：调用方控制打开→打印→关闭全流程
|
||
|
||
## 2. 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 调用方 Flutter 项目 │
|
||
│ Printer.openComPort() → PrinterPortHandle │
|
||
│ handle.printText() → handle.close() │
|
||
└──────────────┬───────────────────────────────┘
|
||
│ MethodChannel 调用
|
||
┌──────────────▼───────────────────────────────┐
|
||
│ Flutter 插件 Dart 层 │
|
||
│ Printer → PrinterPlatform │
|
||
│ → MethodChannelPrinterPort │
|
||
│ → PrinterPortHandle │
|
||
└──────────────┬───────────────────────────────┐
|
||
│ MethodChannel + portHandle
|
||
┌──────────────▼───────────────────────────────┐
|
||
│ Android 原生层 (Java) │
|
||
│ PrinterPlugin (MethodCallHandler) │
|
||
│ → PortHandleManager │
|
||
│ → autoreplyprint.aar │
|
||
└───────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 3. API 设计
|
||
|
||
### 使用示例
|
||
```dart
|
||
// 打开端口
|
||
PrinterPortHandle port = await Printer.openComPort(
|
||
portName: 'COM3',
|
||
baudRate: 9600,
|
||
dataBits: 8,
|
||
parity: Parity.none,
|
||
stopBits: StopBits.one,
|
||
flowControl: FlowControl.none,
|
||
);
|
||
|
||
// 设置编码
|
||
await port.setMultiByteMode();
|
||
await port.setMultiByteEncoding(MultiByteEncoding.utf8);
|
||
|
||
// 打印
|
||
await port.setAlignment(Alignment.center);
|
||
await port.setTextScale(width: 2, height: 2);
|
||
await port.printText('拉曼检测结果报告');
|
||
|
||
// 走纸切纸
|
||
await port.feedLine(3);
|
||
await port.halfCutPaper();
|
||
|
||
// 关闭
|
||
await port.close();
|
||
```
|
||
|
||
### API 分类
|
||
|
||
| 类别 | 方法 |
|
||
|------|------|
|
||
| 端口管理 | `openComPort`, `close` |
|
||
| 打印文本 | `printText`, `printTextInUtf8`, `printTextInGbk` |
|
||
| 格式控制 | `setAlignment`, `setTextScale`, `setTextBold`, `setTextUnderline` |
|
||
| 走纸切纸 | `feedLine`, `feedDot`, `halfCutPaper`, `fullCutPaper` |
|
||
| 编码模式 | `setMultiByteMode`, `setSingleByteMode`, `setMultiByteEncoding` |
|
||
| 条码/二维码 | `printBarcode`, `printQRCode` |
|
||
| 图片 | `printRasterImageFromData` |
|
||
| 其他 | `resetPrinter`, `kickOutDrawer`, `beep` |
|
||
|
||
## 4. MethodChannel 协议
|
||
|
||
### 协议格式
|
||
```
|
||
MethodChannel 名称: "printer"
|
||
|
||
Method: "openComPort"
|
||
Args: { portName, baudRate, dataBits, parity, stopBits, flowControl, autoReplyMode }
|
||
Return: { success: bool, portHandle: int?, error: String? }
|
||
|
||
Method: "closePort"
|
||
Args: { portHandle }
|
||
Return: { success: bool, error: String? }
|
||
|
||
Method: "printText"
|
||
Args: { portHandle, text }
|
||
Return: { success: bool, error: String? }
|
||
|
||
... // 每个操作对应一个 method call
|
||
```
|
||
|
||
### 错误处理
|
||
- 原生层异常通过 `result.error()` 返回
|
||
- Dart 层统一包装为 `PrinterException`
|
||
|
||
## 5. 原生层设计
|
||
|
||
### 端口句柄管理
|
||
- `PrinterPlugin.java` 维护 `Map<Integer, Pointer> portHandles`
|
||
- `openComPort` 调用 `CP_Port_OpenCom` 返回 Pointer 存入 map
|
||
- 生成递增 int 作为 Dart 层 portHandle
|
||
- 每个 method call 从 map 中取出 Pointer，调用对应 AAR 函数
|
||
|
||
### AAR 集成
|
||
- 将 `docs/autoreplyprint.aar` 移至 `android/libs/`
|
||
- `build.gradle.kts` 配置 `implementation files('libs/autoreplyprint.aar')`
|
||
|
||
## 6. 项目结构
|
||
|
||
```
|
||
printer/
|
||
├── lib/
|
||
│ ├── printer.dart # 主入口
|
||
│ ├── printer_platform_interface.dart # 平台接口
|
||
│ ├── printer_method_channel.dart # MethodChannel 实现
|
||
│ └── src/
|
||
│ ├── models/
|
||
│ │ ├── parity.dart # 串口校验枚举
|
||
│ │ ├── alignment.dart # 对齐枚举
|
||
│ │ ├── encoding.dart # 字符编码枚举
|
||
│ │ └── printer_exception.dart # 自定义异常
|
||
│ └── port_handle.dart # 端口句柄封装
|
||
├── android/
|
||
│ ├── build.gradle.kts
|
||
│ ├── libs/
|
||
│ │ └── autoreplyprint.aar
|
||
│ └── src/main/java/com/xiarui/printer/
|
||
│ ├── PrinterPlugin.java
|
||
│ └── PortHandleManager.java
|
||
└── test/
|
||
└── printer_test.dart
|
||
```
|
||
|
||
## 7. 关键决策
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| SDK 集成方式 | 原生层调用 AAR | 利用已有封装，可靠 |
|
||
| API 风格 | 底层指令式 | 灵活，调用方控制流程 |
|
||
| 字符编码 | UTF8 | 中文支持，现代标准 |
|
||
| 连接方式 | 串口 (通过 CH34) | 项目实际硬件需求 |
|
||
| 状态回调 | 暂不需要 | 最小实现，后续可扩展 |
|