ZPL 二维码 — ^BQ 命令完整指南
在 ZPL 中生成二维码所需的一切：^BQ 语法、参数、纠错、尺寸和复制粘贴示例——免费，无需注册。
TL;DR
ZPL 中的二维码由 ^BQ 命令生成。基本语法：^FOx,y ^BQ 方向,模型,放大倍数 ^FD <ECC><模式>,数据 ^FS。务必使用模型 2（模型 1 是旧版）。^FD 的 payload 以两个字母开头：第一个是纠错级别（H、Q、M、L），第二个是输入模式（A = 自动编码，M = 手动分段）。HA, 是物流/户外的安全默认（H 恢复 + 自动）。放大倍数（1-10）控制模块大小——在 203 dpi 的 4×6 英寸标签上从 5 开始。在格式内添加 ^CI28 以在 payload 中启用 UTF-8。
ZPL 中的二维码是什么？
ZPL 中的二维码是由 ^BQ 命令生成的二维条形码——Zebra 打印机支持的最强大符号体系之一。单个二维码可存储多达 4,296 个字母数字字符或 7,089 个数字，支持 Reed–Solomon 纠错（部分损坏或脏污仍可读），可被任何智能手机摄像头和工业扫描器识别。因此它是追踪 URL、vCard 名片、GS1 应用标识符、WiFi 凭据、交通票据以及超出 1D 条形码 20 字符最佳区间的任何 payload 的通用选择。
在 ZPL 中，二维码像任何其他字段一样存在于 ^XA..^XZ 格式中。用 ^FO 或 ^FT 定位，用 ^BQ 声明，并在 ^FD 中在逗号和实际数据之前加两个字符：第一个字符是纠错级别（H、Q、M 或 L），第二个是输入模式（A 表示自动编码选择，M 表示手动分段）。对于大多数生产用例，你写 ^FDHA,数据^FS——高恢复，自动编码。没有单独的 ^BY 宽度步骤，因为模块大小由放大倍数参数直接控制——在 203 dpi 的 4×6 英寸标签上典型值为 4 到 8。模型参数应始终为 2（模型 1 是旧版，不推荐用于新设计）。
^BQ 命令语法
最小二维码声明在 ^BQ 后接 3 个参数——方向、模型和放大倍数。纠错级别和输入模式作为 2 字符前缀加逗号放在 ^FD 内（见下方的「Field Data 格式」一节）。标准结构如下：
^XA
^CI28 ; 国际数据使用 UTF-8
^FO50,50 ; 位置 X=50, Y=50
^BQ 方向,模型,放大倍数 ; 方向 N/R/I/B，模型 2，放大 1-10
^FD <ECC><模式>,<payload>^FS ; ECC = H/Q/M/L，模式 = A（自动）或 M（手动）
^XZ
; 典型生产行：高恢复 + 自动编码
; ^FDHA,https://zplpdf.com^FS^BQ 参数
| 参数 | 描述 | 有效值 | 默认 |
|---|---|---|---|
| 方向 | QR 符号在标签上的旋转。物流标签用 N，垂直堆叠内容时用 R。 | N, R, I, B | N |
| 模型 | QR 模型。新设计始终使用 2。模型 1 是 1994 年的旧规范，大多数现代扫描器只针对模型 2。 | 1, 2 | 2 |
| 放大倍数 | 模块（点）大小乘数。每单位在 203 dpi 下每模块约增加 5 dots。值越大 = 二维码越大越易扫描，但占用更多标签空间。 | 1–10 | 依 dpi |
| ECC override | 在 ^BQ 命令本身的可选纠错覆盖。实际上此槽留空，级别由 ^FD 的第一个字符选择（H/Q/M/L）——见 Field Data 格式。 | H, Q, M, L | 空（用 ^FD 前缀） |
| 掩码值 | 当自然 payload 产生均匀区域时，可选的位模式掩码改善扫描器可读性。几乎不需要手动设置。 | 0–7 | 7 |
Field Data 格式：<ECC><模式>,数据
^BQ 的 ^FD payload 总是以逗号前的两个字符开头：第一个是纠错级别（H、Q、M 或 L），第二个是输入模式（A 表示自动编码选择，M 表示手动分段，你用 N/A/B/K 前缀标记每段编码）。下面的四张卡片显示你在生产中会用到的组合。选对组合是最重要的决定——大多数生产 bug 都源于误读这两个字符。
高恢复 + 自动（推荐默认）
HA,~30% 损坏恢复和自动编码选择。对于可能磨损的物流、货运和户外标签，这是最安全的选择。
^FO50,50^BQN,2,6^FDHA,https://zplpdf.com/track/A-7782^FS中等恢复 + 自动（通用）
MA,~15% 恢复——为干净的室内标签（办公、零售、电商）提供最佳的容量与可恢复性平衡。
^FO50,50^BQN,2,6^FDMA,SKU:COF-ORG-250^FS低恢复 + 自动（最大容量）
LA,~7% 恢复，最密集编码。仅当 payload 较长且标签在室内高分辨率打印时使用。
^FO50,50^BQN,2,6^FDLA,<带许多参数的长URL>^FS高恢复 + 手动模式（高级）
HM,手动模式允许在数据中用 N（数字）、A（字母数字）、B（字节）或 K（汉字）前缀按段标记编码。仅当自动模式产生次优编码时使用。
^FO50,50^BQN,2,6^FDHM,N0123456789AABC1234^FS纠错级别（H / Q / M / L）
Reed–Solomon 纠错允许二维码即使在符号部分缺失或损坏时仍可读。代价是容量：级别越高添加更多冗余，留给实际数据的空间越少。级别由 ^FD 前缀的第一个字符选择——HA 表示 H + 自动，MA 表示 M + 自动，依此类推。没有隐式默认值——你始终明确声明级别。对于物流和户外，HA 是推荐的起点；对于干净的室内标签，MA 节省空间。
| 级别 | 恢复 | 何时使用 |
|---|---|---|
| L | ~7% | 最大容量，干净的室内标签，高分辨率打印的营销海报。 |
| M | ~15% | 通用默认。办公、零售、电商标签的良好平衡。 |
| Q | ~25% | 暴露于磨损的热敏标签（仓库、货运）和稍微脏污的环境。 |
| H | ~30% | 户外标签、冷链，任何二维码可能被刮擦、弄脏或部分撕裂的地方。用 HA, 前缀选择。 |
尺寸和放大倍数
ZPL 中的二维码尺寸由放大倍数参数（1–10）控制——二维码没有 ^BY 步骤。每单位在 203 dpi 时将模块（二维码最小方块）乘以 4 dots，在 300 dpi 时乘以 6 dots。符号总大小取决于放大倍数和 payload 长度（数据越多 → 模块越多 → 代码越大）。
- 203 dpi 打印机 + 放大倍数 5 ≈ 200×200 dots ≈ 25×25 mm，带 50 字符 URL。
- 203 dpi 打印机 + 放大倍数 8 ≈ 320×320 dots ≈ 40×40 mm — 推荐用于 >50 cm 的户外扫描。
- 300 dpi 打印机 + 放大倍数 5 ≈ 300×300 dots ≈ 25×25 mm，带 50 字符 URL。
- 如果 URL 较短（≤25 字符）且标签距摄像头 20 cm 以内，智能手机可可靠读取放大倍数 3。
- 始终先在最慢的预期扫描器上测试；将放大倍数提高 1 比现场扫描失败更便宜。
- 低于 0.4 mm 的模块大小在大多数低端成像仪上变得不可读——203 dpi 打印机上保持放大倍数 ≥4。
复制粘贴二维码示例
下面每个示例都是完整的 ^XA..^XZ 块。粘贴到 ZPLPDF 查看器以查看打印机将精确产生的内容。
带高恢复的追踪 URL（最常见）
90% 的情况：用任何智能手机摄像头扫描时打开追踪 URL 的二维码。HA, 提供高纠错（~30% 恢复）加自动编码选择——是任何物流或电商标签的安全默认。
^XA
^CI28
^FO50,50
^BQN,2,6
^FDHA,https://zplpdf.com/track/A-7782^FS
^XZvCard 名片
存储完整联系人（姓名、电话、邮箱、组织）以便扫描标签时将联系人添加到智能手机。使用 MA,（中等恢复 + 自动）和放大倍数 7 以保持约 250 字符可扫描。
^XA
^CI28
^FO50,50
^BQN,2,7
^FDMA,BEGIN:VCARD\nVERSION:3.0\nN:李;明\nFN:李明\nORG:ZPLPDF Inc.\nTEL:+86-10-5555-0142\nEMAIL:liming@zplpdf.com\nEND:VCARD^FS
^XZGS1 应用标识符（制药）
按照 GS1 Digital Link 约定，在单个二维码中编码 (01) GTIN + (17) 有效期 + (10) 批次。常用于制药追溯——HA, 提供该标准期望的高恢复。
^XA
^CI28
^FO50,50
^BQN,2,6
^FDHA,https://id.gs1.org/01/07640123456789/17/270930/10/B25C-0481^FS
^XZWiFi 凭据（Android 与 iOS）
扫描二维码会自动将设备连接到 WiFi 网络。在包装或活动徽章上使用。将 SSID 和密码替换为你的值。MA,（中等 + 自动）对于干净的室内标签足够。
^XA
^CI28
^FO50,50
^BQN,2,6
^FDMA,WIFI:T:WPA;S:Office-Guest;P:Welcome2026;;^FS
^XZ高恢复户外/冷链标签
当标签可能被刮擦、弄脏或部分撕裂时（冷链、货运、恶劣物流），提高放大倍数并保持 HA, 前缀，以便二维码经受住部分损坏。
^XA
^CI28
^FO50,50
^BQN,2,8
^FDHA,FREIGHT-A-7782^FS
^XZ国际字符（UTF-8）
非 ASCII 字符（中文, ñ, ç, é）需要在格式内使用 ^CI28 以便打印机将 payload 视为 UTF-8。MA,（中等 + 自动）会透明地处理字节段；没有 ^CI28，数据中会显示 ?。
^XA
^CI28
^FO50,50
^BQN,2,6
^FDMA,客户订单 #A-7782\n姓名: 李明^FS
^XZ常见二维码错误及修复方法
二维码打印但扫描器无法读取。
→ 对于数据 payload 放大倍数过低——模块比扫描器最小值还小。
✓ 将放大倍数增加 2（例如 5 → 7），并确认模块宽度至少 0.4 mm。
扫描器读取但 UTF-8 字符显示为 ?。
→ ^BQ 前缺少 ^CI28——默认代码页删除非 ASCII 字节。
✓ 在 ^XA 后立即添加 ^CI28。HA,/MA, 自动输入模式会正确处理 UTF-8 字节。
二维码看起来呈块状，智能手机摄像头拒绝识别。
→ 在 ^BQ 中使用了模型 1（旧版）而不是模型 2。
✓ 使用 ^BQN,2,<mag>——新设计的模型槽始终为 2。
长 URL 打印但在部分磨损的标签上扫描失败。
→ 选择了低 ECC 级别（LA, 或 MA,），所以二维码无法承受部分损坏。
✓ 对任何可能在现场被磨损的标签使用 HA,（高恢复，~30% 损坏容忍）。
二维码周围多余的空白迫使标签过大。
→ 因为显式 ^FO 继承了格式中较早 1D 条形码的旧 ^BY 值，安静区过大。
✓ 在符号体系之间重置 ^BY，或简单地用 QR 自己的 ^FO 在任何先前 ^BY 块之外定位。
二维码在查看器上编码正确但在 Datalogic / Honeywell 扫描器上失败。
→ 工业成像仪通常需要最小模块大小和 4 模块的安静区。
✓ 将放大倍数增加到 ≥6，并在符号周围保持至少 4 模块的边距。