EasyInk

Appearance

API 参考 ​

EasyInk.Printer 提供 HTTP 和 WebSocket 两种通信方式，默认端口 18080。

基础约定 ​

  • 基地址：http://localhost:18080/api/
  • 响应格式统一为 PrinterResult：
json
{
  "id": "请求ID",
  "success": true,
  "data": {},
  "errorInfo": null
}

错误时 success 为 false，errorInfo 包含 code 和 message。

HTTP API ​

打印机 ​

GET /api/printers ​

获取所有打印机。

bash
curl http://localhost:18080/api/printers

响应 data 结构：

json
{
  "printers": [
    {
      "name": "HP LaserJet Pro",
      "isDefault": true,
      "isOnline": true,
      "driverName": "HP Universal Printing PCL 6"
    }
  ]
}

GET /api/printers/{name}/status ​

获取指定打印机状态。

bash
curl http://localhost:18080/api/printers/HP%20LaserJet/status

响应 data 结构：

json
{
  "isReady": true,
  "statusCode": "READY",
  "message": "打印机就绪",
  "isOnline": true,
  "hasPaper": true
}

状态码：READY / PRINTER_OFFLINE / PAPER_JAM / PAPER_OUT / PRINTER_STOPPED / PRINTER_ERROR / PRINTER_NOT_FOUND

打印 ​

POST /api/print ​

同步打印，等待完成后返回结果。

JSON 方式（Base64 / URL）：

bash
curl -X POST http://localhost:18080/api/print \
  -H "Content-Type: application/json" \
  -d '{
    "printerName": "HP LaserJet",
    "pdfBase64": "JVBERi0xLjQK...",
    "copies": 1,
    "landscape": false,
    "dpi": 300
  }'

Multipart 方式（二进制 PDF）：

bash
curl -X POST http://localhost:18080/api/print \
  -F 'params={"printerName":"HP LaserJet","copies":1}' \
  -F 'pdf=@document.pdf'

参数：

字段类型必填说明
printerNamestring是打印机名称
pdfBase64string三选一Base64 编码的 PDF
pdfUrlstring三选一远程 PDF URL
pdfBytesbinary三选一二进制 PDF（multipart）
copiesint否份数，默认 1
landscapebool否横向打印
dpiint否分辨率，默认 300
paperSizeobject否自定义纸张 {width, height, unit}
offsetobject否打印偏移 {x, y}

POST /api/print/async ​

异步打印，立即返回 jobId。

bash
curl -X POST http://localhost:18080/api/print/async \
  -H "Content-Type: application/json" \
  -d '{"printerName":"HP LaserJet","pdfBase64":"..."}'

响应 data：

json
{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }

POST /api/print/batch ​

批量同步打印。

bash
curl -X POST http://localhost:18080/api/print/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"printerName":"Printer1","pdfBase64":"..."},
    {"printerName":"Printer2","pdfBase64":"..."}
  ]'

POST /api/print/batch/async ​

批量异步打印，返回 jobId 数组。

任务 ​

GET /api/jobs ​

获取所有任务。

bash
curl http://localhost:18080/api/jobs

GET /api/jobs/ ​

查询指定任务状态。

bash
curl http://localhost:18080/api/jobs/550e8400-...

响应 data：

json
{
  "jobId": "550e8400-...",
  "status": "Completed",
  "printerName": "HP LaserJet",
  "createdAt": "2025-01-01T00:00:00Z",
  "completedAt": "2025-01-01T00:00:01Z"
}

任务状态：Queued / Printing / Completed / Failed

审计日志 ​

GET /api/logs ​

查询审计日志，支持筛选。

bash
curl "http://localhost:18080/api/logs?printerName=HP&status=completed&limit=50"

参数：

字段说明
printerName按打印机名筛选（模糊匹配）
status按状态筛选
limit返回条数上限

服务状态 ​

GET /api/status ​

服务运行状态，包含版本、运行时间、内存使用。

bash
curl http://localhost:18080/api/status

WebSocket ​

连接地址：ws://localhost:18080/ws

文本帧（JSON 命令） ​

json
{
  "command": "print",
  "id": "uuid-1",
  "params": {
    "printerName": "HP LaserJet",
    "pdfBase64": "JVBERi0xLjQK...",
    "copies": 1
  }
}

二进制帧（大 PDF 上传） ​

┌────────────────┬─────────────────┬─────────────────┐
│ 4 字节 (uint32) │ N 字节 (JSON)    │ 剩余 (PDF 二进制) │
│ 元数据长度 N     │ 元数据           │ PDF 数据         │
└────────────────┴─────────────────┴─────────────────┘

分块上传 ​

大 PDF（最大 50 MB）可通过分块上传：

  1. 将 PDF 切分为 2 MB 的块
  2. 逐块发送 uploadPdfChunk 命令
  3. 最后发送 printUploadedPdf 或 printUploadedPdfAsync 触发打印

支持的命令 ​

命令说明
print同步打印
printAsync异步打印
getPrinters获取打印机列表
getPrinterStatus获取打印机状态
getJobStatus查询任务状态
getAllJobs获取所有任务
queryLogs查询审计日志
uploadPdfChunk分块上传 PDF
printUploadedPdf打印已上传的 PDF
printUploadedPdfAsync异步打印已上传的 PDF

前端示例 ​

ts
const ws = new WebSocket('ws://localhost:18080/ws')

ws.onopen = () => {
  // 获取打印机列表
  ws.send(JSON.stringify({
    command: 'getPrinters',
    id: crypto.randomUUID(),
  }))
}

ws.onmessage = (event) => {
  const result = JSON.parse(event.data)
  if (result.success) {
    console.log(result.data)
  }
}

// 打印
function print(printerName: string, pdfBase64: string) {
  ws.send(JSON.stringify({
    command: 'print',
    id: crypto.randomUUID(),
    params: { printerName, pdfBase64, copies: 1 },
  }))
}

认证 ​

设置 API Key 后，所有请求需携带 X-API-Key 头：

bash
curl -H "X-API-Key: your-secret-key" http://localhost:18080/api/printers

WebSocket 连接时通过 URL 参数传递：

ws://localhost:18080/ws?apiKey=your-secret-key

错误码 ​

错误码说明
INVALID_PARAMS参数缺失或格式错误
INVALID_JSONJSON 解析失败
UNKNOWN_COMMAND未知命令
JOB_NOT_FOUND任务不存在
QUEUE_FULL队列已满
SUMATRA_NOT_FOUNDSumatraPDF 未找到
PRINT_FAILED打印失败
PRINT_TIMEOUT打印超时
INVALID_PDF_SOURCEPDF 来源无效
UNAUTHORIZED认证失败
NOT_FOUND接口不存在