ZPL参考手册：编程语言、字体和格式
Zebra编程语言完整手册——结构、命令、字体、条形码以及可直接复制的发货、零售和物流标签示例。
TL;DR
ZPL（Zebra编程语言）自1980年代起就是热敏标签打印的事实标准。每个标签以^XA开始、^XZ结束。以^开头的命令位于格式内部；以~开头的命令用于打印机配置。坐标使用点（dots）表示（203 dpi = 8 dots/mm，300 dpi = 12 dots/mm）。内置字体0和A–H可覆盖大多数场景——字体0完全可缩放。最常用的条形码是^BC（Code 128，用于发货）、^BQ（QR，用于追踪）和^BE（EAN-13，用于零售）。使用^FO设置字段位置，使用^FD写入数据，每个字段以^FS结束。使用^CI28启用UTF-8和国际字符。
什么是ZPL（Zebra编程语言）？
ZPL是Zebra Programming Language的缩写，由Zebra Technologies在1980年代创建，用于驱动热敏标签打印机的页面描述语言。它是发货标签、仓库识别、零售价签和制药包装的行业标准，因为它紧凑、确定性强，并被所有Zebra打印机型号（ZD、ZT、ZE、ZQ、GK、GX、ZM以及较旧的105SL/110XiIII系列）支持。
ZPL程序是一个纯文本命令流，打印机逐行解释。每个命令以一个控制字符开头——^（caret）用于格式命令，~（tilde）用于配置命令——后跟两字符代码和可选的逗号分隔参数。ZPL II（当前版本）增加了图形、可下载字体、固定和序列化字段、多格式标签以及双向通信。相同的代码在每台Zebra打印机上都会打印相同的输出，这使ZPL成为全球标签生产的通用语言。
ZPL格式结构
每个可打印标签都是一个自包含的块，称为格式。格式以^XA开始，包含一个或多个字段，以^XZ结束。在块内，命令顺序很重要：打印机按状态顺序应用它们。一个字段——文本、条形码或图形——由位置命令（^FO或^FT）、内容命令（^A、^BC、^GB等）和分隔符（^FS）定义。^XA..^XZ之外的内容被视为打印机配置并立即执行。
- 每个标签格式以^XA开始、^XZ结束。之外的内容是配置，而非可打印内容。
- 以^开头的命令是格式命令，位于^XA..^XZ块内。
- 以~开头的命令是控制命令，用于配置打印机，可以独立发送（例如~JR重置打印机）。
- 每个可打印字段必须以^FS（字段分隔符）结束。忘记^FS是导致输出乱码的最常见原因。
- 参数以逗号分隔且按位置排列。缺失的参数会回退到打印机默认值或上一次设定的值。
- 在格式内使用^CI28启用UTF-8，支持非ASCII字符（重音符号、ñ、ç、é、ü、中文、西里尔字母）。
- 命令区分大小写。^FO和^fo不相同——始终使用大写。
- 命令之间的空白和换行被忽略，因此可以为可读性而格式化ZPL。
^XA ; 格式开始
^CI28 ; 启用UTF-8
^CF0,40 ; 默认字体0，尺寸40
^FO50,50 ; 位置 X=50, Y=50
^FDHello ZPL World^FS ; 打印文本，关闭字段
^FO50,120^BY3 ; 新字段+条形码宽度
^BCN,100,Y,N,N ; Code 128，高100点
^FD1234567890^FS ; 条形码数据，关闭字段
^XZ ; 格式结束 → 打印标签坐标系统与DPI
ZPL使用从标签左上角测量的点坐标定位每个元素。毫米或英寸与点之间的转换取决于打印机的打印密度（DPI）。了解标签的精确点数对像素级对齐至关重要，尤其是预打印表单和对标签尺寸要求严格的承运商（FedEx、UPS或Mercado Libre）。
- 203 dpi打印机：每毫米8点（每英寸203点）。4×6英寸标签为812×1218点。
- 300 dpi打印机：每毫米12点（每英寸300点）。相同的4×6标签为1200×1800点。
- 600 dpi打印机：每毫米24点。主要用于超精细零售价签和珠宝标签。
- ^FO x,y按字段边界框的左上角定位。
- ^FT x,y按文本基线定位——混合字体大小时很有用。
- Y向下增长。^FO0,0是左上角；203 dpi下^FO0,1218是6英寸标签的底部。
- 始终在100%缩放下测试；渲染工具可能会重新缩放预览，但打印机会按点坐标精确执行。
ZPL编程指南：从Hello World到发货标签
三个逐步丰富的示例。将每个示例粘贴到ZPL查看器中，即可看到打印机输出的精确效果。
步骤1 — Hello World
最小的有效ZPL程序。打开格式，使用默认可缩放字体0以40点高度在位置(50,50)打印单个文本字段，然后关闭格式。
^XA
^CF0,40
^FO50,50^FDHello ZPL^FS
^XZ步骤2 — 文本+Code 128条形码
添加Code 128条形码（^BC）——发货标签的标准。^BY在声明条形码之前设置模块宽度。由于Y标志，条形码会在下方渲染人类可读的数字。
^XA
^CF0,40
^FO50,50^FD订单 #1042^FS
^FO50,120^BY3
^BCN,100,Y,N,N
^FD1234567890^FS
^XZ步骤3 — 完整发货标签
组合可变文本、多行地址块、QR码和Code 128追踪条形码——真实电商发货标签的结构。
^XA
^CI28
^CF0,32
^FO40,40^FD收件人：^FS
^FO40,90^FB540,4,0,L,0^FD李明\&北京市朝阳区建国路1号\&100020 北京\&中国^FS
^FO40,260^FD订单 #A-7782^FS
^FO40,310^BY3^BCN,90,Y,N,N^FD1Z999AA10123456784^FS
^FO450,260^BQN,2,5^FDQA,https://example.com/track/A-7782^FS
^XZZPL命令参考
按用途分组的最常用ZPL II命令。对于每个命令，我们列出简短描述、可粘贴到查看器中的可用示例以及参数含义。
格式与控制
| 命令 | 描述 | 示例 | 参数 |
|---|---|---|---|
| ^XA | 标签格式开始。每个可打印标签的开头必需。 | ^XA ... ^XZ | 无 |
| ^XZ | 标签格式结束。将标签发送到打印队列。 | ^XA^FO50,50^FDHi^FS^XZ | 无 |
| ^FS | 字段分隔符。关闭当前字段。每个可打印元素之后必需。 | ^FO50,50^FD文本^FS | 无 |
| ^CI | 更改国际字符集。^CI28为重音符号和非拉丁文字启用UTF-8。 | ^CI28 | 28 = UTF-8, 13 = Latin-1 |
| ^CF | 整个标签的默认字体、高度和宽度。免去为每个字段重复^A。 | ^CF0,30,30 | 字体,高度,宽度 |
| ^LH | Label Home——平移所有坐标的原点(0,0)。 | ^LH30,30 | x,y 单位点 |
| ^PQ | 打印数量。^XZ之后发出N次相同标签。 | ^PQ5,0,0,N | 数量,暂停,复制,覆盖 |
| ~JR | 打印机重置。在格式外发送；打印机重启。 | ~JR | 无 |
定位与文本
| 命令 | 描述 | 示例 | 参数 |
|---|---|---|---|
| ^FO | 字段原点——按左上角定位下一个字段。 | ^FO50,80 | x,y 单位点 |
| ^FT | Field Typeset——按文本基线定位下一个字段。混合字体大小时最佳。 | ^FT50,80 | x,y 单位点 |
| ^A | 为下一个字段选择字体。局部覆盖^CF。 | ^A0N,40,40 | 字体,方向,高度,宽度 |
| ^FD | 字段数据。要打印的字面文本或数值。 | ^FD订单 #42^FS | 文本（最多3072字符） |
| ^FB | 字段块——具有自动换行和对齐方式的多行文本。 | ^FB400,3,0,L,0^FD…^FS | 宽度,最大行数,行间距,对齐,缩进 |
| ^FN | 字段编号——稍后通过^FN数据填充的模板占位符。 | ^FN1^FS | 1–999 |
| ^SN | 序列号——在打印任务的副本之间自动递增。 | ^SN001,1,Y | 起始,增量,补零 |
条形码
| 命令 | 描述 | 示例 | 参数 |
|---|---|---|---|
| ^BY | 默认条形码模块宽度和比例。必须在条形码命令之前。 | ^BY3,3,100 | 模块宽度,比例,高度 |
| ^BC | Code 128条形码——发货/物流的标准。 | ^BCN,100,Y,N,N | 方向,高度,下方文本,上方文本,校验位 |
| ^BQ | QR码——URL、JSON、追踪ID。最多7089个数字字符。 | ^BQN,2,5 | 方向,模型,放大 |
| ^BE | EAN-13——全球零售商品代码（13位）。 | ^BEN,100,Y,N | 方向,高度,下方文本,上方文本 |
| ^BU | UPC-A——北美零售商品代码（12位）。 | ^BUN,100,Y,N | 方向,高度,下方文本,上方文本 |
| ^BX | Data Matrix——用于小物品和制药的高密度2D码。 | ^BXN,200,200 | 方向,高度,质量 |
| ^B0 | Aztec——用于交通票务和SmartCard标签的2D码。 | ^B0N,7,N,0,N | 方向,放大倍数(1-10),ECI(Y/N),纠错控制(0-300),菜单(Y/N) |
| ^B7 | PDF417——用于驾照和发货的堆叠2D条形码。 | ^B7N,8,5,10,30,N | 方向,行高,安全级(0-8),列(1-30),行(3-90),截断(Y/N) |
图形
| 命令 | 描述 | 示例 | 参数 |
|---|---|---|---|
| ^GB | 图形框——矩形、边框、分隔符。 | ^GB300,2,2,B^FS | 宽度,高度,粗细,颜色 |
| ^GC | 图形圆形。 | ^GC100,3,B^FS | 直径,粗细,颜色 |
| ^GD | 图形对角线。 | ^GD200,200,2,B,R^FS | 宽度,高度,粗细,颜色,方向 |
| ^GF | 图形字段——嵌入位图（ASCII或压缩）。 | ^GFA,1024,1024,32,… | 格式,字节,总数,每行字节,数据 |
| ^FR | 字段反向打印——字段内黑白反转。 | ^FO50,50^FR^GB100,30,30^FS | 无 |
ZPL字体：内置与可缩放
Zebra打印机出厂时配备一组固定的位图字体（A到H）和一种完全可缩放字体（0）。字体0是唯一可通过^CF或^A设置任意高度和宽度的字体；位图字体具有固定大小，可拉伸但无法清晰重绘。^A命令为单个字段选择字体+大小；^CF设置整个标签的默认值。
| 代码 | 名称 | 大小 | 说明 |
|---|---|---|---|
| 0 | 字体0（CG Triumvirate） | 可缩放，任意高度/宽度 | 默认可缩放字体。最适合价格、标题、动态尺寸内容。 |
| A | 字体A | 9 × 5 点（固定） | 最小的位图字体。适合细小文字和密集标签。 |
| B | 字体B | 11 × 7 点（固定） | 比A略大。常用于条目项。 |
| C / D | 字体C、D | 18 × 10 点（固定） | 用于可变字段的中等大小位图。 |
| E | 字体E | 28 × 15 点（OCR-B） | 适合光学字符识别。 |
| F | 字体F | 26 × 13 点 | 通用较大位图字体。 |
| G | 字体G | 60 × 40 点 | 显示尺寸，用于标题。 |
| H | 字体H（OCR-A） | 21 × 13 点 | OCR-A标准，为机器读取而设计。 |
| P–V | 软字体P–V | 可变 | 字母P、Q、R、S、T、U、V——旧固件中的旧位图字体。 |
^XA
^CF0,50,50 ; 默认字体0为50x50
^FO50,50^FDPrice: $19.99^FS
^FO50,120^ABN,30,15 ; 显式字体B
^FDSKU: ABC-001^FS
^FO50,170^A0N,80,80 ; 内联大字体0
^FDSALE^FS
^XZZPL中的条形码
ZPL原生渲染所有常见的1D和2D符号。始终在条形码命令之前声明^BY（模块宽度和比例），以保证扫描器正常读取。
Code 128
^BC发货、物流、包裹追踪。数字+字母。FedEx、UPS、USPS的行业默认。
^FO50,50^BY3^BCN,100,Y,N,N^FD1234567890^FSQR Code
^BQURL、JSON负载、追踪ID。最多7089个数字字符。广泛的读取器支持。
^FO50,50^BQN,2,6^FDQA,https://zplpdf.com^FSEAN-13
^BE全球零售产品代码。恰好12位数字——第13位为自动校验。
^FO50,50^BY2^BEN,100,Y,N^FD750123456789^FSUPC-A
^BU北美零售。11位数字+自动校验。
^FO50,50^BY2^BUN,100,Y,N^FD01234567890^FSData Matrix
^BX制药UDI、电子产品、超小物品。任意角度可读。
^FO50,50^BXN,200,200^FDPharmaCode-42^FSAztec
^B0交通票务、登机牌。紧凑，无需静默区。
^FO50,50^B0N,7,N,0,N^FDBOARDING-A14^FSPDF417
^B7驾照、身份证、发货。堆叠2D，容量约1.1 KB。
^FO50,50^B7N,8,5,10,30,N^FDLastName/FirstName/DOB^FSCode 39
^B3内部库存、资产标签。字母数字，但密度低于Code 128。
^FO50,50^BY3^B3N,N,100,Y,N^FDASSET-001^FS完整ZPL示例（复制粘贴即用）
可直接放入ZPLPDF查看器的可运行程序。每个示例都是在203 dpi、4×6英寸标签上测试过的完整^XA..^XZ块。
发货标签——电商包裹
发件人、收件人、Code 128追踪条形码和用于追踪URL的QR码。
^XA
^CI28
^PW812
^LL1218
^CF0,28
^FO40,40^FDFROM:^FS
^FO40,80^FB400,3,0,L,0^FDZPLPDF Warehouse\&500 Logistics Ave\&Miami, FL 33101^FS
^FO40,210^FDTO:^FS
^FO40,250^A0N,38,38^FB500,4,0,L,0^FD李明\&北京市朝阳区建国路1号\&100020 北京\&中国^FS
^FO40,520^GB720,2,2,B^FS
^FO40,540^FD追踪号：^FS
^FO40,580^BY3^BCN,110,Y,N,N^FD1Z999AA10123456784^FS
^FO520,540^BQN,2,6^FDQA,https://zplpdf.com/track/1Z999AA10123456784^FS
^FO40,820^FD订单 #A-7782^FS
^FO40,860^FD2026-05-21^FS
^XZEAN-13零售价签
产品名称、SKU、EAN-13条形码和反向打印框突出的价格。
^XA
^CI28
^CF0,40
^FO40,30^A0N,50,50^FD有机咖啡 250g^FS
^FO40,100^FDSKU: COF-ORG-250^FS
^FO40,150^BY2^BEN,100,Y,N^FD750123456789^FS
^FO40,290^GB300,80,80,B^FS
^FO50,300^FR^A0N,60,60^FD¥ 89.00^FS
^XZ药品标签与Data Matrix（GS1）
药品名称、批次和到期日，搭配携带GS1应用标识符的Data Matrix——常见于制药供应链。
^XA
^CI28
^CF0,32
^FO40,40^A0N,44,44^FD对乙酰氨基酚 500 mg^FS
^FO40,100^FD批次：B25C-0481^FS
^FO40,150^FD有效期：2027-09^FS
^FO40,200^BXN,200,200^FD>;(01)07640123456789(17)270930(10)B25C-0481^FS
^XZ序列化批次——50张唯一标签
^PQ50打印50份；^SN在每份上自动递增序列号。
^XA
^CF0,40
^FO50,50^FD批次SN^FS
^FO50,120^A0N,80,80^SN0001,1,Y^FS
^PQ50,0,0,N
^XZ常见ZPL错误及修复方法
标签空白或跳过纸张。
→ 末尾缺少^XZ，或^XA与^XZ之间有多余字符。
✓ 确保格式以^XA开始、^XZ结束，且没有杂散字节破坏数据流。
文本显示?而不是重音符号（á、é、ñ）。
→ 默认编码为CP-850，无法承载UTF-8字节。
✓ 在^XA之后立即添加^CI28，将打印机切换到UTF-8。
条形码打印但扫描器无法读取。
→ 模块宽度太小或比例超出规格。
✓ 在条形码之前设置^BY3,3,100，并确保其周围有静默区。
字段出现在错误的位置。
→ 混用^FO和^FT——它们使用不同的参考点。
✓ 选择其一：^FO（边界框左上角）或^FT（文本基线）。不要在标签中途切换。
多行文本超出标签边缘。
→ 未使用^FB时^FD不会自动换行。
✓ 在^FD之前将多行文本包裹在^FB宽度,最大行数,行间距,对齐,缩进中。
图像（^GF）打印损坏。
→ 字节数或每行字节数与数据长度不匹配。
✓ 使用已知工具重新编码图像——每行字节数必须等于ceil(宽度/8)。