checkout.liquid

已废弃

checkout.liquid 现在已经不再支持用于信息填写、配送和付款这几个结账步骤了。checkout.liquid、附加脚本以及 <script> 标签在 Thank you 和 Order status 页面上也已被废弃，并将于 2025 年 8 月 28 日正式停用。

目前在 Thank you 和 Order status 页面上还在使用 checkout.liquid 的店铺，需要在截止日期前 升级到 Checkout Extensibility。Shopify Scripts 会继续和 Checkout Extensibility 一起工作，直到 2025 年 8 月 28 日。

你可以学习 如何构建 checkout 扩展功能，来自定义 Shopify 的结账流程。

checkout.liquid 模板会渲染整个 checkout 页面，仅对 Shopify Plus 商家开放。如果你的店铺不是 Shopify Plus，那你可以在 theme editor 里对 checkout 页面做一些自定义。

所在位置

checkout.liquid 模板位于主题的 layout 目录下：

  1. └── theme
  2.     ├── layout
  3.     |  ├── theme.liquid
  4.     |  └── checkout.liquid
  5.     ├── templates
  6.     ...

模板结构（Schema）

默认情况下，checkout.liquid 模板的结构如下：

checkout.liquid

  1. <!DOCTYPE html>
  2. <html lang="{{ locale }}" dir="{{ direction }}" class="{{ checkout_html_classes }}">
  3.   <head>
  4.     <meta charset="utf-8">
  5.     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0, height=device-height, minimum-scale=1.0, user-scalable=0">
  7.     <meta name="referrer" content="origin">
  9.     <title>{{ page_title }}</title>
  11.     {{ content_for_header }}
  13.     {{ checkout_stylesheets }}
  14.     {{ checkout_scripts }}
  15.   </head>
  16.   <body>
  17.     {{ skip_to_content_link }}
  19.     <header class="banner" data-header role="banner">
  20.       <div class="wrap">
  21.         {{ content_for_logo }}
  22.       </div>
  23.     </header>
  25.     {{ order_summary_toggle }}
  26.     <div class="content" data-content>
  27.       <div class="wrap">
  28.         <div class="main">
  29.           <header class="main__header" role="banner">
  30.             {{ content_for_logo }}
  31.             {{ breadcrumb }}
  32.             {{ alternative_payment_methods }}
  33.           </header>
  34.           <main class="main__content" role="main">
  35.             {{ content_for_layout }}
  36.           </main>
  37.           <footer class="main__footer" role="contentinfo">
  38.             {{ content_for_footer }}
  39.           </footer>
  40.         </div>
  41.         <aside class="sidebar" role="complementary">
  42.           <div class="sidebar__header">
  43.             {{ content_for_logo }}
  44.           </div>
  45.           <div class="sidebar__content">
  46.             {{ content_for_order_summary }}
  47.           </div>
  48.         </aside>
  49.       </div>
  50.     </div>
  52.     {{ tracking_code }}
  53.   </body>
  54. </html>

内容（Content）

checkout.liquid 模板会使用一些 checkout 对象 来渲染不同 checkout 步骤下的内容。

Checkout 步骤

结账流程包括以下几个步骤：

步骤 描述
Inventory issues 如果购物车里有商品缺货，或者库存少于用户下单的数量，就会显示这个步骤。用户会看到一个确认按钮，点击后会把购物车更新为当前可用的库存数量。
Contact information 用户会输入邮箱地址。如果店铺启用了客户账户，用户还可以登录。如果购物车里有需要配送的商品，就会显示收货地址表单；否则会显示账单地址表单。
Shipping method 用户可以选择配送方式或编辑配送信息。如果购物车商品不需要配送，这一步会跳过。对于卖数字商品或服务的商家来说，经常会跳过这一步。点击 Edit shipping information 会返回到 Customer information 步骤。
Payment method 用户会选择付款方式，并在需要的情况下填写支付信息。有些支付服务商会把用户跳转到第三方网站去完成支付。用户也可以在这一步选择不同的账单地址。
Review order 这个步骤是可选的，取决于 checkout 设置。用户会点击 Complete order 来确认订单金额、地址和支付信息。如果店铺在欧盟运营，这一步可能是必须的。
Processing/forwarding 这是一个临时页面，用户下单后显示，订单正在处理或者用户正在被跳转到外部支付网站。显示的消息取决于 checkout 的翻译设置。
Order status 最后一步，订单完成后显示。了解更多 ›

在每个步骤的右侧都会显示一个 Order summary，包含商品、价格、税费和运费。在移动端，这一栏会折叠收起。

小提示

你可以用 JavaScript 来 识别当前步骤。

Checkout 对象

对象 描述 是否必须
content_for_header Shopify 提供的脚本，比如 hCaptcha、Shopify app 等功能。必须放在 <head> 和 </head> 标签之间。 是
content_for_layout 每一步 checkout 流程的表单字段和内容。必须放在 <body> 和 </body> 标签之间。 是
locale 当前选择的语言环境。 否
direction 内容的 CSS 方向，比如 ltr 或 rtl。 否
page_title 页面标题，通常包裹在 <title> 标签中。 否
skip_to_content_link 一个隐藏的无障碍链接，可以跳转到页面主内容。 否
checkout_html_classes 应该加在 <html> 标签上的字符串，可以使用 Shopify 默认样式。 否
checkout_stylesheets Shopify 的 checkout 样式表。就算你有自己的样式，也建议保留它，因为要完全替代默认样式很复杂。 否
checkout_scripts Shopify 的 JavaScript 文件。 否
content_for_logo 店铺 logo，取决于 checkout 设置。 否
breadcrumb 完成结账所需的步骤列表。在 checkout 的最后 review 步骤不会显示。 否
order_summary_toggle 在移动端显示或隐藏订单摘要所需的 HTML。 否
content_for_order_summary 订单摘要内容，包括商品明细、折扣、税费和总价。 否
alternative_payment_methods 支持的快捷支付方式列表，比如 PayPal。 否
content_for_footer 店铺政策列表，如果没有则显示版权声明。 否
tracking_code 用于 Google Analytics 和 Facebook Pixel 的 JavaScript。 否
checkout checkout 对象。 否

注意

如果你没有在 checkout.liquid 模板里包含必需的对象，那你将无法通过代码编辑器或 Shopify CLI 保存或更新这个文件。

用法（Usage）

使用 checkout.liquid 时，你需要了解以下几个概念：

访问 checkout.liquid

如果你是 Shopify Plus 商家，想启用或禁用 checkout.liquid 的访问权限，需要 联系客服。

在申请使用 checkout.liquid 之前，你需要了解不同版本的 checkout 及其影响：

版本 描述
Standard 默认的 checkout，如果没有启用 checkout.liquid，就会使用这个版本。Shopify 会自动为它更新功能。
Maintenance 当启用了 checkout.liquid，就会使用这个版本。它是一个冻结版本的 Standard，不会自动更新。如果你使用 Maintenance，可以通过以下方式获取更新：
  • 禁用 checkout.liquid 访问权限，回到 Standard。
  • 等待 Maintenance 升级并手动跟进 checkout 升级流程。 |

向主题添加 checkout.liquid

如果你已经启用了 checkout.liquid 访问权限，就可以按照以下步骤，通过 Shopify 管理后台的代码编辑器，将这个模板添加到你的主题中：

  1. 在你的 Shopify 后台，进入 Online Store > Themes。

  2. 找到你要编辑的主题，然后点击 … > Edit code。

  3. 在 Layout 目录中，点击 Add a new layout。

  4. 在下拉列表中选择 checkout，然后点击 Create layout。

现在你应该能在 Layout 目录下看到 checkout.liquid。

自定义 checkout 内容

你不能在 checkout objects 渲染之前修改它们生成的内容（无论是必需还是可选的）。唯一的例外是翻译设置、主题编辑器设置，还有一些 Shopify 后台提供的选项。

如果你需要自定义 checkout object 输出的内容，就得用 JavaScript 在渲染之后进行修改。想了解更多，请参考 Best practices for editing checkout.liquid。

步骤识别（Step identification）

checkout 所有流程都在一个页面里进行，也就是说 URL 不会变，不管用户走到哪个步骤。为了判断用户现在在哪个步骤，你可以用以下 JavaScript 对象：

小提示

这些 JavaScript 对象可以通过浏览器的开发者工具查看。

Shopify.Checkout.step

这个对象用来表示用户当前在 checkout 的哪个步骤。返回值可能是：

  • contact_information
  • shipping_method
  • payment_method
  • processing - 这是 payment_method 和 thank_you 页面之间的步骤。
  • review - 这是在 Shopify Admin 中设置的一个可选步骤。

注意

这个对象只有在用户第一次访问 Order Status 页面时才会被定义。

Shopify.Checkout.page

这个对象用来表示用户当前在什么类型的页面上。返回值可能是：

  • show - checkout 流程中各步骤的页面模板。
  • stock_problems - 如果购物车里的商品库存有问题，就会显示这个页面。
  • processing - 支付处理中时显示的页面。
  • forward - 来自 PayPal 或其他第三方支付网关的跳转页面。
  • thank_you

注意

这个对象也只有在用户第一次访问 Order Status 页面时才会被定义。

Shopify.Checkout.OrderStatus

这个对象可以用来 往 Order status 页面添加内容，也能帮你判断用户当前是在 Thank You 页面还是 Order Status 页面。

Order Status 页面一般也算是 checkout 页面。不过用户第一次访问时，它被认为是 Thank You 页面，这时候 Shopify.Checkout.step 和 Shopify.Checkout.page 都是有定义的。

如果用户是再次访问或刷新 页面，那么这个 checkout 会变成 order，页面就会被当作 Order Status 页面加载，此时 Shopify.Checkout.step 和 Shopify.Checkout.page 就会是 undefined，而 Shopify.Checkout.OrderStatus 会被定义。

页面事件（Page events）

checkout 的所有步骤都在同一个 URL 路径下，页面内容是根据当前步骤动态加载的。这个过程中会触发两个主要事件：

page:load

当每个步骤的内容被加载时会触发 page:load 事件。通常你在加载页面时添加内容时就用这个事件。

page:change

当用户还在同一个 checkout 步骤里，但部分内容有变动时，就会触发 page:change。比如用户提交折扣码表单时就会触发这个事件。

如果你只是用 page:load 来往 DOM 里添加内容，那可能会在 page:change 时被覆盖。为了避免这种问题，建议你监听两个事件一起处理：

  1. $(document).on("page:load page:change", function() {
  2.   // 添加内容
  3. });

Checkout jQuery

checkout 自带一个版本的 jQuery，可以通过 Checkout.$ 来访问：

  1. (function($) {
  2.   $(document).on("page:load page:change", function() {
  3.     // 自定义功能
  4.   });
  5. })(Checkout.$);

注意

checkout 自带的 jQuery 可能不是最新版的。如果你需要新版 jQuery 的功能，记得要自己额外引入。

捕获 checkout attributes

你可以像捕获购物车属性那样捕获 checkout 属性，方式类似：capturing cart attributes。

要捕获 checkout attribute，你需要在主 checkout 表单中加一个 input，带上 name="checkout[attributes][attribute-name]" 属性，其中 attribute-name 就是你自定义的属性名：

  1. <input type="text" name="checkout[attributes][custom attribute]">

小提示

如果你是在 Payment method 步骤里收集这些属性的，那最好先用一个占位值填充它们再继续提交订单。如果这个字段是空的，可能会报错，说 checkout 有变动。

另外注意，捕获 checkout 属性会覆盖掉之前的购物车属性。想避免这个问题，请参考下面的「保留购物车属性」部分。

保留购物车属性（Preserve cart attributes）

在你捕获 checkout 属性时，可以用 checkout.attributes 这个 Liquid 对象来保留购物车属性。这个对象里包含了原本的购物车属性值。你可以遍历这些属性，生成带对应 name 和 value 的 input，然后加入到 checkout 表单里。

这个代码片段应该写在一个 JavaScript 函数中，用来把这些 input 插入到主表单里。

  1. {% for attribute in checkout.attributes %}
  2.   <input type=hidden name="checkout[attributes][{{ attribute.first }}]" value="{{ attribute.last  }}">
  3. {% endfor %}