init
This commit is contained in:
Developer
157
docs/superpowers/specs/2026-04-22-printer-plugin-design.md
Normal file
157
docs/superpowers/specs/2026-04-22-printer-plugin-design.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 打印机插件设计文档
|
||||
|
||||
**日期:** 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) | 项目实际硬件需求 |
|
||||
| 状态回调 | 暂不需要 | 最小实现，后续可扩展 |
|
||||
Reference in New Issue
Block a user