ZPLab

# ZPLab <img src="public/favicon.png" alt="ZPLab logo" width="64" align="right" /> [](https://github.com/u8array/ZPLab/actions/workflows/deploy.yml?query=branch%3Aprod) [](https://github.com/u8array/ZPLab/actions/workflows/pr.yml) [](LICENSE) 基于浏览器的 Zebra 打印机 ZPL 编辑器：可视化设计标签，或导入现有的 ZPL，进行编辑，再导出。 手动编写 ZPL（Zebra 编程语言）非常繁琐：晦涩的命令、点坐标，直到打印机输出前都没有视觉反馈。ZPLab 允许您可视化构建标签。只需将元素拖放到画布上，在属性面板中调整它们，然后复制或下载 ZPL。不需要安装，不需要 ZPL 知识。 现有的 ZPL 文件是一等公民，不仅仅是一次导入：重新导出的标签在字节层面保持不变，除非您实际编辑了对象（参见[导入保证](#import-guarantees)）；GS1 和 EAN/UPC 内容会逐字段验证。 **[试用](https://zplab.org/)** · [下载桌面应用](#download) · [报告问题](https://github.com/u8array/ZPLab/issues) > **免责声明：** 这是一个独立的开源工具，与 Zebra Technologies Corp. 无关，也未得到其认可或关联。Zebra 是 Zebra Technologies Corp. 的商标；所有其他商标归各自所有者所有。 --- <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/screenshot-dark.png"> <source media="(prefers-color-scheme: light)" srcset="docs/screenshot-light.png"> <img alt="ZPLab: designer with a sample label" src="docs/screenshot-light.png"> </picture> --- ## 下载 | 平台 | [v0.2.0](https://github.com/u8array/ZPLab/releases/tag/v0.2.0) | |---|---| | Windows | [x64 安装程序](https://github.com/u8array/ZPLab/releases/download/v0.2.0/ZPLab_0.2.0_x64-setup.exe) | | macOS | [Apple Silicon](https://github.com/u8array/ZPLab/releases/download/v0.2.0/ZPLab_0.2.0_aarch64.dmg) · [Intel](https://github.com/u8array/ZPLab/releases/download/v0.2.0/ZPLab_0.2.0_x64.dmg) | | Linux | [AppImage](https://github.com/u8array/ZPLab/releases/download/v0.2.0/ZPLab_0.2.0_amd64.AppImage) · [deb](https://github.com/u8array/ZPLab/releases/download/v0.2.0/ZPLab_0.2.0_amd64.deb) · [rpm](https://github.com/u8array/ZPLab/releases/download/v0.2.0/ZPLab-0.2.0-1.x86_64.rpm) | macOS 会阻止首次启动；在 *系统设置 > 隐私和安全* 中允许应用。 ## 使用 ### 1. 设置标签 标签尺寸和打印分辨率在页眉中显示（`宽度 × 高度 mm · dpmm`）。取消选择所有内容（点击空白画布）以在**属性**面板中编辑它们。 打印分辨率（dpmm = 每毫米点数）必须与您的打印机匹配。常见值：6 dpmm（152 dpi）、8 dpmm（203 dpi）、12 dpmm（300 dpi）、24 dpmm（600 dpi）。如果不确定，请查看打印机的手册；8 dpmm 是最常见的。 ### 2. 添加对象 将左侧面板中的项目拖放到画布上，或双击它们以添加到中心。 可用对象：文本、序列号（自动递增数字字段）、条形码（28 种符号，包括 Code 128、QR、DataMatrix、PDF417、Maxicode）、形状（框、线、椭圆）、图像和图形符号（®/©/™）。 <details> <summary>支持的条形码符号完整列表</summary> **一维线性：** Code 128、Code 39、Code 93、Code 11、Interleaved 2 of 5、Standard 2 of 5、Industrial 2 of 5、Codabar、LOGMARS、MSI、Plessey、GS1 Databar、Planet Code、Postal/POSTNET、EAN-13、EAN-8、UPC-A、UPC-E、UPC/EAN 2 位或 5 位补充、Code 49 **二维矩阵：** QR Code、DataMatrix、PDF417、MicroPDF417、Aztec、Codablock F、Maxicode、TLC39 </details> ### 3. 编辑属性 选择一个对象以在右侧的**属性**面板中配置它：内容、大小、字体、条形码选项等。 可以按住 Shift 或绘制一个选框来选择多个对象；位置更改将应用于所有选定的对象；调整大小一次只适用于一个对象。 ### 4. 打印或导出 底部的**ZPL 输出**面板显示生成的 ZPL。它在您编辑时实时更新。 - **复制**：将 ZPL 复制到剪贴板；将其粘贴到打印机软件中或直接发送到打印机 - **预览**：通过 [Labelary](https://labelary.com/) 渲染预览图像，或在桌面上，通过连接的打印机的固件（参见打印机设置） - **导出**（文件菜单）：下载 `.zpl` 文件 - **打印**（文件菜单）：打开 Labelary 预览并触发浏览器打印对话框 ### 导入现有的 ZPL 文件菜单 → **导入 ZPL**：直接粘贴 ZPL 代码，或打开 `.zpl` 文件。 > 导入会回溯文本、条形码、形状、图像（包括打印机存储和压缩图形）、标签头设置和模板字段（`^FN` 槽进入**变量**选项卡；`^FE` 内联嵌入如 `^FD#1#-#2#` 导入为字段内容中的 `«name»` 标记）。解析器无法识别的任何其他内容都会在导入报告中列出；它不会出现在画布上，但在导出的 ZPL 中会保留（如下所述）。 ### 导入保证 编辑导入的标签并再次导出： - **保留：** 您未触及的内容原样保留，包括字段、标签设置、注释、空格和编辑器未建模的命令。零编辑的导入/导出循环会精确地重现文件。 - **重新生成：** 只有您编辑、添加或删除的对象会从模型中重新发出。文件的其余部分会原样拼接回来。 - **完全重新生成回退：** 某些构造使得逐对象修补不安全：`^MU` 单位缩放、非默认 `^CC`/`^CT`/`^CD` 命令前缀、非 UTF-8 `^CI` 编码、非默认 `^FE` 嵌入分隔符、外部声明的裸 `^FN` 和依赖先前字段的条形码 `^BY`。在这样的标签上，第一次编辑会重新生成整个标签；如果没有编辑，导出会保持字节不变。 导入时的字节捕获故意保守：当字段无法干净地映射到单个对象时，整个标签会回退到模型重新生成，这会保留内容但不保留确切的字节。捕获的字节存储在保存的 `.json` 设计中；如果检测到来自旧应用版本的设计具有过时的捕获格式，则会检测并重建。 ### 多个标签（页面） 文件菜单 → **添加页面** 创建一个新页面。多个页面时，画布底部的控件会在它们之间切换并删除它们。所有页面共享相同的尺寸；导出和导入分别处理每个页面为单独的标签。 ### 从数据批量打印 文件菜单 → **导入 CSV 数据** 加载 CSV。映射对话框将每个变量与列配对，并与设计一起保存。**导出批量 ZPL** 或 **发送到 Zebra 打印机** 然后为每行输出一个标签。 在桌面上，**导入 Excel 数据** 读取工作表，**打印机设置… → 数据源** 从只读 SQLite/PostgreSQL/MySQL 数据库（操作系统钥匙串中的密码）中提取，通过相同的映射和批量输出。设计记得其数据库链接，以便一键重新加载。 ### 打印机设置 文件菜单 → **打印机设置…** 配置标签级别的媒体和打印质量，以及用于时钟、本地化、编码和打印机身份的设置脚本（用于打印机初次设置时发送）。设置脚本值在保存的设计中保持不变，因此共享 `.zpl` 或 `.json` 不会泄露打印机名称或本地化。 其**预览**选项卡选择哪个渲染器绘制叠加层（Labelary 的在线服务，或在桌面上，连接的打印机的固件），并包含可选的高级 Labelary 端点和 API 密钥；在桌面上，密钥存储在操作系统钥匙串中，在网络上存储在浏览器存储中。 ### 快捷键 | 快捷键 | 操作 | |---|---| | `Ctrl/⌘+Z` / `Ctrl/⌘+Shift+Z` | 撤销 / 重做 | | `Ctrl/⌘+A` | 全选 | | `Ctrl/⌘+C` / `Ctrl/⌘+V` | 复制 / 粘贴 | | `Ctrl/⌘+D` | 复制选区 | | `Ctrl/⌘+G` / `Ctrl/⌘+Shift+G` | 分组 / 取消分组选区 | | `Ctrl/⌘+L` / `Ctrl/⌘+Shift+L` | 锁定 / 解锁选区 | | `Del` / `Backspace` | 删除选区 | | 箭头键 / `Shift`+箭头 | 微调选区（捕捉步长 / 10 毫米） | | `G` | 切换网格 | | `S` | 切换捕捉 | | `R` | 旋转视图（0° → 90° → 180° → 270°） | | `Page Up` / `Page Down` | 上一页 / 下一页 | | `Alt/⌥`+点击 | 通过堆叠对象循环选择（选择下方） | | 中间鼠标 / 空格+拖动 | 平移画布 | | 滚动 | 平移画布 | | `Ctrl/⌘`+滚动 | 缩放 | ### 保存和加载 `.zpl` 和 `.json` 都可以无损回溯。`.zpl` 保留所有可打印内容，并作为设计源：重新导入它并继续编辑。`.json`（文件 → 保存设计）还存储设计者独有的状态，这些状态没有 ZPL 表示：锁定/隐藏对象、排除导出项、自定义对象名称和组结构。 --- ## 功能 - 智能对齐和间距指南 - 层面板，支持重新排序 - 无损 ZPL 回溯：导入的 ZPL 重新导出字节不变，只重新生成您编辑的内容（[导入保证](#import-guarantees)） - 变量：绑定文本和条形码字段到命名默认值，发出 `^FN` 槽（或 `^FE` 内联嵌入，当一个字段引用多个变量），与打印机侧模板往返 - 批量打印：从 CSV、Excel 工作表或只读数据库（桌面）映射列到变量，然后打印或导出具有高效打印机侧数据合并（模板发送一次，每行仅发送其覆盖） - GS1 内容构建器：从应用程序标识符（DataBar Expanded、GS1-128 和 GS1 DataMatrix）组装 GS1 内容，按字段验证并针对 GS1 组合规则验证 - 内容构建器：生成类型化的 QR/DataMatrix/Aztec 内容（URL、WiFi、联系人、电子邮件、电话、SMS、地理位置）并使用正确的编码和转义 - EAN/UPC 内联验证：实时长度计数器、计算校验位预览和 GS1 前缀提示直接在内容字段下 - 打印机设置：标签级别硬件调谐加上用于时钟、本地化、编码和打印机身份的设置脚本 - 32 种 UI 语言（自动从浏览器检测） - 浅色/深色模式（跟随操作系统设置） --- ## 覆盖范围 <!-- coverage:start (generated from docs/zpl-roadmap.md by scripts/gen-coverage.mjs; run `pnpm coverage:gen`) --> 204 个 ZPL II 命令中的 107 个已跟踪 [路线图](docs/zpl-roadmap.md)，今日支持。分类分解： | 区域 | 支持 | |---|---| | 布局和流程 | 16 / 16 | | 模板和变量 | 4 / 4 | | 条形码 | 28 / 28 | | 字段 | 17 / 20 | | 序列化 | 2 / 2 | | 编码和语言 | 3 / 4 | | 时钟和时间 | 3 / 3 | | 身份和访问 | 3 / 3 | | 图形 | 6 / 12 | | 媒体和馈送 | 8 / 10 | | 文本和字体 | 7 / 14 | | 打印质量 | 7 / 16 | | 配置和持久性 | 3 / 5 | | 硬件/主机通信/RFID/网络 | 0 / 67 | <!-- coverage:end --> --- ## 限制 - 画布是设计预览，而不是像素完美模拟。形状、间距和位置与打印匹配；文本在几点内近似 Zebra 内置字体，但确切的字母形状和抗锯齿不同。对于忠实的渲染，请使用右下角面板中的**预览**（Labelary 或桌面上的打印机固件）。 - 默认预览渲染器是 Labelary；网络构建调用 `api.labelary.com`，而自我托管者可以指向私有端点或关闭它（也可以在运行时设置高级端点和密钥，参见打印机设置）。桌面应用可以改为在连接的打印机上预览。 - Labelary 预览并不渲染每个 ZPL 功能。一些不太常见的元素（例如 Codablock F、Maxicode）可能在预览中缺失或错误，即使实际打印正常。 --- ## 开发 ```bash pnpm install pnpm dev ``` 需要 Node.js ≥ 24 和 pnpm。或者使用 `npm install` / `npm run dev`。 ```bash pnpm build # 输出到 dist/ ``` 网络构建输出完全静态，可以从任何网络服务器或文件主机提供服务。桌面应用是一个单独的 [Tauri](https://tauri.app/) 外壳（`src-tauri/`），具有本机打印机 I/O。 ### 技术栈 - [React 19](https://react.dev/) + TypeScript - [Vite](https://vite.dev/) - [Konva](https://konvajs.org/) / react-konva：画布渲染 - [Zustand](https://github.com/pmndrs/zustand) + [zundo](https://github.com/charkour/zundo)：状态和撤销历史 - [bwip-js](https://github.com/metafloor/bwip-js)：条形码渲染 - [Tailwind CSS v4](https://tailwindcss.com/) - [Tauri](https://tauri.app/)：桌面外壳（本机打印和文件对话框） ### 工作原理 编辑器将标签存储为 Zustand 中的对象列表。在每次更改时，通过将每个对象映射到其对应的 ZPL 命令，在客户端生成 ZPL II。条形码使用 bwip-js 在画布上渲染。预览图像来自 Labelary API 或桌面上的连接打印机固件。 --- ## 贡献 欢迎提出问题和拉取请求。 如果您发现 ZPL 文件导入不正确，请将 `.zpl` 文件附加到问题中，这是您能做的最有用的事情。 --- ## 许可证 MIT