EZ Print Bridge 使用文档

01 / 快速开始

打印第一张标签

开始前，先在 Windows 中安装打印机官方驱动并打印一张系统测试页。EZ Print Bridge 使用 Windows 打印队列，只有系统能正常识别的打印机才会出现在软件中。

1. 1
   安装并启动软件

   运行安装包。首次启动自动进入 14 天试用，无需预装 .NET 或持续联网。

2. 2
   选择打印机

   在顶部打印机列表选择设备，点击旁边的设置按钮确认纸张规格、方向、打印速度和浓度。

3. 3
   设置标签尺寸

   在左侧输入实际宽度和高度，单位为毫米。软件尺寸与驱动中的纸张尺寸应保持一致。

4. 4
   添加标签内容

   点击或拖入文本、Code 128 条码、二维码、图片、边框或分隔线，在右侧修改内容和样式。

5. 5
   保存并试打

   将模板保存到固定的本机目录，然后点击“打印静态样张”检查实际尺寸与位置。

02 / 标签设计器

设计和保存标签或报表模板

03 / 变量模板

让一份模板承载不同数据

选择一个文本、条码或二维码元素，点击“插入变量”。变量名只能包含字母、数字和下划线，不能以数字开头，例如 product_name。插入后内容中会出现 {{product_name}}。

04 / 打印与校准

把预览和实物对齐

• 静态样张：使用模板默认值打印一张，适合检查版式、条码和二维码。
• 序列样张：指定张数后作为一个多页任务发送，序列变量按起始值、步进和补零规则生成。
• 偏移校准：内容整体偏左或偏上时调整 X/Y 偏移；不要移动每一个元素来补偿硬件误差。
• 清晰度：条码效果还取决于打印头 DPI、标签材质、碳带、速度、浓度和驱动设置。

05 / API 准备

启动本地打印服务

保持 EZ Print Bridge 运行，在顶部点击“启动 API”。状态栏显示以下地址后即可调用：

Invoke-RestMethod -Uri 'http://127.0.0.1:9191/api/health'

06 / API 参考

接口总览

基础地址为 http://127.0.0.1:9191，请求和响应使用 UTF-8 JSON。

校验请求后立即进入单消费者打印队列。成功提交不代表打印已经完成，请使用返回的 jobId 查询最终状态。

请求字段

data 支持字符串、数字、布尔值和 null；它们会转换为文本。对象或数组会转换为 JSON 文本。未提供的 API 变量使用模板默认值。

{
  "requestId": "order-20260716-001",
  "templatePath": "D:\\Labels\\Product_Label.ezl",
  "printerName": "Zebra ZD421",
  "copies": 10,
  "data": {
    "product_name": "冷萃咖啡",
    "batch": "B20260716",
    "price": 18.5
  }
}

成功响应

{
  "jobId": "7f3c512e-50ca-4af8-a021-ff340f15a120",
  "status": "Queued",
  "duplicate": false
}

响应还会包含 Location: /api/jobs/{jobId}。如果请求头和正文同时提供幂等 ID，两者必须完全一致。相同 ID 对应不同请求内容时返回 409 Conflict。

07 / 任务查询

确认任务是否真正完成

{
  "id": "7f3c512e-50ca-4af8-a021-ff340f15a120",
  "status": "Completed",
  "message": "API 任务已完成：10 张，打印机 Zebra ZD421",
  "createdAt": "2026-07-16T08:15:30.120+00:00",
  "updatedAt": "2026-07-16T08:15:31.006+00:00",
  "templatePath": "D:\\Labels\\Product_Label.ezl",
  "printerName": "Zebra ZD421",
  "copies": 10,
  "requestId": "order-20260716-001"
}

GET /api/jobs 返回最近 50 条任务数组。最多 500 条摘要持久化到 %APPDATA%\EZPrintBridge\api-jobs.json，不会保存完整 data。程序异常退出时未完成的任务会标记为 Failed，不会自动重打。

08 / 调用示例

从你的程序提交打印

$body = @{
  requestId   = 'order-20260716-001'
  templatePath = 'D:\Labels\Product_Label.ezl'
  printerName = 'Zebra ZD421'
  copies      = 2
  data        = @{ product_name = '冷萃咖啡'; batch = 'B20260716' }
} | ConvertTo-Json -Depth 5

$job = Invoke-RestMethod `
  -Uri 'http://127.0.0.1:9191/api/print' `
  -Method Post -ContentType 'application/json; charset=utf-8' -Body $body

Invoke-RestMethod -Uri "http://127.0.0.1:9191/api/jobs/$($job.jobId)"

const response = await fetch('http://127.0.0.1:9191/api/print', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-20260716-001'
  },
  body: JSON.stringify({
    templatePath: 'D:\\Labels\\Product_Label.ezl',
    printerName: 'Zebra ZD421',
    copies: 2,
    data: { product_name: '冷萃咖啡', batch: 'B20260716' }
  })
});

if (!response.ok) throw new Error(await response.text());
const job = await response.json();
console.log(job.jobId);

09 / 错误与排查

状态码和常见问题