shopify-liquid

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Liquid Templating

Shopify Liquid 模板语言

Expert guidance for Shopify's Liquid templating language including complete syntax reference, filters, objects, and best practices.

针对Shopify Liquid模板语言的专业指南，包含完整的语法参考、过滤器、对象及最佳实践。

When to Use This Skill

适用场景

Invoke this skill when:

Working with
```
.liquid
```
,
```
.css.liquid
```
, or
```
.js.liquid
```
files
Creating or modifying theme templates (product, collection, cart, etc.)
Implementing dynamic content rendering
Using Liquid filters to format data (money, dates, strings)
Accessing Shopify objects (product, collection, cart, customer)
Writing conditional logic or loops in templates
Debugging Liquid syntax errors or output issues
Creating sections or snippets with Liquid logic
Formatting prices, dates, or other data

在以下场景中调用此技能：

处理
```
.liquid
```
、
```
.css.liquid
```
或
```
.js.liquid
```
文件
创建或修改主题模板（产品、集合、购物车等）
实现动态内容渲染
使用Liquid过滤器格式化数据（货币、日期、字符串）
访问Shopify对象（产品、集合、购物车、客户）
在模板中编写条件逻辑或循环
调试Liquid语法错误或输出问题
使用Liquid逻辑创建区块或代码片段
格式化价格、日期或其他数据

Core Capabilities

核心能力

1. Liquid Syntax Fundamentals

1. Liquid语法基础

Three core syntax types:

Output (display values):

liquid

{{ product.title }}
{{ product.price | money }}
{{ collection.products.size }}

Logic (conditionals and control):

liquid

{% if product.available %}
  <button>Add to Cart</button>
{% else %}
  <p>Sold Out</p>
{% endif %}

Assignment (variables):

liquid

{% assign sale_price = product.price | times: 0.8 %}
{% capture full_title %}{{ collection.title }} - {{ product.title }}{% endcapture %}

Whitespace control:

liquid

{%- if condition -%}
  Content (strips whitespace)
{%- endif -%}

三种核心语法类型：

输出（显示值）：

liquid

{{ product.title }}
{{ product.price | money }}
{{ collection.products.size }}

逻辑（条件与控制）：

liquid

{% if product.available %}
  <button>Add to Cart</button>
{% else %}
  <p>Sold Out</p>
{% endif %}

赋值（变量）：

liquid

{% assign sale_price = product.price | times: 0.8 %}
{% capture full_title %}{{ collection.title }} - {{ product.title }}{% endcapture %}

空白字符控制：

liquid

{%- if condition -%}
  Content (strips whitespace)
{%- endif -%}

2. Control Flow Tags

2. 控制流标签

Conditionals:

```
if/elsif/else/endif
```
- Standard conditionals
```
unless/endunless
```
- Negated if
```
case/when/else/endcase
```
- Switch statements

Logical operators:

```
and
```
,
```
or
```
- Combine conditions
```
==
```
,
```
!=
```
,
```
>
```
,
```
<
```
,
```
>=
```
,
```
<=
```
- Comparisons
```
contains
```
- Substring/array search

Example:

liquid

{% if product.available and product.price < 100 %}
  Affordable and in stock
{% elsif product.available %}
  Available but pricey
{% else %}
  Out of stock
{% endif %}

条件语句：

```
if/elsif/else/endif
```
- 标准条件判断
```
unless/endunless
```
- 反向条件判断
```
case/when/else/endcase
```
- 分支语句

逻辑运算符：

```
and
```
,
```
or
```
- 组合条件
```
==
```
,
```
!=
```
,
```
>
```
,
```
<
```
,
```
>=
```
,
```
<=
```
- 比较运算符
```
contains
```
- 子字符串/数组搜索

示例：

liquid

{% if product.available and product.price < 100 %}
  Affordable and in stock
{% elsif product.available %}
  Available but pricey
{% else %}
  Out of stock
{% endif %}

3. Iteration (Loops)

3. 迭代（循环）

for loop:

liquid

{% for product in collection.products %}
  {{ product.title }}
{% endfor %}

{# With modifiers #}
{% for product in collection.products limit: 5 offset: 10 reversed %}
  {{ product.title }}
{% endfor %}

forloop object:

liquid

{% for item in array %}
  {{ forloop.index }}      {# 1-based index #}
  {{ forloop.index0 }}     {# 0-based index #}
  {{ forloop.first }}      {# Boolean: first item #}
  {{ forloop.last }}       {# Boolean: last item #}
  {{ forloop.length }}     {# Total items #}
{% endfor %}

Pagination:

liquid

{% paginate collection.products by 12 %}
  {% for product in paginate.collection.products %}
    {% render 'product-card', product: product %}
  {% endfor %}

  {% if paginate.pages > 1 %}
    {{ paginate | default_pagination }}
  {% endif %}
{% endpaginate %}

for循环：

liquid

{% for product in collection.products %}
  {{ product.title }}
{% endfor %}

{# With modifiers #}
{% for product in collection.products limit: 5 offset: 10 reversed %}
  {{ product.title }}
{% endfor %}

forloop对象：

liquid

{% for item in array %}
  {{ forloop.index }}      {# 1-based index #}
  {{ forloop.index0 }}     {# 0-based index #}
  {{ forloop.first }}      {# Boolean: first item #}
  {{ forloop.last }}       {# Boolean: last item #}
  {{ forloop.length }}     {# Total items #}
{% endfor %}

分页：

liquid

{% paginate collection.products by 12 %}
  {% for product in paginate.collection.products %}
    {% render 'product-card', product: product %}
  {% endfor %}

  {% if paginate.pages > 1 %}
    {{ paginate | default_pagination }}
  {% endif %}
{% endpaginate %}

4. Essential Filters

4. 必备过滤器

Money formatting:

liquid

{{ 1000 | money }}                          {# $10.00 #}
{{ 1000 | money_without_currency }}         {# 10.00 #}
{{ 1000 | money_without_trailing_zeros }}   {# $10 #}

String manipulation:

liquid

{{ "hello" | upcase }}                {# HELLO #}
{{ "hello" | capitalize }}            {# Hello #}
{{ "hello world" | truncate: 8 }}     {# hello... #}
{{ "a,b,c" | split: "," }}            {# ["a","b","c"] #}
{{ text | strip_html }}               {# Remove HTML tags #}

Array/collection:

liquid

{{ array | first }}                              {# First element #}
{{ array | last }}                               {# Last element #}
{{ array | size }}                               {# Count #}
{{ products | map: "title" }}                    {# Extract property #}
{{ products | where: "vendor", "Nike" }}         {# Filter #}
{{ products | sort: "price" }}                   {# Sort #}
{{ array | join: ", " }}                         {# Join with separator #}

Date formatting:

liquid

{{ order.created_at | date: '%B %d, %Y' }}      {# November 10, 2025 #}
{{ order.created_at | date: '%m/%d/%Y' }}       {# 11/10/2025 #}
{{ order.created_at | date: '%H:%M %p' }}       {# 12:39 PM #}

Image handling:

liquid

{{ product.image | img_url: '500x500' }}        {# Resize image #}
{{ product.image | img_url: 'medium' }}         {# Named size #}
{{ 'logo.png' | asset_url }}                    {# Theme asset CDN #}

Math operations:

liquid

{{ 5 | plus: 3 }}           {# 8 #}
{{ 5 | minus: 3 }}          {# 2 #}
{{ 5 | times: 3 }}          {# 15 #}
{{ 10 | divided_by: 2 }}    {# 5 #}
{{ 1.567 | round: 2 }}      {# 1.57 #}

Chaining filters:

liquid

{{ collection.products | where: "available" | map: "title" | sort | first }}

货币格式化：

liquid

{{ 1000 | money }}                          {# $10.00 #}
{{ 1000 | money_without_currency }}         {# 10.00 #}
{{ 1000 | money_without_trailing_zeros }}   {# $10 #}

字符串处理：

liquid

{{ "hello" | upcase }}                {# HELLO #}
{{ "hello" | capitalize }}            {# Hello #}
{{ "hello world" | truncate: 8 }}     {# hello... #}
{{ "a,b,c" | split: "," }}            {# ["a","b","c"] #}
{{ text | strip_html }}               {# Remove HTML tags #}

数组/集合：

liquid

{{ array | first }}                              {# First element #}
{{ array | last }}                               {# Last element #}
{{ array | size }}                               {# Count #}
{{ products | map: "title" }}                    {# Extract property #}
{{ products | where: "vendor", "Nike" }}         {# Filter #}
{{ products | sort: "price" }}                   {# Sort #}
{{ array | join: ", " }}                         {# Join with separator #}

日期格式化：

liquid

{{ order.created_at | date: '%B %d, %Y' }}      {# November 10, 2025 #}
{{ order.created_at | date: '%m/%d/%Y' }}       {# 11/10/2025 #}
{{ order.created_at | date: '%H:%M %p' }}       {# 12:39 PM #}

图片处理：

liquid

{{ product.image | img_url: '500x500' }}        {# Resize image #}
{{ product.image | img_url: 'medium' }}         {# Named size #}
{{ 'logo.png' | asset_url }}                    {# Theme asset CDN #}

数学运算：

liquid

{{ 5 | plus: 3 }}           {# 8 #}
{{ 5 | minus: 3 }}          {# 2 #}
{{ 5 | times: 3 }}          {# 15 #}
{{ 10 | divided_by: 2 }}    {# 5 #}
{{ 1.567 | round: 2 }}      {# 1.57 #}

链式调用过滤器：

liquid

{{ collection.products | where: "available" | map: "title" | sort | first }}

5. Key Shopify Objects

5. 关键Shopify对象

Product object:

liquid

{{ product.title }}
{{ product.price | money }}
{{ product.available }}              {# Boolean #}
{{ product.vendor }}
{{ product.type }}
{{ product.images }}                 {# Array #}
{{ product.variants }}               {# Array #}
{{ product.selected_variant }}
{{ product.metafields.custom.field }}

Collection object:

liquid

{{ collection.title }}
{{ collection.products }}            {# Array #}
{{ collection.products_count }}
{{ collection.all_tags }}
{{ collection.sort_by }}
{{ collection.filters }}

Cart object (global):

liquid

{{ cart.item_count }}
{{ cart.total_price | money }}
{{ cart.items }}                     {# Array of line items #}
{{ cart.empty? }}                    {# Boolean #}

Customer object:

liquid

{{ customer.name }}
{{ customer.email }}
{{ customer.orders_count }}
{{ customer.total_spent | money }}
{{ customer.default_address }}

Global objects:

liquid

{{ shop.name }}
{{ shop.currency }}
{{ shop.url }}
{{ request.path }}
{{ request.page_type }}             {# "product", "collection", etc. #}
{{ settings.color_primary }}        {# Theme settings #}

Product对象：

liquid

{{ product.title }}
{{ product.price | money }}
{{ product.available }}              {# Boolean #}
{{ product.vendor }}
{{ product.type }}
{{ product.images }}                 {# Array #}
{{ product.variants }}               {# Array #}
{{ product.selected_variant }}
{{ product.metafields.custom.field }}

Collection对象：

liquid

{{ collection.title }}
{{ collection.products }}            {# Array #}
{{ collection.products_count }}
{{ collection.all_tags }}
{{ collection.sort_by }}
{{ collection.filters }}

Cart对象（全局）：

liquid

{{ cart.item_count }}
{{ cart.total_price | money }}
{{ cart.items }}                     {# Array of line items #}
{{ cart.empty? }}                    {# Boolean #}

Customer对象：

liquid

{{ customer.name }}
{{ customer.email }}
{{ customer.orders_count }}
{{ customer.total_spent | money }}
{{ customer.default_address }}

全局对象：

liquid

{{ shop.name }}
{{ shop.currency }}
{{ shop.url }}
{{ request.path }}
{{ request.page_type }}             {# "product", "collection", etc. #}
{{ settings.color_primary }}        {# Theme settings #}

6. Template Inclusion

6. 模板引入

render (isolated scope - PREFERRED):

liquid

{% render 'product-card', product: product, show_price: true %}

{# Render for each item #}
{% render 'product-card' for collection.products as item %}

include (shared scope - LEGACY):

liquid

{% include 'product-details' %}

section (dynamic sections):

liquid

{% section 'featured-product' %}

render（隔离作用域 - 推荐）：

liquid

{% render 'product-card', product: product, show_price: true %}

{# Render for each item #}
{% render 'product-card' for collection.products as item %}

include（共享作用域 - 旧版）：

liquid

{% include 'product-details' %}

section（动态区块）：

liquid

{% section 'featured-product' %}

Common Patterns

常见模式

Product availability check

产品库存状态检查

liquid

{% if product.available %}
  <button type="submit">Add to Cart</button>
{% elsif product.selected_variant.incoming %}
  <p>Coming {{ product.selected_variant.incoming_date | date: '%B %d' }}</p>
{% else %}
  <p class="sold-out">Sold Out</p>
{% endif %}

liquid

{% if product.available %}
  <button type="submit">Add to Cart</button>
{% elsif product.selected_variant.incoming %}
  <p>Coming {{ product.selected_variant.incoming_date | date: '%B %d' }}</p>
{% else %}
  <p class="sold-out">Sold Out</p>
{% endif %}

Price display with sale

促销价格显示

liquid

{% if product.compare_at_price > product.price %}
  <span class="sale-price">{{ product.price | money }}</span>
  <span class="original-price">{{ product.compare_at_price | money }}</span>
  <span class="savings">Save {{ product.compare_at_price | minus: product.price | money }}</span>
{% else %}
  <span class="price">{{ product.price | money }}</span>
{% endif %}

liquid

{% if product.compare_at_price > product.price %}
  <span class="sale-price">{{ product.price | money }}</span>
  <span class="original-price">{{ product.compare_at_price | money }}</span>
  <span class="savings">Save {{ product.compare_at_price | minus: product.price | money }}</span>
{% else %}
  <span class="price">{{ product.price | money }}</span>
{% endif %}

Loop through variants

遍历产品变体

liquid

{% for variant in product.variants %}
  <option
    value="{{ variant.id }}"
    {% unless variant.available %}disabled{% endunless %}
  >
    {{ variant.title }} - {{ variant.price | money }}
  </option>
{% endfor %}

liquid

{% for variant in product.variants %}
  <option
    value="{{ variant.id }}"
    {% unless variant.available %}disabled{% endunless %}
  >
    {{ variant.title }} - {{ variant.price | money }}
  </option>
{% endfor %}

Check collection tags

检查集合标签

liquid

{% if collection.all_tags contains 'sale' %}
  <div class="sale-banner">Sale items available!</div>
{% endif %}

liquid

{% if collection.all_tags contains 'sale' %}
  <div class="sale-banner">Sale items available!</div>
{% endif %}

Best Practices

最佳实践

Use whitespace control (
```
{%-
```
and
```
-%}
```
) to keep HTML clean
Prefer
render
over
include
for better performance and isolation
Cache expensive operations by assigning to variables
Use descriptive variable names for clarity
Leverage filters instead of complex logic when possible
Check for existence before accessing nested properties

Use
default
filter for fallback values:

{{ product.metafield | default: "N/A" }}

使用空白字符控制（
```
{%-
```
和
```
-%}
```
）保持HTML代码整洁
优先使用
render
而非
include
，提升性能并实现作用域隔离
将耗时操作缓存到变量中
使用描述性变量名，提升代码可读性
尽可能使用过滤器替代复杂逻辑
访问嵌套属性前先检查是否存在

使用
default
过滤器设置回退值：

{{ product.metafield | default: "N/A" }}

Detailed References

详细参考文档

For comprehensive documentation:

references/syntax.md - Complete syntax reference with all tags
references/filters.md - All 60+ filters with examples
references/objects.md - Complete object property reference

如需完整文档：

references/syntax.md - 包含所有标签的完整语法参考
references/filters.md - 60+个过滤器及示例
references/objects.md - 完整的对象属性参考

Integration with Other Skills

与其他技能的集成

shopify-theme-dev - Use when working with theme file structure and sections
shopify-api - Use when fetching data via Ajax or GraphQL to display in Liquid
shopify-debugging - Use when troubleshooting Liquid rendering issues
shopify-performance - Use when optimizing Liquid template performance

shopify-theme-dev - 处理主题文件结构和区块时使用
shopify-api - 通过Ajax或GraphQL获取数据并在Liquid中展示时使用
shopify-debugging - 排查Liquid渲染问题时使用
shopify-performance - 优化Liquid模板性能时使用

Quick Syntax Reference

快速语法参考

liquid

{# Output #}
{{ variable }}
{{ product.title | upcase }}

{# Conditionals #}
{% if condition %}...{% elsif %}...{% else %}...{% endif %}
{% unless condition %}...{% endunless %}
{% case variable %}{% when value %}...{% endcase %}

{# Loops #}
{% for item in array %}...{% endfor %}
{% for item in array limit: 5 offset: 10 %}...{% endfor %}
{% break %} / {% continue %}

{# Variables #}
{% assign var = value %}
{% capture var %}content{% endcapture %}

{# Inclusion #}
{% render 'snippet', param: value %}
{% section 'section-name' %}

{# Comments #}
{% comment %}...{% endcomment %}
{# Single line #}

liquid

{# Output #}
{{ variable }}
{{ product.title | upcase }}

{# Conditionals #}
{% if condition %}...{% elsif %}...{% else %}...{% endif %}
{% unless condition %}...{% endunless %}
{% case variable %}{% when value %}...{% endcase %}

{# Loops #}
{% for item in array %}...{% endfor %}
{% for item in array limit: 5 offset: 10 %}...{% endfor %}
{% break %} / {% continue %}

{# Variables #}
{% assign var = value %}
{% capture var %}content{% endcapture %}

{# Inclusion #}
{% render 'snippet', param: value %}
{% section 'section-name' %}

{# Comments #}
{% comment %}...{% endcomment %}
{# Single line #}