列印收據的自訂 Liquid 區塊

您可以使用自訂 Liquid 區塊，將專屬內容新增至列印收據的頁首或頁尾，例如訂單詳情、顧客資訊、商品屬性、中繼欄位及條碼。

系統會在已完成的線上與銷售點 (POS) 訂單列印收據中，轉譯自訂 Liquid 區塊。自訂 Liquid 區塊不會在採用離線結帳的訂單中轉譯。

您可以從 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	要在 QR 碼中編碼的內容。與 `qrcode` 篩選條件搭配使用。
line_items	已購買的商品。每個商品項目的屬性都列在訂單商品項目物件中。
transactions	付款。每筆付款的屬性都列在交易物件中。
discounts	訂單層級的折扣。每筆折扣的屬性都列在折扣物件中。
tax_lines	稅項明細。每個稅項明細的屬性都列在稅項明細物件中。
refunds	訂單退款。
shipping_address	運送地址。地址屬性列在地址物件之中。
customer	顧客的詳情，列在顧客物件之中。
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	要編碼為 QR 碼的內容。

中繼欄位和屬性

中繼欄位和商品項目屬性有兩種形式。

商品項目中繼欄位和屬性具有金鑰。您可以透過金鑰直接存取值：

{{ 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 }}	呈現 QR 碼。

自訂 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 %}

若要新增連結至該訂單的 QR 碼，請使用以下 Liquid：

{{ order.qr_code_content | qrcode }}