Labelize 源码 · v1.12.0 发行版 · 在线 Playground

Rust crate 许可证为 MIT AND BSD-3-Clause。

这篇帖子最早介绍的是 ZPL 和 EPL 渲染。现在 Labelize 支持 ZPL、EPL、TSPL/TSC、CPCL 和 DPL，可以在本机把标签指令转换成 PNG 或 PDF。

为什么做这个工具

做物流系统的同学应该都接触过 ZPL（Zebra Programming Language）。这是 Zebra 打印机使用的标签描述语言。日常开发中经常有一个需求，就是不连接打印机，先看看标签渲染出来是什么样。我最初用 Rust 写 Labelize 是为了这个预览需求，后来逐步加入了更多语言和接入方式。需要把标签数据留在自己的环境里时，可以在本机使用 CLI，也可以把 HTTP 服务部署到自己的系统里。

现在能做什么

• 渲染条码和图形。 支持文字、图形字段和多种一维、二维条码，包括 Code 128、QR Code、Data Matrix、PDF417、Aztec 和 MaxiCode。不同打印语言的命令覆盖见支持的语言。
• 导出 PNG 和 PDF。 默认输出黑白栅格，可以开启抗锯齿保留灰度边缘。矢量 PDF 可保留受支持的文字和图形，文字可以搜索，位图仍按位图嵌入。矢量场景也能按比例生成更高分辨率的 PNG，同时保留标签的物理尺寸。矢量输出说明
• 把图片转成打印指令。 可以将 PNG、JPEG 等图片转成 ZPL 的 ^GFA 或 TSPL 的 BITMAP，用在已有的打印流程里。
• 在不同环境复用同一引擎。 提供 Rust crate、CLI、HTTP 服务、WASM/npm 和 Android AAR。在线 Playground 可以粘贴标签指令并切换输出选项，API 控制台可以试请求和复制调用示例。

快速上手

命令行

macOS 或 Linux 可以用 Homebrew 安装。Windows 的 CLI 在发行页。

brew tap GOODBOY008/homebrew-labelize && brew install labelize

# 渲染一张 ZPL 标签，生成 label.png
labelize convert label.zpl

# 将包含多个 ^XA ... ^XZ 格式的文件保存为一份矢量 PDF
labelize convert labels.zpl --mode vector --type pdf --all-pages -o labels.pdf

# 把 PNG 转为 TSPL 打印指令，生成 label.tspl
labelize encode label.png -l tspl

自托管 HTTP 服务

先启动服务，再在另一个终端提交文件。

labelize serve --host 127.0.0.1 --port 8080

curl -X POST http://127.0.0.1:8080/convert \
  -H 'Content-Type: application/zpl' \
  --data-binary @label.zpl \
  -o label.png

请求参数和批量转换示例见API 文档。

作为 Rust 库使用

在 Cargo.toml 的依赖里添加 labelize = "1.12"。高层 API 接收原始字节，可以自动识别打印语言。

use labelize::{render_png, RenderOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let zpl = b"^XA^FO50,50^A0N,40,40^FDHello^FS^XZ";
    let output = render_png(zpl, RenderOptions::default())?;
    std::fs::write("label.png", output.bytes)?;
    Ok(())
}

JavaScript 可以通过 @goodboy008/labelize-wasm 接入。Android 的 AAR 随发行版提供。WASM 指南 · Android 指南

渲染与验证

各语言的解析器先把打印指令转成统一的标签模型，渲染层再据此排版文字、条码和图形。v1.12.0 增加了 ZplParser::parse_with_options。接收完整 ZPL 任务时，可以读取有效的 ^PW 和 ^LL 尺寸，检查 ^XA 与 ^XZ 是否配对，并限制 ^PQ 展开后的标签数量。Studio 的 ZPL 接收链路使用了这个接口。架构说明

v1.12.0 的回归报告覆盖 56 个标签场景、112 个针对性用例和 8 个图片转指令再渲染的用例。像素对照按用例记录参考来源和容差。矢量 PDF 还会检查绘制结构、文字搜索和物理尺寸，并通过 PDFium、Poppler 和条码解码器验证输出。标签差异报告 · 测试说明

Labelize Studio 桌面工作台

实际工作里还经常要打开几份标签对照，或直接设计一张标签。我在同一个引擎之上做了 Labelize Studio，桌面界面使用 Rust + GPUI。它有多标签页工作台、可视化设计器、PDF/PNG 导出和名为 Labelize Printer 的虚拟打印队列。Studio v0.5.0 使用 Labelize 1.12.0 处理打印语言任务，提供 Windows、macOS 和 Debian 安装包。

社区里的 Studio 介绍 · Studio 源码 · Studio 安装包

适用场景与反馈

• 物流标签预览，在发送到打印机前先检查效果
• 仓储管理，批量转换标签为 PDF 存档
• 电商系统，通过 Rust 库或 HTTP 服务生成标签图片
• 自动化流程，校验指令并对照预期输出

项目还在补齐各语言的命令覆盖和渲染精度。如果你也在做物流或仓储系统，欢迎试用和反馈。遇到渲染差异时，可以附上脱敏后的最小标签样例、纸张尺寸和打印分辨率。

⭐ 如果觉得有用，给个 Star 支持一下。Labelize GitHub