mirror of
https://github.com/crmeb/CRMEB.git
synced 2026-10-28 21:40:50 +00:00
204 lines
5.7 KiB
Markdown
204 lines
5.7 KiB
Markdown
# 打印驱动扩展开发指南
|
||
|
||
## 概述
|
||
|
||
打印驱动扩展位于 `driver/printer/{Driver}/` 目录，负责对接各类云打印服务（飞鹅云、易联云等），用于订单小票打印。
|
||
|
||
系统通过 `crmeb\services\driver\DriverRegistry` 扫描各驱动包的 `plugin.json` 完成驱动注册。
|
||
|
||
## 已有驱动
|
||
|
||
| 驱动目录 | 驱动标识 | 说明 |
|
||
|---------|---------|------|
|
||
| [FeiEYun](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/printer/FeiEYun/) | — | 飞鹅云打印机 |
|
||
| [YiLianYun](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/printer/YiLianYun/) | — | 易联云打印机 |
|
||
|
||
## 开发步骤
|
||
|
||
### 1. 创建驱动目录
|
||
|
||
```bash
|
||
mkdir -p driver/printer/{DriverName}
|
||
```
|
||
|
||
### 2. 创建 plugin.json
|
||
|
||
```json
|
||
{
|
||
"key": "YourDriver",
|
||
"name": "打印驱动名称",
|
||
"description": "驱动描述",
|
||
"version": "1.0.0",
|
||
"author": "CRMEB",
|
||
"type": "driver",
|
||
"path": "driver/printer/YourDriver",
|
||
"require": {
|
||
"crmeb": "^6.0",
|
||
"php": "^8.0"
|
||
},
|
||
"driver": {
|
||
"name": "打印驱动名称",
|
||
"driver_key": "YourDriver",
|
||
"driver": "YourDriver",
|
||
"icon": "",
|
||
"description": "驱动描述",
|
||
"config_fields": [
|
||
{
|
||
"field": "api_key",
|
||
"label": "API Key",
|
||
"type": "text",
|
||
"required": true,
|
||
"group": "基础配置",
|
||
"tip": "输入说明"
|
||
},
|
||
{
|
||
"field": "api_secret",
|
||
"label": "API 密钥",
|
||
"type": "password",
|
||
"required": true,
|
||
"group": "基础配置"
|
||
},
|
||
{
|
||
"field": "device_sn",
|
||
"label": "设备编号",
|
||
"type": "text",
|
||
"required": true,
|
||
"group": "设备配置",
|
||
"tip": "打印机设备编号（SN）"
|
||
}
|
||
],
|
||
"help_doc": {
|
||
"title": "使用说明",
|
||
"steps": ["步骤1", "步骤2"],
|
||
"link": "https://example.com"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### plugin.json driver 子对象字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | ✅ | 驱动名称 |
|
||
| `driver_key` | string | ✅ | 驱动唯一标识 |
|
||
| `driver` | string | ✅ | 驱动目录名（打印驱动按目录名索引） |
|
||
| `icon` | string | ❌ | 图标 |
|
||
| `description` | string | ❌ | 驱动描述 |
|
||
| `config_fields` | array | ❌ | 配置字段 |
|
||
| `help_doc` | object | ❌ | 帮助文档 |
|
||
|
||
> 顶层字段（`key`/`name`/`description`/`version`/`author`/`type`/`path`/`require`）与通用 driver 插件一致，参见 [sms/DEVELOPMENT.md](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/sms/DEVELOPMENT.md) 的字段说明表。
|
||
|
||
### 3. 创建 Driver.php
|
||
|
||
```php
|
||
<?php
|
||
namespace driver\printer\{DriverName};
|
||
|
||
use crmeb\services\printer\BasePrinter;
|
||
|
||
/**
|
||
* {DriverName} 打印驱动
|
||
*/
|
||
class Driver extends BasePrinter
|
||
{
|
||
/**
|
||
* 初始化
|
||
* @param array $config
|
||
*/
|
||
protected function initialize(array $config): void
|
||
{
|
||
// 初始化配置
|
||
}
|
||
|
||
/**
|
||
* 开始打印
|
||
* @return bool|mixed|string
|
||
* @throws \Exception
|
||
*/
|
||
public function startPrinter()
|
||
{
|
||
if (!$this->printerContent) {
|
||
return $this->setError('Missing print');
|
||
}
|
||
// 调用打印API
|
||
$response = $this->accessToken->postRequest('http://api.example.com/open/', [
|
||
'content' => $this->printerContent,
|
||
'times' => $this->times,
|
||
]);
|
||
$res = json_decode($response, true);
|
||
if ($res['msg'] === 'ok') {
|
||
return $res;
|
||
}
|
||
return $this->setError($res['msg']);
|
||
}
|
||
|
||
/**
|
||
* 设置打印内容
|
||
* @param string $content 打印内容
|
||
* @param int $times 打印次数
|
||
* @return $this
|
||
*/
|
||
public function setPrinterContent($content, $times = 1): self
|
||
{
|
||
$this->times = $times;
|
||
$this->printerContent = $content;
|
||
return $this;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 验证驱动
|
||
|
||
```php
|
||
use crmeb\services\driver\DriverRegistry;
|
||
|
||
$drivers = DriverRegistry::scan('printer'); // 全部打印驱动
|
||
$class = DriverRegistry::getDriverClass('printer', 'your_driver_key'); // 完整类名 driver\printer\YourDriver\Driver
|
||
```
|
||
|
||
## 接口规范
|
||
|
||
### 必须实现的方法
|
||
|
||
| 方法 | 说明 | 返回值 |
|
||
|------|------|--------|
|
||
| `startPrinter()` | 开始打印 | `bool\|mixed\|string` |
|
||
|
||
### 打印内容格式
|
||
|
||
打印内容通常包含以下要素，需按各打印服务商要求的格式组装：
|
||
|
||
```
|
||
// 小票打印内容示例
|
||
<center>**订单小票**</center>
|
||
--------------------------------
|
||
商品名称 数量 价格
|
||
--------------------------------
|
||
商品A 1 ¥29.90
|
||
商品B 2 ¥19.80
|
||
--------------------------------
|
||
合计： ¥69.50
|
||
--------------------------------
|
||
订单号：ORD202501011234
|
||
时间：2025-01-01 10:00:00
|
||
```
|
||
|
||
## 典型配置字段
|
||
|
||
打印驱动通常需要以下配置：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `user_id` | text | 用户ID/开发者ID |
|
||
| `app_id` | text | 应用ID |
|
||
| `app_secret` | password | 应用密钥 |
|
||
| `device_sn` | text | 打印机设备编号（SN） |
|
||
| `enable_voice` | switch | 语音播报开关 |
|
||
|
||
## 参考实现
|
||
|
||
- [飞鹅云打印机](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/printer/FeiEYun/) — 飞鹅云API方式
|
||
- [易联云打印机](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/printer/YiLianYun/) — 易联云API方式
|