跳到主内容
版本: 2.x

热敏模板

WP 后台: 热敏模板在 WP Admin → POS → Templates 中编辑。

热敏模板是一个用 XML 编写的简短文本文件,用来为收据打印机排版收据。无论打印机使用哪种打印机语言(ESC/POS、StarPRNT 或 Star Line Mode),同一个文件既用于绘制屏幕上的预览,也用于告诉打印机打印什么。它使用与 HTML 模板相同的 {{placeholders}} 来填入订单数据。所有占位符都列在收据数据中。

在打印机设置中设置的任何收据打印机,都请使用热敏模板。

快速跳转: 制作热敏模板 · 模板与打印机 · 可用标签 · 示例:简易 80mm 收据 · 模板预览 · 出现问题时

制作热敏模板​

从模板库中的模板开始,再修改它。无需从零开始编写。

  1. 打开模板库。 在 WP 后台中,进入 POS → 模板。在模板库中,将格式筛选为 ESC/POS(热敏打印机)。
  2. 复制模板。 点击卡片上的使用模板,例如 Simple Thermal Receipt (80mm)。副本会出现在您的模板中。开启其启用开关。
  3. 编辑模板。 打开您的副本。在左侧修改 XML,右侧的预览会随输入实时更新。点击更新保存。编辑器不会自动保存。
  4. 发送到收据打印机。 在 POS 中,进入设置 → 打印。在收据模板下,在模板旁选择您的收据打印机,或保持自动。
  5. 打印收据。 在收据界面的模板下选择您的模板,然后点击打印收据。

示例:修改感谢语​

首先检查店铺的收据页脚备注。如果已设置备注,它会取代感谢语打印出来,因此请改在自定义收据中修改备注。如果没有设置备注,请继续阅读本节。

在 Simple Thermal Receipt (80mm) 中,在编辑器靠近底部的位置找到 {{i18n.thank_you_purchase}}。只把这个占位符替换成您自己的话。

修改前:

{{i18n.thank_you_purchase}}

修改后:

See you again soon!

该行中位于它前后的其他内容保持原样。

整行感谢语,修改前后对比
{{^store.personal_notes}}<text>{{i18n.thank_you_purchase}}</text>{{/store.personal_notes}}
{{^store.personal_notes}}<text>See you again soon!</text>{{/store.personal_notes}}

点击更新。预览会在收据底部显示新的一行。

本页其余部分介绍第 3 步中可以写些什么。有关模板库的更多信息,请参阅自定义收据。

模板与打印机​

有些内容是在打印机上设置的,而不是在模板中。在 POS 中,进入设置 → 打印,点击打印机所在行的编辑。

网络 Epson 打印机的编辑打印机界面:打印机语言 ESC/POS,纸张宽度 48 — 80 mm,大多数 Epson 和 Star 打印机,收据语言自动,自动切纸、自动打开钱箱和设为默认开关,以及将收据打印为图像
  1. 打印机语言 — 此处为 ESC/POS。同一个模板适用于全部三种语言。
  2. 纸张宽度 — 此处为 48。在纸上,它会取代模板中的 paper-width。
  3. 收据语言 — 打印机打印时使用的字母和符号集。仅适用于 ESC/POS。
  4. 将收据打印为图像 — 将整张收据打印为一张图片。

开启自动打开钱箱后,其下方会出现钱箱连接器:

编辑打印机的底部:自动打开钱箱已开启,钱箱连接器设为引脚 2 / 钱箱 1,设为默认,以及打开钱箱、测试打印和关闭按钮
  1. 自动打开钱箱 — 在收据之后打开钱箱,除非模板自带 <drawer />。
  2. 钱箱连接器 — 此处为引脚 2 / 钱箱 1。当标签未指定连接器时,<drawer /> 使用它。
  3. 打开钱箱 — 只打开一次钱箱,不打印。
  4. 测试打印 — 打印应用的测试页打印机诊断,而不是您的模板。如果像此处一样开启了自动打开钱箱,它也会打开钱箱。

请特别留意纸张宽度。模板中的 paper-width 只决定预览的宽度。在纸上,以打印机的纸张宽度为准。width="*" 的列会占用其他列之后剩余的空间(自适应伸展的列)。请在您使用的每种纸张宽度上检查效果(收据宽度)。

影响收据的打印机设置
打印机设置对热敏模板的影响
纸张宽度(32、42、48 或 64)纸上每行的字符数。打印时它会取代模板中的 paper-width。请参阅收据宽度。
打印机语言ESC/POS、StarPRNT 或 Star Line Mode。同一个模板可在这三种语言上打印。
收据语言(仅 ESC/POS)打印机打印时使用的字母和符号集。
自动打开钱箱在收据之后打开钱箱,除非模板自带 <drawer />。
钱箱连接器引脚 2 / 钱箱 1 或 引脚 5 / 钱箱 2。仅在自动打开钱箱开启时显示。当 <drawer /> 未指定连接器时使用它。
将收据打印为图像将整张收据打印为一张图片。适用于打印机无法以文本打印的文字,例如阿拉伯语、希伯来语和泰语。比文本打印更慢。

可用标签​

下面每个标签都有各自的小节和示例。标签内的设置(例如 width="2")都是可选的,除非标明必填。

所有元素和属性一览表
标签打印内容及其设置(省略某项设置时的效果)
<receipt>必填。包裹整个模板。
paper-width (48)
<text>一行文字。
<bold>、<underline>、<invert>带样式的文字。<invert> 为黑底白字。
<size>放大文字,1–8 倍。
width (1), height (等同于 width)
<align>对齐其内部内容。
mode: left, center, right (left)
<row> + <col>并排的列。
width:一个数字或 * (12); align: left, right (left)
<line />横跨纸张的一条线。
style: single, double, dashed, dotted (single)
<feed />空白行。
lines (1)
<barcode>内部文字的条形码。
type (code128), height (40)
<qrcode>内部文字的二维码。
size (4)
<image />徽标或图片。
src (必填), width 以打印机点数计 (200)
<cut />切纸。
type: full, partial (partial)
<drawer />打开钱箱。
connector: pin2, pin5 (打印机的设置)

数字必须是大于零的整数。其他任何值(例如 width="1.5" 或 lines="0")都会被忽略,标签会使用其通常的值。不在此表中的标签会被跳过,但其内部的文字仍会打印。

<receipt> 标签​

每个热敏模板都以 <receipt> 作为开头和结尾:

<receipt paper-width="48">
<!-- 48 characters = 80 mm paper on most Epson and Star printers -->
<!-- 32 characters = 58 mm paper -->
</receipt>

paper-width 设置预览的宽度,以字符计。在纸上,以打印机的纸张宽度为准(模板与打印机)。

粗体、下划线和反色文字​

<text>Plain text</text>
<bold><text>Bold text</text></bold>
<underline><text>Underlined text</text></underline>
<invert><text>Inverted (white on black)</text></invert>

单独一个样式标签不会结束该行,因此请在其中放入 <text>。<text> 会在其文字之后结束该行(包裹带样式的标题)。在居中或右对齐的 <align> 内有一个例外(居中的带样式标题)。

左对齐、居中和右对齐​

<align mode="left"><text>Left aligned</text></align>
<align mode="center"><text>Centered</text></align>
<align mode="right"><text>Right aligned</text></align>

任何其他 mode 都按左对齐打印。

放大文字​

将文字放宽、加高,或两者兼有:

<size width="2" height="2"><text>Double-size text</text></size>
<size width="2" height="1"><text>Wide text</text></size>
<size width="1" height="2"><text>Tall text</text></size>

如果省略 height,它与 width 相同。ESC/POS 打印机最大可放大 8 倍;Star 打印机最大为 6 倍。

列​

使用 <row> 和 <col> 将文字分列并排放置:

<row>
<col width="16">Item name</col>
<col width="4" align="right">Qty</col>
<col width="12" align="right">Price</col>
</row>

这些宽度之和为 32,即最窄的纸张,因此这一行适合所有打印机。在更宽的纸上,该行剩余部分保持空白。

列宽以字符计。给某一列设置 width="*",它会占用剩余的空间,使这一行刚好适合纸张:

<row>
<col width="*">{{name}}</col>
<col width="12" align="right">{{line_total_display}}</col>
</row>
  • <col> 可以 left 或 right 对齐。列不能居中。
  • <row> 之外的 <col> 会被跳过。
  • 列只打印其文字。<col> 内的样式(<bold>、<size> 等)会显示在预览中,但不会打印在纸上,除非开启了将收据打印为图像。模板库中的模板就是这样给“总计”加粗的(例如 Simple Thermal Receipt (80mm)),因此它们的“总计”是以普通字体打印的。若要将整行加粗打印,请把 <bold> 放在 <row> 外面。
示例:加粗打印的“总计”行
<!-- Prints bold on paper -->
<bold>
<row>
<col width="*">{{i18n.total}}</col>
<col width="16" align="right">{{totals.total_display}}</col>
</row>
</bold>

线条和空白​

<line /> <!-- Single line -->
<line style="double" /> <!-- Double line -->
<line style="dashed" /> <!-- Dashed line -->
<line style="dotted" /> <!-- Dotted line -->
<feed lines="2" /> <!-- Two blank lines -->

预览以不同方式绘制每种样式。在纸上,single 和 dashed 看起来相同。

各线条样式在纸上的打印效果
  • single 和 dashed 都会在纸上打印一整行 - 字符。
  • dotted 在纸上打印 . . . .。在应用通过 ePOS(Epson 自有的网络连接;即浏览器中的 Epson 网络打印机,或桌面应用中打印机在其 ePOS 端口应答时)连接的 Epson 打印机上,它与 single 一样打印 -。
  • double 打印一整行双线字符。通过 ePOS 和云打印时,它打印一整行 =。

切纸和打开钱箱​

<cut /> <!-- Partial cut (leaves a small tab) -->
<cut type="full" /> <!-- Full cut -->
<drawer /> <!-- Open the cash drawer -->
<drawer connector="pin5" /> <!-- Open the drawer on pin 5 -->
  • <cut /> 会先将纸张送到切刀处。预览以带 ✂ 的虚线显示切纸。在应用通过 ePOS 连接的 Epson 打印机上,<cut /> 和 <cut type="full" /> 的切法相同。
  • 无论自动打开钱箱如何设置,<drawer /> 都会打开钱箱。当模板自带 <drawer /> 时,应用不会再次打开钱箱。预览中不显示它。请参阅钱箱。

条形码和二维码​

<barcode type="code128" height="40">{{order.number}}</barcode>
<qrcode size="4">{{fiscal.qr_payload}}</qrcode>
  • height 是条形码的高度,以打印机点数计。
  • size 是二维码每个方块的大小:数字越大,二维码越大。
用以下代码生成的二维码 <barcode>

<barcode type="qrcode">(或 type="qr")同样会生成二维码。其大小来自 height:height ÷ 10,并限制在 2 到 10 之间。

预览将条形码和二维码绘制为图片。打印机收到的是它自己的条形码命令,或应用已生成的图片。

示例:简易 80mm 收据​

一张从上到下的完整收据:店铺名称和地址、订单号、日期和收银员、分三列显示的商品、带加粗总计行的合计、每笔付款及其实收金额和找零、一行感谢语,以及切纸。

显示完整模板(约 80 行)
<receipt paper-width="48">
<align mode="center">
<bold><size height="2"><text>{{store.name}}</text></size></bold>
{{#store.address_lines}}<text>{{.}}</text>{{/store.address_lines}}
{{#store.phone}}<text>{{store.phone}}</text>{{/store.phone}}
</align>
<line />

<text>Order: #{{order.number}}</text>
<text>Date: {{order.created.datetime}}</text>
{{#cashier.name}}<text>Cashier: {{cashier.name}}</text>{{/cashier.name}}
<line />

<!-- Column headers, bold on paper -->
<bold>
<row>
<col width="*">Item</col>
<col width="4" align="right">Qty</col>
<col width="12" align="right">Total</col>
</row>
</bold>
<line />

<!-- Line items -->
{{#lines}}
<row>
<col width="*">{{name}}</col>
<col width="4" align="right">{{qty}}</col>
<col width="12" align="right">{{line_total_display}}</col>
</row>
{{/lines}}

<line />

<!-- Totals -->
<row>
<col width="*">Subtotal</col>
<col width="16" align="right">{{totals.subtotal_display}}</col>
</row>
{{#totals.tax_total}}
<row>
<col width="*">Tax</col>
<col width="16" align="right">{{totals.tax_total_display}}</col>
</row>
{{/totals.tax_total}}
<bold>
<row>
<col width="*">TOTAL</col>
<col width="16" align="right">{{totals.total_display}}</col>
</row>
</bold>

<line />

{{#payments}}
<row>
<col width="*">{{method_title}}</col>
<col width="16" align="right">{{amount_display}}</col>
</row>
{{#tendered}}
<row>
<col width="*">Tendered</col>
<col width="16" align="right">{{tendered_display}}</col>
</row>
<row>
<col width="*">Change</col>
<col width="16" align="right">{{change_display}}</col>
</row>
{{/tendered}}
{{/payments}}

<feed lines="2" />
<align mode="center">
<text>Thank you for your purchase!</text>
</align>
<feed lines="3" />
<cut />
</receipt>

这里的标签是纯英文。模板库中的模板改用 {{i18n.*}} 标签,因此收据会跟随店铺的语言(i18n 字段)。

自适应伸展的列​

width="*" 的列会随纸张伸展。无需为某一种纸张尺寸固定每一列,而是把 * 给需要伸展的那一列:

<!-- Works on 58 mm (32 characters) AND 80 mm (48 characters) printers -->
<row>
<col width="*">{{name}}</col>
<col width="10" align="right">{{line_total_display}}</col>
</row>

在 48 字符的打印机上,商品名称占 38 个字符。在 32 字符的打印机上,则占 22 个。固定列在两者上大小相同。

多个 * 列

剩余空间平均分配。最后一个 * 列会得到多出的那一个字符。* 列的宽度不会小于 1 个字符。

模板预览​

WP 后台的模板编辑器会在您输入时显示实时热敏预览。停止输入 300 毫秒后更新。POS 的收据界面在打印前也会显示同类预览。两者都以等宽字符绘制您的模板,宽度与 paper-width 相同。

预览和打印件使用同一个模板,没有单独的打印模板。预览与纸上效果很接近,但并不完全一致,因此在依赖它之前,请在您使用的每种纸张宽度上打印一张测试收据。

预览与纸上效果的差异
在预览中在纸上
宽度为 paper-width宽度为打印机的纸张宽度
<col> 内的 <bold>、<size> 会显示该列以普通文本打印,除非开启了将收据打印为图像
<size> 只随 width 放大,因此只加高的尺寸看起来是正常的宽度和高度都生效
单线和虚线看起来不同两者都打印 - 字符
<cut /> 显示为带 ✂ 的虚线;<drawer /> 不显示任何内容纸张被切断;钱箱打开
所有文字都会显示只有打印机内置的字符才会打印,除非开启了将收据打印为图像

编写模板的技巧​

热敏打印有一些 HTML 没有的陷阱。下面逐一列出,并给出解决办法。

用 <text> 包裹带样式的标题以换行​

样式标签——<bold>、<size>、<underline>、<invert>、<align>——本身不会结束该行。<text> 会在其文字之后结束该行,<line />、<row> 和 <feed /> 等整行标签也一样。有一个例外:直接放在居中或右对齐的 <align> 内的带样式标题,在后面还有另一行时会自行结束该行(居中的带样式标题)。

<!-- ❌ Wrong: the heading runs into whatever follows -->
<bold>{{i18n.bill_to}}</bold>
{{customer.name}}

<!-- ✅ Right: put the words inside <text> -->
<bold><text>{{i18n.bill_to}}</text></bold>
<text>{{customer.name}}</text>

80 mm 的模板库模板对每个标题都是这样做的。

避免在窄行中使用 <size width="2">​

双倍宽度的文字每个字符占用两倍的空间。在 48 字符的打印机上放得下的标题,在 42 字符的打印机上可能会溢出,而在 58 mm 纸上只剩 16 个字符。

<col> 内的尺寸本来就不会打印。若要显示较大的数值(大额合计、厨房订单号),请改用 <size> 将其单独打印在一行上。

示例:加高的店铺名称和大号合计
<!-- For store names, prefer normal-width, double-height -->
<bold><size height="2"><text>{{store.name}}</text></size></bold>

<!-- For a big total, put it on its own line above the row -->
<align mode="right">
<bold><size height="2"><text>{{totals.total_display}}</text></size></bold>
</align>

使用 width="*",让各行适配任何纸张​

width="*" 的列会占用固定列之后剩余的宽度。以这种方式构建的行适合 32、42、48 和 64 字符的打印机(自适应伸展的列)。固定列和双倍宽度的文字仍会占用其全部空间,因此请在您使用的每种纸张宽度上检查效果。

如果确实要使用固定宽度,请让它们之和不超过打印机的纸张宽度:58 mm 纸为 32。80 mm 纸请用 42,而不是 48:许多 80 mm 打印机每行打印 42 个字符,总和为 48 的行会在它们上面换行。请在收据宽度中查看您的打印机对应的数字。

<align> 块内居中的带样式标题​

在 <align mode="center">(或 right)内,直接放在 <align> 中的带样式标题——<bold>、<size>、<underline> 或 <invert>——在后面还有另一行时会自行结束该行。居中放大的店铺名称位于居中的地址之上,即使没有 <text> 包裹也能正常打印。

在 <align> 块之外,请保留 <text> 包裹。

破折号和弯引号​

在 ESC/POS 打印机上,破折号和弯引号会以普通字符打印,因此可以随意输入。在 Star 打印机上,请只使用打印机内置的字母和符号。

具体会改变什么,以及在哪些打印机上

当打印机语言为 ESC/POS 时,打印前会将花式标点替换为普通的键盘字符:

  • 各种长度的连字符和破折号(短破折号、长破折号、数字破折号、减号)→ -
  • 弯引号 → 直引号

因此,即使打印机不包含这些字符,Mon–Sat 9:00–18:00 和 “open” 也能正确打印。应用向 Star 打印机(StarPRNT 和 Star Line Mode)打印时会保留原来的破折号和引号,因此请只使用打印机内置的字符。通过云打印时,Star 收据同样会被改为普通字符。

在所有打印机上,特殊空格(不换行空格、窄空格和细空格)都会以普通空格打印。

非拉丁文字和从右到左的文字​

热敏打印机使用自带的内置字符打印文字。阿拉伯语、希伯来语、波斯语、乌尔都语、泰语和其他非拉丁文字,只有在打印机内置了该文字时才能正确打印。否则会出现空白或错误的字符。

可靠的解决办法是在打印机上开启将收据打印为图像。它会把整张收据绘制成一张图片,因此无论打印机内置了哪些字符,都能按设计效果打印。模板末尾的切纸、进纸或 <drawer /> 仍然有效;位于模板中间的则会被忽略。其他解决办法请参阅非拉丁文字收据。

热敏硬件需要热敏模板

热敏打印机无法打印整页的 HTML 模板。打印任务必须转换为打印机命令(ESC/POS 或 Star),而 HTML 页面无法以这种方式写入。热敏硬件请使用热敏模板。对于整页 A4/Letter 的 HTML,请打印到系统打印机或 PDF 打印机,或通过 PrintNode 打印。

徽标和图片​

使用 <image /> 添加徽标。店铺徽标位于 {{store.logo}}:

<align mode="center">
<image src="{{store.logo}}" width="200" />
</align>

应用会在设备上将图片转换为打印机点阵:用白色填充透明部分,缩小至合适大小,并转为黑白(以点阵图案呈现,因此徽标能保留明暗层次)。然后将其作为图片发送给打印机。请使用高对比度的 PNG;暂不支持 SVG 打印。

图片宽度、可接受的来源和格式
  • 宽度:width 以打印机点数计(省略时为 200)。图片打印宽度永远不会超过纸张:58 mm 纸(32 字符或更少)为 384 点,80 mm 纸为 576 点。
  • 可接受的来源:data:image/png 和 data:image/jpeg 数据 URL、http(s) 地址,以及您自己网站上以 / 开头的路径。以 // 开头的地址,以及含有反斜杠或 .. 的路径,会被拒绝。
  • 最佳格式:透明或白色背景上的高对比度 PNG。JPEG 也可以,但其模糊处可能会打印成斑点。
  • 热敏打印机暂不支持 SVG。

技巧​

  • 从模板库中的模板开始。 模板库中的热敏模板用到了上面所有的写法。其中有 58 mm、80 mm 和从右到左的收据、厨房单,以及收银台结算、清点单和报表版本。
  • 测试您使用的每种纸张宽度,即使使用了 width="*" 的列也一样。固定列和双倍宽度的文字仍可能使行换行。
  • 金额请使用 _display 字段。 它们已按店铺的货币格式化(货币字段)。
  • 保持简单。 热敏打印机能使用的文字样式比网页少。请用 <text>、<row> 和 <col width="*"> 构建收据。

出现问题时​

编辑器预览显示“热敏模板渲染错误。请检查您的 XML 语法。” 模板无法被读取。有两种原因:

  • 标签没有闭合,或文字中有单独的 & 或 <。请闭合每个标签(写 <line />,而不是 <line>),并将 & 写成 &amp;。
  • 最外层的标签不是 <receipt>。请用 <receipt>…</receipt> 包裹整个模板。

标题与下一行连在一起。 单独一个样式标签不会结束该行,因此后面的文字会接在同一行。请在其中放入 <text>(包裹带样式的标题)。直接位于居中或右对齐的 <align> 内的带样式标题是例外(居中的带样式标题)。

一行在纸上换成了两行。 固定宽度之和超过了打印机的纸张宽度。请把某一列设为 width="*",或让固定宽度之和不超过纸张宽度:58 mm 纸为 32,许多 80 mm 打印机为 42(使用 width="*")。

总计在预览中是粗体,但在纸上是普通字体。 <col> 内的样式不会打印,而模板库中的模板正是这样给总计加粗的。请把 <bold> 放在整个 <row> 外面(列),或开启将收据打印为图像。

预览比纸张更窄或更宽。 纸张以打印机的纸张宽度为准,而不是 paper-width。把 paper-width 设为相同的数字,即可预览实际打印效果。

切纸后留下一个连接点。 <cut /> 是部分切断。需要完全切断时,请使用 <cut type="full" />。在通过 ePOS 连接的 Epson 打印机上,两者的切法相同,因此 type 在那里不起作用。

徽标不打印。 请检查 src 是可接受的来源之一,并且不是 SVG。在浏览器中,请参阅浏览器中徽标缺失。

出现问号、空白或错误的字符。 打印机没有内置该文字。请开启将收据打印为图像(非拉丁文字)。

每张收据都会打开钱箱。 要么自动打开钱箱已开启,要么模板中有 <drawer />,而它无论该设置如何都会打开钱箱。若要停止,请关闭该设置,并从模板中删除 <drawer />。

钱箱无法打开。 如果模板的 <drawer /> 带有 connector,它会覆盖打印机的设置。请去掉 connector,让打印机的钱箱连接器设置生效,然后在那里尝试另一个引脚(该设置在自动打开钱箱开启时显示)。还要检查打印机语言是否与打印机匹配,因为钱箱命令取决于它。

为旧版 StarPRNT 固定布局制作的模板打印不出有用的内容。 该布局已在 1.10 版本中移除。请用 <row>、<col> 和 width="*" 重新构建,或从模板库中的模板重新开始。