打印收据的自定义 Liquid 区块

您可以使用自定义 Liquid 区块将您自己的内容（例如订单详细信息、客户信息、产品属性、元字段和条码）添加到打印收据的标头或页脚。

自定义 Liquid 区块会在已完成的在线订单和 POS 订单的打印收据上呈现。它们不会在采用离线结账的订单上呈现。

您可以从 Shopify 后台的收据可视化编辑器中添加自定义 Liquid 区块。打印收据时，将从收据的数据中提取您引用的值。例如，当订单备注存在时，以下 Liquid 代码会将订单备注添加到收据中：

{% if order.note %}
  <p>Order note: {{ order.note }}</p>
{% endif %}

本页内容

Liquid 语法规则

在构建自定义 Liquid 区块之前，请先查看以下语法规则：

变量名使用小写字母和下划线，这种格式称为 snake_case（蛇形命名法）。例如，请使用 order.total_price、order.customer.display_name 和 order.line_items。
货币值是纯数字。请使用 money 筛选器设置其格式，例如 {{ order.total_price | money }}。
使用 if 语句保护可选值，以免打印出空行，例如 {% if order.customer.email %}{{ order.customer.email }}{% endif %}。
使用 for 语句对列表进行循环运算，例如 {% for item in order.line_items %} ... {% endfor %}。
不支持部分 Liquid 标签。您无法使用 assign、capture、include、render、raw、increment 或 decrement。如果您的区块使用了不受支持的标签，系统将不会保存您的收据，并且您会看到一条错误消息。
一个自定义 Liquid 区块最多可包含 50 KB 代码。

HTML 和 CSS

您可以在自定义 Liquid 区块中使用基本 HTML 来构建内容，例如 <p>、<br>、<strong>、<em>、标题、列表和链接。您的内容会采用收据的现有字体和大小。

您无法使用 CSS 来更改收据的外观。不支持 <style> 区块和 style 属性，因此自定义 Liquid 区块无法重置收据上其他内容的样式或将其隐藏。同样不支持 <script> 标签、onclick 等事件处理程序以及 javascript: 链接。

如果您的区块包含不受支持的 HTML，系统将不会保存您的收据，并且您会看到一条错误消息。请移除不受支持的 HTML，然后再重新保存。

变量和对象

自定义 Liquid 区块可引用以下对象和变量。有些值不在默认收据上，因此添加它们的其中一种方法是使用自定义 Liquid 区块。

顶级变量

在自定义 Liquid 区块中可使用以下顶级变量。

自定义 Liquid 区块可使用的顶级变量描述
变量	描述
order	正在打印的订单。
shop	商店。
location	零售地点。
settings	收据的显示设置，即在编辑器中配置的切换键。
purchased_gift_cards	在此订单上购买的礼品卡。
staff_member_description	分配的员工（当开启显示员工时）。
locale	收据的区域设置，例如 en。
is_pickup	判断订单是否为取货订单。
pickup_location	取货地点（如果适用）。

订单对象

订单对象描述
属性	描述
name	订单名称，例如 #1001。
created_at	订单时间戳。应与 `date` 筛选器配合使用。
note	订单备注。
subtotal_price	小计。应使用 `money` 筛选器设置格式。
total_price	总计。应使用 `money` 筛选器设置格式。
shipping_price	收取的运费。应使用 `money` 筛选器设置格式。
total_tip_received	小费总计。应使用 `money` 筛选器设置格式。
balance_due	尚欠金额。应使用 `money` 筛选器设置格式。
change_due	找零。应使用 `money` 筛选器设置格式。
taxes_included	价格中是否包含税费。
receipt_number	收据编号。
barcode_content	要在条码中编码的内容。
qr_code_content	要在二维码中编码的内容。应与 `qrcode` 筛选器配合使用。
line_items	购买的商品。每个商品的属性都列在订单项目对象中。
transactions	付款。每笔付款的属性都列在交易对象中。
discounts	订单级别的折扣。每个折扣的属性都列在折扣对象中。
tax_lines	税费行。每个税费行的属性都列在税费行对象中。
refunds	订单的退款。
shipping_address	收货地址。地址属性列在 address object 中。
customer	客户的详细信息，列在 customer object 中。
metafields	订单元字段。

客户对象

该 order.customer 对象包含客户的详细信息。

客户对象描述
属性	描述
display_name	客户的显示名称。
first_name	客户的名字。
last_name	客户的姓氏。
email	客户的电子邮件地址。
phone	客户的电话号码。
default_address	客户的默认地址。
metafields	客户元字段。

订单项目对象

在 order.line_items 中的每个项目包含以下属性。

订单项目对象描述
属性	描述
name	产品或订单项目名称。
variant_title	多属性，例如大号/蓝色。
sku	SKU。
vendor	厂商。
quantity	数量。
price	单价。使用 `money` 筛选器进行格式化。
total_price	订单项目总计。使用 `money` 筛选器进行格式化。
discounted_total_price	折后订单项目总计。使用 `money` 筛选器进行格式化。
discounted_unit_price	折后单价。使用 `money` 筛选器进行格式化。
discounts	应用于此订单项目的折扣。
selling_plan_name	订阅或销售方案名称（如果有）。
staff_member_description	归属于此订单项目的员工。
custom_attributes	订单项目属性，可通过键访问。
product_metafields	产品元字段，可通过键访问。
variant_metafields	多属性元字段，可通过键访问。

交易对象

在 order.transactions 中的每笔付款包含以下属性。在订单中使用的商店抵扣额将列为名为 Store credit 的付款。客户剩余的商店抵扣额余额不可作为变量使用。

交易对象描述
属性	描述
name	付款名称，例如 Visa、现金或商店抵扣额。
payment_type	付款类型代码。
amount	金额。使用 `money` 筛选器进行格式化。
kind	交易类型。
status	交易状态。
credit_card_number	经过遮盖处理的卡号（如果适用）。
created_at	交易时间戳。
additional_details	额外的付款详细信息行。

商店对象

该 shop 对象包含商店的详细信息。

商店对象描述
属性	描述
name	商店名称。
domain	商店域名。
currency	商店货币。
id	商店 ID。

地点对象

该 location 对象包含零售地点的详细信息。

地点对象描述
属性	描述
name	地点名称。
address1	第一行地址。
address2	第二行地址。
city	城市。
province	省或州。
province_code	省或州代码。
zip	邮政编码。
country	国家/地区。
phone	电话号码。
metafields	地点元字段。

地址对象

地址（例如 order.shipping_address 或 order.customer.default_address）包含以下属性。

地址对象描述
属性	描述
company	公司名称。
name	收件人姓名。
address1	第一行地址。
address2	第二行地址。
city	城市。
province	省或州。
province_code	省或州代码。
zip	邮政编码。
country	国家/地区。
country_code	国家/地区代码。
phone	电话号码。

折扣对象

在 order.discounts 或 item.discounts 中的每个项目包含以下属性。

折扣对象描述
属性	描述
description	折扣描述。
amount	折扣金额。使用 `money` 筛选器进行格式化。
percentage	折扣百分比。

税费行对象

在 order.tax_lines 中的每个项目包含以下属性。

税费行对象描述
属性	描述
title	税费名称。
rate	以小数表示的税率。
rate_percentage	以百分比表示的税率。
price	税额。使用 `money` 筛选器进行格式化。
taxable_amount	需纳税金额。使用 `money` 筛选器进行格式化。

礼品卡对象

在 purchased_gift_cards 中的每个项目包含以下属性。

礼品卡对象描述
属性	描述
code	礼品卡代码。
masked_code	掩码礼品卡代码。
balance	礼品卡余额。使用 `money` 筛选器设置格式。
created_at	礼品卡时间戳。
qr_code_content	要在二维码中编码的内容。

元字段和属性

元字段和订单项目属性有两种形式。

订单项目元字段和属性使用键。通过键直接访问值：

{{ item.product_metafields.care_instructions }}
{{ item.custom_attributes.engraving }}

订单和客户元字段为列表。请循环遍历它们：

{% for m in order.metafields %}
  {{ m.namespace }}.{{ m.key }}: {{ m.value }}
{% endfor %}

键已标准化为 snake_case 格式。对于诸如 Care Instructions 或 careInstructions 的键，需以 care_instructions 的形式访问。引用采用键的值时，请始终使用小写字母和下划线。

订单和客户元字段是否可用取决于记录中是否存在这些元字段。

Liquid 筛选器

您可以使用筛选器来设置自定义 Liquid 区块中信息的格式。若要应用筛选器，请添加竖线字符 |，然后在 Liquid 输出中添加该筛选器，例如 {{ order.total_price | money }}。

标准的 Liquid 筛选器也可发挥作用。参阅筛选器参考文档，详细了解 Liquid 筛选器。

可用于自定义 Liquid 区块的筛选器说明
筛选器	示例	描述
money	{{ order.total_price \| money }}	使用收据货币设置金额格式。
date	{{ order.created_at \| date: '%B %e, %Y' }}	设置日期或时间的格式。
percent	{{ tax_line.rate \| percent }}	将小数格式化为百分比，例如将 0.2 设置为 20%。
t	{{ 'receipt.total' \| t }}	返回已翻译的标签。
barcode	{{ order.barcode_content \| barcode }}	渲染条码。
qrcode	{{ order.qr_code_content \| qrcode }}	渲染二维码。

自定义 Liquid 区块示例

以下示例添加了默认打印的收据模板上没有的内容。

要添加订单备注（如果存在），请使用以下 Liquid 代码：

{% if order.note %}<p>Note: {{ order.note }}</p>{% endif %}

要在每个商品旁边添加 SKU，请使用以下 Liquid 代码：

{% for item in order.line_items %}
  <p>{{ item.name }} — {{ item.sku }} ×{{ item.quantity }}</p>
{% endfor %}

要添加订单项目属性（例如雕刻要求），请使用以下 Liquid 代码：

{% for item in order.line_items %}
  {% if item.custom_attributes.engraving %}
    <p>{{ item.name }} — Engraving: {{ item.custom_attributes.engraving }}</p>
  {% endif %}
{% endfor %}

要添加产品元字段（例如护理说明），请使用以下 Liquid 代码：

{% for item in order.line_items %}
  {% if item.product_metafields.care_instructions %}
    <p>{{ item.name }}: {{ item.product_metafields.care_instructions }}</p>
  {% endif %}
{% endfor %}

要添加客户元字段，请使用以下 Liquid 代码：

{% for m in order.customer.metafields %}
  {% if m.key == 'loyalty_tier' %}<p>Loyalty tier: {{ m.value }}</p>{% endif %}
{% endfor %}

要添加链接到订单的二维码，请使用以下 Liquid 代码：

{{ order.qr_code_content | qrcode }}