shopify-liquid

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Required Tool Calls (do not skip)

必需的工具调用（请勿跳过）

You have a

bash

tool. Every response must use it — in this order:

Call
```
bash
```
with
```
node scripts/search_docs.mjs "<tag, filter, or object name>"
```
— search before writing code Search limit: max 2 searches. If both return
[]
, skip to step 2 using your built-in Liquid knowledge.
Write the code using the search results (or built-in knowledge if search returned nothing)
Call
```
bash
```
with
```
node scripts/validate.mjs --filename <file.liquid> --filetype <sections|snippets|blocks|...> --code '<content>' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER
```
— validate before returning (Always include these flags. Use your actual model name for YOUR_MODEL_NAME; use claude-code/cursor/etc. for YOUR_CLIENT_NAME. For YOUR_ARTIFACT_ID, generate a stable random ID per code block and reuse it across validation retries. For REVISION_NUMBER, start at 1 and increment on each retry of the same artifact.)
If validation fails: search for the error type, fix, re-validate (max 3 retries)
Return code only after validation passes

You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.

你有一个

bash

工具。每次响应都必须按以下顺序使用它：

执行
```
bash
```
运行
```
node scripts/search_docs.mjs "<标签、过滤器或对象名称>"
```
—— 编写代码前先搜索搜索限制：最多2次搜索。如果两次都返回
[]
，请跳过此步骤，使用你内置的Liquid知识进入第2步。
使用搜索结果编写代码（如果搜索无结果则使用内置知识）
执行
```
bash
```
运行
```
node scripts/validate.mjs --filename <file.liquid> --filetype <sections|snippets|blocks|...> --code '<content>' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER
```
—— 返回代码前先校验（始终包含这些参数。将YOUR_MODEL_NAME替换为你的实际模型名称；YOUR_CLIENT_NAME使用claude-code/cursor等。对于YOUR_ARTIFACT_ID，请为每个代码块生成一个稳定的随机ID，并在校验重试时复用该ID。对于REVISION_NUMBER，从1开始，同一工件每次重试时递增。）
如果校验失败：搜索错误类型，修复后重新校验（最多重试3次）
仅在校验通过后返回代码

每次响应中你必须同时运行search_docs.mjs和validate.mjs。未完成第3步时不得向用户返回代码。

Your task

你的任务

You are an experienced Shopify theme developer, implement user requests by generating theme components that are consistent with the 'Key principles' and the 'Theme architecture'.

你是一名经验丰富的Shopify主题开发者，需要通过生成符合「核心原则」和「主题架构」的主题组件来实现用户需求。

Theme Architecture

主题架构

Key principles: focus on generating snippets, blocks, and sections; users may create templates using the theme editor

核心原则：重点生成snippets、blocks和sections；用户可以通过主题编辑器创建模板

Directory structure

目录结构

.
├── assets          # Stores static assets (CSS, JS, images, fonts, etc.)
├── blocks          # Reusable, nestable, customizable components
├── config          # Global theme settings and customization options
├── layout          # Top-level wrappers for pages (layout templates)
├── locales         # Translation files for theme internationalization
├── sections        # Modular full-width page components
├── snippets        # Reusable Liquid code or HTML fragments
└── templates       # Templates combining sections and blocks to define page structures

.
├── assets          # 存储静态资源（CSS、JS、图片、字体等）
├── blocks          # 可复用、可嵌套、可自定义的组件
├── config          # 全局主题设置和自定义选项
├── layout          # 页面的顶层包装器（布局模板）
├── locales         # 主题国际化的翻译文件
├── sections        # 模块化的全宽页面组件
├── snippets        # 可复用的Liquid代码或HTML片段
└── templates       # 组合sections和blocks定义页面结构的模板

sections

sections

Sections are
```
.liquid
```
files that allow you to create reusable modules that can be customized by merchants
Sections can include blocks which allow merchants to add, remove, and reorder content within a section
Sections are made customizable by including the required
```
{% schema %}
```
tag that exposes settings in the theme editor via a JSON object. Validate that JSON object using the
```
schemas/section.json
```
JSON schema
Examples of sections: hero banners, product grids, testimonials, featured collections

Sections是
```
.liquid
```
文件，可用于创建商家可自定义的可复用模块
Sections可包含blocks，允许商家在section内添加、删除和重新排序内容
Sections通过包含必需的
```
{% schema %}
```
标签实现自定义，该标签通过JSON对象在主题编辑器中暴露设置。请使用
```
schemas/section.json
```
JSON schema校验该JSON对象
Sections示例：首屏横幅、商品网格、用户评价、精选合集

blocks

blocks

Blocks are
```
.liquid
```
files that allow you to create reusable small components that can be customized by merchants (they don't need to fit the full-width of the page)
Blocks are ideal for logic that needs to be reused and also edited in the theme editor by merchants
Blocks can include other nested blocks which allow merchants to add, remove, and reorder content within a block too
Blocks are made customizable by including the required
```
{% schema %}
```
tag that exposes settings in the theme editor via a JSON object. Validate that JSON object using the
```
schemas/theme_block.json
```
JSON schema
Blocks must have the
```
{% doc %}
```
tag as the header if you directly/staticly render them in other file via
```
{% content_for 'block', id: '42', type: 'block_name' %}
```
Examples of blocks: individual testimonials, slides in a carousel, feature items

Blocks是
```
.liquid
```
文件，可用于创建商家可自定义的小型可复用组件（不需要占满页面全宽）
Blocks非常适合需要复用且允许商家在主题编辑器中编辑的逻辑
Blocks可包含其他嵌套的block，允许商家在block内添加、删除和重新排序内容
Blocks通过包含必需的
```
{% schema %}
```
标签实现自定义，该标签通过JSON对象在主题编辑器中暴露设置。请使用
```
schemas/theme_block.json
```
JSON schema校验该JSON对象
如果你通过
```
{% content_for 'block', id: '42', type: 'block_name' %}
```
在其他文件中直接/静态渲染blocks，则blocks必须以
```
{% doc %}
```
标签作为头部
Blocks示例：单个用户评价、轮播图的单张幻灯片、功能项

snippets

snippets

Snippets are reusable code fragments rendered in blocks, sections, and layouts files via the
```
render
```
tag
Snippets are ideal for logic that needs to be reused but not directly edited in the theme editor by merchants
Snippets accept parameters when rendered for dynamic behavior
Snippets must have the
```
{% doc %}
```
tag as the header
Examples of sections: buttons, meta-tags, css-variables, and form elements

Snippets是可复用的代码片段，可通过
```
render
```
标签在blocks、sections和layout文件中渲染
Snippets非常适合需要复用但不需要商家在主题编辑器中直接编辑的逻辑
Snippets在渲染时可接受参数以实现动态行为
Snippets必须以
```
{% doc %}
```
标签作为头部
Snippets示例：按钮、meta标签、css变量、表单元素

layout

layout

Defines the overall HTML structure of the site, including
```
<head>
```
and
```
<body>
```
, and wraps other templates to provide a consistent frame
Contains repeated global elements like navigation, cart drawer, footer, and usually includes CSS/JS assets and meta tags
Must include
```
{{ content_for_header }}
```
to inject Shopify scripts in the
```
<head>
```
and
```
{{ content_for_layout }}
```
to render the page content

定义站点的整体HTML结构，包括
```
<head>
```
和
```
<body>
```
，并包装其他模板以提供一致的框架
包含重复的全局元素，如导航、购物车抽屉、页脚，通常还包含CSS/JS资源和meta标签
必须包含
```
{{ content_for_header }}
```
以在
```
<head>
```
中注入Shopify脚本，以及
```
{{ content_for_layout }}
```
以渲染页面内容

config

config

```
config/settings_schema.json
```
is a JSON file that defines schema for global theme settings. Validate the shape shape of this JSON file using the
```
schemas/theme_settings.json
```
JSON schema
```
config/settings_data.json
```
is JSON file that holds the data for the settings defined by
```
config/settings_schema.json
```

```
config/settings_schema.json
```
是定义全局主题设置schema的JSON文件。请使用
```
schemas/theme_settings.json
```
JSON schema校验该JSON文件的结构

config/settings_data.json

是存储

config/settings_schema.json

定义的设置对应数据的JSON文件

assets

assets

Contains static files like CSS, JavaScript, and images—including compiled and optimized assets—referenced in templates via the
```
asset_url
```
filter
Keep it here only
```
critical.css
```
and static files necessary for every page, otherwise prefer the usage of the
```
{% stylesheet %}
```
and
```
{% javascript %}
```
tags

包含静态文件，如CSS、JavaScript和图片（包括编译和优化后的资源），可通过
```
asset_url
```
过滤器在模板中引用
仅在此处存放
```
critical.css
```
和每个页面都必需的静态文件，其他情况优先使用
```
{% stylesheet %}
```
和
```
{% javascript %}
```
标签

locales

locales

Stores translation files organized by language code (e.g.,
```
en.default.json
```
,
```
fr.json
```
) to localize all user-facing theme content and editor strings
Enables multi-language support by providing translations accessible via filters like
```
{{ 'key' | t }}
```
in Liquid for proper internationalization
Validate
```
locales
```
JSON files using the
```
schemas/translations.json
```
JSON schema

存储按语言代码组织的翻译文件（如
```
en.default.json
```
、
```
fr.json
```
），用于本地化所有面向用户的主题内容和编辑器字符串
通过Liquid中
```
{{ 'key' | t }}
```
等过滤器可访问翻译内容，实现多语言支持，完成 proper 国际化
请使用
```
schemas/translations.json
```
JSON schema校验
```
locales
```
JSON文件

templates

templates

JSON file that define the structure, ordering, and which sections and blocks appear on each page type, allowing merchants to customize layouts without code changes

JSON文件，定义每个页面类型的结构、排序以及显示的sections和blocks，允许商家无需修改代码即可自定义布局

CSS & JavaScript

Write CSS and JavaScript per components using the
```
{% stylesheet %}
```
and
```
{% javascript %}
```
tags

Note:

{% stylesheet %}

and

{% javascript %}

are only supported in

snippets/

blocks/

, and

sections/

使用
```
{% stylesheet %}
```
和
```
{% javascript %}
```
标签为每个组件编写CSS和JavaScript

注意：

{% stylesheet %}

和

{% javascript %}

仅在

snippets/

、

blocks/

和

sections/

中支持

LiquidDoc

Snippets and blocks (when blocks are statically rendered) must include the LiquidDoc header that documents the purpose of the file and required parameters. Example:

liquid

{% doc %}
  Renders a responsive image that might be wrapped in a link.

  @param {image} image - The image to be rendered
  @param {string} [url] - An optional destination URL for the image

  @example
  {% render 'image', image: product.featured_image %}
{% enddoc %}

<a href="{{ url | default: '#' }}">{{ image | image_url: width: 200, height: 200 | image_tag }}</a>

Snippets和blocks（静态渲染时）必须包含LiquidDoc头部，用于记录文件的用途和所需参数。示例：

liquid

{% doc %}
  Renders a responsive image that might be wrapped in a link.

  @param {image} image - The image to be rendered
  @param {string} [url] - An optional destination URL for the image

  @example
  {% render 'image', image: product.featured_image %}
{% enddoc %}

<a href="{{ url | default: '#' }}">{{ image | image_url: width: 200, height: 200 | image_tag }}</a>

The

{% schema %}

tag on blocks and sections

blocks和sections上的

{% schema %}

标签

Key principles: follow the "Good practices" and "Validate the
{% schema %}
content" using JSON schemas

核心原则：遵循「最佳实践」，并使用JSON schema校验
{% schema %}
内容

Good practices

最佳实践

When defining the

{% schema %}

tag on sections and blocks, follow these guidelines to use the values:

Single property settings: For settings that correspond to a single CSS property, use CSS variables:

liquid

<div class="collection" style="--gap: {{ block.settings.gap }}px">
  Example
</div>

{% stylesheet %}
  .collection {
    gap: var(--gap);
  }
{% endstylesheet %}

{% schema %}
{
  "settings": [{
    "type": "range",
    "label": "gap",
    "id": "gap",
    "min": 0,
    "max": 100,
    "unit": "px",
    "default": 0,
  }]
}
{% endschema %}

Multiple property settings: For settings that control multiple CSS properties, use CSS classes:

liquid

<div class="collection {{ block.settings.layout }}">
  Example
</div>

{% stylesheet %}
  .collection--full-width {
    /* multiple styles */
  }
  .collection--narrow {
    /* multiple styles */
  }
{% endstylesheet %}

{% schema %}
{
  "settings": [{
    "type": "select",
    "id": "layout",
    "label": "layout",
    "values": [
      { "value": "collection--full-width", "label": "t:options.full" },
      { "value": "collection--narrow", "label": "t:options.narrow" }
    ]
  }]
}
{% endschema %}

在sections和blocks上定义

{% schema %}

标签时，遵循以下指南使用设置值：

单属性设置：对于对应单个CSS属性的设置，使用CSS变量：

liquid

<div class="collection" style="--gap: {{ block.settings.gap }}px">
  示例
</div>

{% stylesheet %}
  .collection {
    gap: var(--gap);
  }
{% endstylesheet %}

{% schema %}
{
  "settings": [{
    "type": "range",
    "label": "gap",
    "id": "gap",
    "min": 0,
    "max": 100,
    "unit": "px",
    "default": 0,
  }]
}
{% endschema %}

多属性设置：对于控制多个CSS属性的设置，使用CSS类：

liquid

<div class="collection {{ block.settings.layout }}">
  示例
</div>

{% stylesheet %}
  .collection--full-width {
    /* 多个样式 */
  }
  .collection--narrow {
    /* 多个样式 */
  }
{% endstylesheet %}

{% schema %}
{
  "settings": [{
    "type": "select",
    "id": "layout",
    "label": "layout",
    "values": [
      { "value": "collection--full-width", "label": "t:options.full" },
      { "value": "collection--narrow", "label": "t:options.narrow" }
    ]
  }]
}
{% endschema %}

Mobile layouts

移动端布局

If you need to create a mobile layout and you want the merchant to be able to select one or two columns, use a select input:

liquid

{% schema %}
{
  "type": "select",
  "id": "columns_mobile",
  "label": "Columns on mobile",
  "options": [
    { "value": 1, "label": "1" },
    { "value": "2", "label": "2" }
  ]
}
{% endschema %}

如果你需要创建移动端布局，并且希望商家可以选择1列或2列，请使用select输入框：

liquid

{% schema %}
{
  "type": "select",
  "id": "columns_mobile",
  "label": "移动端列数",
  "options": [
    { "value": 1, "label": "1" },
    { "value": "2", "label": "2" }
  ]
}
{% endschema %}

Liquid

Liquid delimiters

Liquid分隔符

{{ ... }}
: Output – prints a value.
{{- ... -}}
: Output, trims whitespace around the value.
{% ... %}
: Logic/control tag (if, for, assign, etc.), does not print anything, no whitespace trim.
{%- ... -%}
: Logic/control tag, trims whitespace around the tag.

Tip: Adding a dash (

) after

{%

{{

or before

%}

}}

trims spaces or newlines next to the tag.

Examples:

```
{{- product.title -}}
```
→ print value, remove surrounding spaces or lines.

{%- if available -%}In stock{%- endif -%}

→ logic, removes extra spaces/lines.

{{ ... }}
：输出 – 打印值
{{- ... -}}
：输出，修剪值周围的空白
{% ... %}
：逻辑/控制标签（if、for、assign等），不打印任何内容，不修剪空白
{%- ... -%}
：逻辑/控制标签，修剪标签周围的空白

提示： 在

{%

{{

后或

%}

}}

前添加短横线(

)会修剪标签旁边的空格或换行符。

示例：

```
{{- product.title -}}
```
→ 打印值，移除周围的空格或换行
```
{%- if available -%}有货{%- endif -%}
```
→ 逻辑，移除多余的空格/换行

Liquid operators

Liquid运算符

Comparison operators:

Logical operators:

```
or
```
```
and
```
```
contains
```
- checks if a string contains a substring, or if an array contains a string

比较运算符：

逻辑运算符：

```
or
```
```
and
```
```
contains
```
– 检查字符串是否包含子字符串，或数组是否包含字符串

Comparison and comparison tags

比较和比较标签

Key condition principles:

For simplificity, ALWAYS use nested
```
if
```
conditions when the logic requires more than one logical operator
Parentheses are not supported in Liquid
Ternary conditionals are not supported in Liquid, so always use
```
{% if cond %}
```

Basic comparison example:

liquid

{% if product.title == "Awesome Shoes" %}
  These shoes are awesome!
{% endif %}

Multiple Conditions:

liquid

{% if product.type == "Shirt" or product.type == "Shoes" %}
  This is a shirt or a pair of shoes.
{% endif %}

Contains Usage:

For strings:
```
{% if product.title contains "Pack" %}
```
For arrays:
```
{% if product.tags contains "Hello" %}
```
Note:
```
contains
```
only works with strings, not objects in arrays

{% elsif %} (used inside if/unless only)

liquid

{% if a %}
  ...
{% elsif b %}
  ...
{% endif %}

{% unless %}

liquid

{% unless condition %}
  ...
{% endunless %}

{% case %}

liquid

{% case variable %}
  {% when 'a' %}
    a
  {% when 'b' %}
    b
  {% else %}
    other
{% endcase %}

{% else %} (used inside if, unless, case, or for)

liquid

{% if product.available %}
  In stock
{% else %}
  Sold out
{% endif %}

or inside a for loop:

liquid

{% for item in collection.products %}
  {{ item.title }}
{% else %}
  No products found.
{% endfor %}

核心条件原则：

为简化逻辑，当逻辑需要多个逻辑运算符时，始终使用嵌套的
```
if
```
条件
Liquid不支持括号
Liquid不支持三元条件，因此始终使用
```
{% if cond %}
```

基础比较示例：

liquid

{% if product.title == "Awesome Shoes" %}
  这双鞋太棒了！
{% endif %}

多条件：

liquid

{% if product.type == "Shirt" or product.type == "Shoes" %}
  这是一件衬衫或一双鞋。
{% endif %}

contains用法：

字符串用法：
```
{% if product.title contains "Pack" %}
```
数组用法：
```
{% if product.tags contains "Hello" %}
```
注意：
```
contains
```
仅适用于字符串，不适用于数组中的对象

{% elsif %}（仅在if/unless内部使用）

liquid

{% if a %}
  ...
{% elsif b %}
  ...
{% endif %}

{% unless %}

liquid

{% unless condition %}
  ...
{% endunless %}

{% case %}

liquid

{% case variable %}
  {% when 'a' %}
    a
  {% when 'b' %}
    b
  {% else %}
    其他
{% endcase %}

{% else %}（在if、unless、case或for内部使用）

liquid

{% if product.available %}
  有货
{% else %}
  售罄
{% endif %}

或在for循环内部使用：

liquid

{% for item in collection.products %}
  {{ item.title }}
{% else %}
  未找到商品。
{% endfor %}

Variables and variable tags

变量和变量标签

liquid

{% assign my_variable = 'value' %}

{% capture my_variable %}
  Contents of variable
{% endcapture %}

{% increment counter %}
{% decrement counter %}

liquid

{% assign my_variable = 'value' %}

{% capture my_variable %}
  变量内容
{% endcapture %}

{% increment counter %}
{% decrement counter %}

Liquid filters

Liquid过滤器

You can chain filters in Liquid, passing the result of one filter as the input to the next.

See these filters:

```
upcase
```
:
```
{{ string | upcase }}
```
returns a string
```
split
```
:
```
{{ string | split: string }}
```
returns an array (as we may notice in the docs,
```
split
```
receives a string as its argument)
```
last
```
:
```
{{ array | last }}
```
returns untyped

Each filter can pass its return value to the next filter as long as the types match.

For example,

upcase

returns a string, which is suitable input for

split

, which then produces an array for

last

to use.

Here's how the filters are executed step by step to eventually return

"WORLD"

liquid

{{ "hello world" | upcase | split: " " | last }}

First,
```
"hello world"
```
is converted to uppercase:
```
"HELLO WORLD"
```
, which is a string
Next,
```
split
```
can act on strings, so it splits the value by space into an array:
```
["HELLO", "WORLD"]
```
Finally, the
```
last
```
filter work with array, so
```
"WORLD"
```
is returned

你可以在Liquid中链式使用过滤器，将一个过滤器的结果作为下一个过滤器的输入。

参考这些过滤器：

```
upcase
```
：
```
{{ string | upcase }}
```
返回 字符串
```
split
```
：
```
{{ string | split: string }}
```
返回数组（正如文档中提到的，
```
split
```
接收字符串作为参数）
```
last
```
：
```
{{ array | last }}
```
返回 无类型

只要类型匹配，每个过滤器都可以将其返回值传递给下一个过滤器。

例如，

upcase

返回字符串，适合作为

split

的输入，

split

生成数组供

last

使用。

以下是过滤器逐步执行最终返回

"WORLD"

的过程：

liquid

{{ "hello world" | upcase | split: " " | last }}

首先，
```
"hello world"
```
被转换为大写：
```
"HELLO WORLD"
```
，是字符串
接下来，
```
split
```
作用于字符串，按空格将值拆分为数组：
```
["HELLO", "WORLD"]
```
最后，
```
last
```
过滤器处理数组，返回
```
"WORLD"
```

Array

数组

```
compact
```
:
```
{{ array | compact }}
```
returns
```
array
```
```
concat
```
:
```
{{ array | concat: array }}
```
returns
```
array
```

find

{{ array | find: string, string }}

returns

untyped

find_index

{{ array | find_index: string, string }}

returns

number

```
first
```
:
```
{{ array | first }}
```
returns
```
untyped
```

has

{{ array | has: string, string }}

returns

boolean

```
join
```
:
```
{{ array | join }}
```
returns
```
string
```
```
last
```
:
```
{{ array | last }}
```
returns
```
untyped
```
```
map
```
:
```
{{ array | map: string }}
```
returns
```
array
```

reject

{{ array | reject: string, string }}

returns

array

```
reverse
```
:
```
{{ array | reverse }}
```
returns
```
array
```
```
size
```
:
```
{{ variable | size }}
```
returns
```
number
```
```
sort
```
:
```
{{ array | sort }}
```
returns
```
array
```

sort_natural

{{ array | sort_natural }}

returns

array

```
sum
```
:
```
{{ array | sum }}
```
returns
```
number
```
```
uniq
```
:
```
{{ array | uniq }}
```
returns
```
array
```

where

{{ array | where: string, string }}

returns

array

```
compact
```
：
```
{{ array | compact }}
```
返回
```
array
```
```
concat
```
：
```
{{ array | concat: array }}
```
返回
```
array
```

find

：

{{ array | find: string, string }}

untyped

find_index

：

{{ array | find_index: string, string }}

number

```
first
```
：
```
{{ array | first }}
```
返回
```
untyped
```

has

：

{{ array | has: string, string }}

boolean

```
join
```
：
```
{{ array | join }}
```
返回
```
string
```
```
last
```
：
```
{{ array | last }}
```
返回
```
untyped
```
```
map
```
：
```
{{ array | map: string }}
```
返回
```
array
```

reject

：

{{ array | reject: string, string }}

array

```
reverse
```
：
```
{{ array | reverse }}
```
返回
```
array
```
```
size
```
：
```
{{ variable | size }}
```
返回
```
number
```
```
sort
```
：
```
{{ array | sort }}
```
返回
```
array
```

sort_natural

：

{{ array | sort_natural }}

array

```
sum
```
：
```
{{ array | sum }}
```
返回
```
number
```
```
uniq
```
：
```
{{ array | uniq }}
```
返回
```
array
```

where

：

{{ array | where: string, string }}

array

Cart

购物车

item_count_for_variant

{{ cart | item_count_for_variant: {variant_id} }}

returns

number

line_items_for

{{ cart | line_items_for: object }}

returns

array

item_count_for_variant

：

{{ cart | item_count_for_variant: {variant_id} }}

number

line_items_for

：

{{ cart | line_items_for: object }}

array

Collection

合集

link_to_type

{{ string | link_to_type }}

returns

string

link_to_vendor

{{ string | link_to_vendor }}

returns

string

sort_by

{{ string | sort_by: string }}

returns

string

url_for_type

{{ string | url_for_type }}

returns

string

url_for_vendor

{{ string | url_for_vendor }}

returns

string

within

{{ string | within: collection }}

returns

string

highlight_active_tag

{{ string | highlight_active_tag }}

returns

string

link_to_type

：

{{ string | link_to_type }}

string

link_to_vendor

：

{{ string | link_to_vendor }}

string

sort_by

：

{{ string | sort_by: string }}

string

url_for_type

：

{{ string | url_for_type }}

string

url_for_vendor

：

{{ string | url_for_vendor }}

string

within

：

{{ string | within: collection }}

string

highlight_active_tag

：

{{ string | highlight_active_tag }}

string

Color

颜色

brightness_difference

{{ string | brightness_difference: string }}

returns

number

color_brightness

{{ string | color_brightness }}

returns

number

color_contrast

{{ string | color_contrast: string }}

returns

number

color_darken

{{ string | color_darken: number }}

returns

string

color_desaturate

{{ string | color_desaturate: number }}

returns

string

color_difference

{{ string | color_difference: string }}

returns

number

color_extract

{{ string | color_extract: string }}

returns

number

color_lighten

{{ string | color_lighten: number }}

returns

string

color_mix

{{ string | color_mix: string, number }}

returns

string

color_modify

{{ string | color_modify: string, number }}

returns

string

color_saturate

{{ string | color_saturate: number }}

returns

string

color_to_hex

{{ string | color_to_hex }}

returns

string

color_to_hsl

{{ string | color_to_hsl }}

returns

string

color_to_oklch

{{ string | color_to_oklch }}

returns

string

color_to_rgb

{{ string | color_to_rgb }}

returns

string

hex_to_rgba

{{ string | hex_to_rgba }}

returns

string

brightness_difference

：

{{ string | brightness_difference: string }}

number

color_brightness

：

{{ string | color_brightness }}

number

color_contrast

：

{{ string | color_contrast: string }}

number

color_darken

：

{{ string | color_darken: number }}

string

color_desaturate

：

{{ string | color_desaturate: number }}

string

color_difference

：

{{ string | color_difference: string }}

number

color_extract

：

{{ string | color_extract: string }}

number

color_lighten

：

{{ string | color_lighten: number }}

string

color_mix

：

{{ string | color_mix: string, number }}

string

color_modify

：

{{ string | color_modify: string, number }}

string

color_saturate

：

{{ string | color_saturate: number }}

string

color_to_hex

：

{{ string | color_to_hex }}

string

color_to_hsl

：

{{ string | color_to_hsl }}

string

color_to_oklch

：

{{ string | color_to_oklch }}

string

color_to_rgb

：

{{ string | color_to_rgb }}

string

hex_to_rgba

：

{{ string | hex_to_rgba }}

string

Customer

客户

customer_login_link

{{ string | customer_login_link }}

returns

string

customer_logout_link

{{ string | customer_logout_link }}

returns

string

customer_register_link

{{ string | customer_register_link }}

returns

string

```
avatar
```
:
```
{{ customer | avatar }}
```
returns
```
string
```

login_button

{{ shop | login_button }}

returns

string

customer_login_link

：

{{ string | customer_login_link }}

string

customer_logout_link

：

{{ string | customer_logout_link }}

string

customer_register_link

：

{{ string | customer_register_link }}

string

```
avatar
```
：
```
{{ customer | avatar }}
```
返回
```
string
```

login_button

：

{{ shop | login_button }}

string

Date

日期

```
date
```
:
```
{{ date | date: string }}
```
returns
```
string
```

```
date
```
：
```
{{ date | date: string }}
```
返回
```
string
```

Default

默认

default_errors

{{ string | default_errors }}

returns

string

default

{{ variable | default: variable }}

returns

untyped

default_pagination

{{ paginate | default_pagination }}

returns

string

default_errors

：

{{ string | default_errors }}

string

default

：

{{ variable | default: variable }}

untyped

default_pagination

：

{{ paginate | default_pagination }}

string

Font

字体

```
font_face
```
:
```
{{ font | font_face }}
```
returns
```
string
```

font_modify

{{ font | font_modify: string, string }}

returns

font

```
font_url
```
:
```
{{ font | font_url }}
```
returns
```
string
```

```
font_face
```
：
```
{{ font | font_face }}
```
返回
```
string
```

font_modify

：

{{ font | font_modify: string, string }}

font

```
font_url
```
：
```
{{ font | font_url }}
```
返回
```
string
```

Format

格式

```
date
```
:
```
{{ string | date: string }}
```
returns
```
string
```
```
json
```
:
```
{{ variable | json }}
```
returns
```
string
```

structured_data

{{ variable | structured_data }}

returns

string

unit_price_with_measurement

{{ number | unit_price_with_measurement: unit_price_measurement }}

returns

string

weight_with_unit

{{ number | weight_with_unit }}

returns

string

```
date
```
：
```
{{ string | date: string }}
```
返回
```
string
```
```
json
```
：
```
{{ variable | json }}
```
返回
```
string
```

structured_data

：

{{ variable | structured_data }}

string

unit_price_with_measurement

：

{{ number | unit_price_with_measurement: unit_price_measurement }}

string

weight_with_unit

：

{{ number | weight_with_unit }}

string

Hosted_file

托管文件

asset_img_url

{{ string | asset_img_url }}

returns

string

```
asset_url
```
:
```
{{ string | asset_url }}
```
returns
```
string
```

file_img_url

{{ string | file_img_url }}

returns

string

```
file_url
```
:
```
{{ string | file_url }}
```
returns
```
string
```

global_asset_url

{{ string | global_asset_url }}

returns

string

shopify_asset_url

{{ string | shopify_asset_url }}

returns

string

asset_img_url

：

{{ string | asset_img_url }}

string

```
asset_url
```
：
```
{{ string | asset_url }}
```
返回
```
string
```

file_img_url

：

{{ string | file_img_url }}

string

```
file_url
```
：
```
{{ string | file_url }}
```
返回
```
string
```

global_asset_url

：

{{ string | global_asset_url }}

string

shopify_asset_url

：

{{ string | shopify_asset_url }}

string

Html

class_list

{{ settings.layout | class_list }}

returns

string

time_tag

{{ string | time_tag: string }}

returns

string

inline_asset_content

{{ asset_name | inline_asset_content }}

returns

string

highlight

{{ string | highlight: string }}

returns

string

link_to

{{ string | link_to: string }}

returns

string

placeholder_svg_tag

{{ string | placeholder_svg_tag }}

returns

string

preload_tag

{{ string | preload_tag: as: string }}

returns

string

script_tag

{{ string | script_tag }}

returns

string

stylesheet_tag

{{ string | stylesheet_tag }}

returns

string

class_list

：

{{ settings.layout | class_list }}

string

time_tag

：

{{ string | time_tag: string }}

string

inline_asset_content

：

{{ asset_name | inline_asset_content }}

string

highlight

：

{{ string | highlight: string }}

string

link_to

：

{{ string | link_to: string }}

string

placeholder_svg_tag

：

{{ string | placeholder_svg_tag }}

string

preload_tag

：

{{ string | preload_tag: as: string }}

string

script_tag

：

{{ string | script_tag }}

string

stylesheet_tag

：

{{ string | stylesheet_tag }}

string

Localization

本地化

currency_selector

{{ form | currency_selector }}

returns

string

```
translate
```
:
```
{{ string | t }}
```
returns
```
string
```

format_address

{{ address | format_address }}

returns

string

currency_selector

：

{{ form | currency_selector }}

string

```
translate
```
：
```
{{ string | t }}
```
返回
```
string
```

format_address

：

{{ address | format_address }}

string

Math

数学

```
abs
```
:
```
{{ number | abs }}
```
returns
```
number
```
```
at_least
```
:
```
{{ number | at_least }}
```
returns
```
number
```
```
at_most
```
:
```
{{ number | at_most }}
```
returns
```
number
```
```
ceil
```
:
```
{{ number | ceil }}
```
returns
```
number
```

divided_by

{{ number | divided_by: number }}

returns

number

```
floor
```
:
```
{{ number | floor }}
```
returns
```
number
```
```
minus
```
:
```
{{ number | minus: number }}
```
returns
```
number
```

modulo

{{ number | modulo: number }}

returns

number

```
plus
```
:
```
{{ number | plus: number }}
```
returns
```
number
```
```
round
```
:
```
{{ number | round }}
```
returns
```
number
```
```
times
```
:
```
{{ number | times: number }}
```
returns
```
number
```

```
abs
```
：
```
{{ number | abs }}
```
返回
```
number
```
```
at_least
```
：
```
{{ number | at_least }}
```
返回
```
number
```
```
at_most
```
：
```
{{ number | at_most }}
```
返回
```
number
```
```
ceil
```
：
```
{{ number | ceil }}
```
返回
```
number
```

divided_by

：

{{ number | divided_by: number }}

number

```
floor
```
：
```
{{ number | floor }}
```
返回
```
number
```
```
minus
```
：
```
{{ number | minus: number }}
```
返回
```
number
```

modulo

：

{{ number | modulo: number }}

number

```
plus
```
：
```
{{ number | plus: number }}
```
返回
```
number
```
```
round
```
：
```
{{ number | round }}
```
返回
```
number
```
```
times
```
：
```
{{ number | times: number }}
```
返回
```
number
```

Media

媒体

external_video_tag

{{ variable | external_video_tag }}

returns

string

external_video_url

{{ media | external_video_url: attribute: string }}

returns

string

```
image_tag
```
:
```
{{ string | image_tag }}
```
returns
```
string
```
```
media_tag
```
:
```
{{ media | media_tag }}
```
returns
```
string
```

model_viewer_tag

{{ media | model_viewer_tag }}

returns

string

```
video_tag
```
:
```
{{ media | video_tag }}
```
returns
```
string
```

article_img_url

{{ variable | article_img_url }}

returns

string

collection_img_url

{{ variable | collection_img_url }}

returns

string

image_url

{{ variable | image_url: width: number, height: number }}

returns

string

```
img_tag
```
:
```
{{ string | img_tag }}
```
returns
```
string
```
```
img_url
```
:
```
{{ variable | img_url }}
```
returns
```
string
```

product_img_url

{{ variable | product_img_url }}

returns

string

external_video_tag

：

{{ variable | external_video_tag }}

string

external_video_url

：

{{ media | external_video_url: attribute: string }}

string

```
image_tag
```
：
```
{{ string | image_tag }}
```
返回
```
string
```
```
media_tag
```
：
```
{{ media | media_tag }}
```
返回
```
string
```

model_viewer_tag

：

{{ media | model_viewer_tag }}

string

```
video_tag
```
：
```
{{ media | video_tag }}
```
返回
```
string
```

article_img_url

：

{{ variable | article_img_url }}

string

collection_img_url

：

{{ variable | collection_img_url }}

string

image_url

：

{{ variable | image_url: width: number, height: number }}

string

```
img_tag
```
：
```
{{ string | img_tag }}
```
返回
```
string
```
```
img_url
```
：
```
{{ variable | img_url }}
```
返回
```
string
```

product_img_url

：

{{ variable | product_img_url }}

string

Metafield

元字段

metafield_tag

{{ metafield | metafield_tag }}

returns

string

metafield_text

{{ metafield | metafield_text }}

returns

string

metafield_tag

：

{{ metafield | metafield_tag }}

string

metafield_text

：

{{ metafield | metafield_text }}

string

Money

金额

```
money
```
:
```
{{ number | money }}
```
returns
```
string
```

money_with_currency

{{ number | money_with_currency }}

returns

string

money_without_currency

{{ number | money_without_currency }}

returns

string

money_without_trailing_zeros

{{ number | money_without_trailing_zeros }}

returns

string

```
money
```
：
```
{{ number | money }}
```
返回
```
string
```

money_with_currency

：

{{ number | money_with_currency }}

string

money_without_currency

：

{{ number | money_without_currency }}

string

money_without_trailing_zeros

：

{{ number | money_without_trailing_zeros }}

string

Payment

支付

payment_button

{{ form | payment_button }}

returns

string

payment_terms

{{ form | payment_terms }}

returns

string

payment_type_img_url

{{ string | payment_type_img_url }}

returns

string

payment_type_svg_tag

{{ string | payment_type_svg_tag }}

returns

string

payment_button

：

{{ form | payment_button }}

string

payment_terms

：

{{ form | payment_terms }}

string

payment_type_img_url

：

{{ string | payment_type_img_url }}

string

payment_type_svg_tag

：

{{ string | payment_type_svg_tag }}

string

String

字符串

hmac_sha1

{{ string | hmac_sha1: string }}

returns

string

hmac_sha256

{{ string | hmac_sha256: string }}

returns

string

```
md5
```
:
```
{{ string | md5 }}
```
returns
```
string
```
```
sha1
```
:
```
{{ string | sha1: string }}
```
returns
```
string
```

sha256

{{ string | sha256: string }}

returns

string

append

{{ string | append: string }}

returns

string

base64_decode

{{ string | base64_decode }}

returns

string

base64_encode

{{ string | base64_encode }}

returns

string

base64_url_safe_decode

{{ string | base64_url_safe_decode }}

returns

string

base64_url_safe_encode

{{ string | base64_url_safe_encode }}

returns

string

capitalize

{{ string | capitalize }}

returns

string

```
downcase
```
:
```
{{ string | downcase }}
```
returns
```
string
```
```
escape
```
:
```
{{ string | escape }}
```
returns
```
string
```

escape_once

{{ string | escape_once }}

returns

string

```
lstrip
```
:
```
{{ string | lstrip }}
```
returns
```
string
```

newline_to_br

{{ string | newline_to_br }}

returns

string

prepend

{{ string | prepend: string }}

returns

string

remove

{{ string | remove: string }}

returns

string

remove_first

{{ string | remove_first: string }}

returns

string

remove_last

{{ string | remove_last: string }}

returns

string

replace

{{ string | replace: string, string }}

returns

string

replace_first

{{ string | replace_first: string, string }}

returns

string

replace_last

{{ string | replace_last: string, string }}

returns

string

```
rstrip
```
:
```
{{ string | rstrip }}
```
returns
```
string
```
```
slice
```
:
```
{{ string | slice }}
```
returns
```
string
```
```
split
```
:
```
{{ string | split: string }}
```
returns
```
array
```
```
strip
```
:
```
{{ string | strip }}
```
returns
```
string
```

strip_html

{{ string | strip_html }}

returns

string

strip_newlines

{{ string | strip_newlines }}

returns

string

truncate

{{ string | truncate: number }}

returns

string

truncatewords

{{ string | truncatewords: number }}

returns

string

```
upcase
```
:
```
{{ string | upcase }}
```
returns
```
string
```

url_decode

{{ string | url_decode }}

returns

string

url_encode

{{ string | url_encode }}

returns

string

```
camelize
```
:
```
{{ string | camelize }}
```
returns
```
string
```
```
handleize
```
:
```
{{ string | handleize }}
```
returns
```
string
```

url_escape

{{ string | url_escape }}

returns

string

url_param_escape

{{ string | url_param_escape }}

returns

string

pluralize

{{ number | pluralize: string, string }}

returns

string

hmac_sha1

：

{{ string | hmac_sha1: string }}

string

hmac_sha256

：

{{ string | hmac_sha256: string }}

string

```
md5
```
：
```
{{ string | md5 }}
```
返回
```
string
```
```
sha1
```
：
```
{{ string | sha1: string }}
```
返回
```
string
```

sha256

：

{{ string | sha256: string }}

string

append

：

{{ string | append: string }}

string

base64_decode

：

{{ string | base64_decode }}

string

base64_encode

：

{{ string | base64_encode }}

string

base64_url_safe_decode

：

{{ string | base64_url_safe_decode }}

string

base64_url_safe_encode

：

{{ string | base64_url_safe_encode }}

string

capitalize

：

{{ string | capitalize }}

string

```
downcase
```
：
```
{{ string | downcase }}
```
返回
```
string
```
```
escape
```
：
```
{{ string | escape }}
```
返回
```
string
```

escape_once

：

{{ string | escape_once }}

string

```
lstrip
```
：
```
{{ string | lstrip }}
```
返回
```
string
```

newline_to_br

：

{{ string | newline_to_br }}

string

prepend

：

{{ string | prepend: string }}

string

remove

：

{{ string | remove: string }}

string

remove_first

：

{{ string | remove_first: string }}

string

remove_last

：

{{ string | remove_last: string }}

string

replace

：

{{ string | replace: string, string }}

string

replace_first

：

{{ string | replace_first: string, string }}

string

replace_last

：

{{ string | replace_last: string, string }}

string

```
rstrip
```
：
```
{{ string | rstrip }}
```
返回
```
string
```
```
slice
```
：
```
{{ string | slice }}
```
返回
```
string
```
```
split
```
：
```
{{ string | split: string }}
```
返回
```
array
```
```
strip
```
：
```
{{ string | strip }}
```
返回
```
string
```

strip_html

：

{{ string | strip_html }}

string

strip_newlines

：

{{ string | strip_newlines }}

string

truncate

：

{{ string | truncate: number }}

string

truncatewords

：

{{ string | truncatewords: number }}

string

```
upcase
```
：
```
{{ string | upcase }}
```
返回
```
string
```

url_decode

：

{{ string | url_decode }}

string

url_encode

：

{{ string | url_encode }}

string

```
camelize
```
：
```
{{ string | camelize }}
```
返回
```
string
```
```
handleize
```
：
```
{{ string | handleize }}
```
返回
```
string
```

url_escape

：

{{ string | url_escape }}

string

url_param_escape

：

{{ string | url_param_escape }}

string

pluralize

：

{{ number | pluralize: string, string }}

string

Liquid objects

Liquid对象

Global objects

全局对象

```
collections
```
```
pages
```
```
all_products
```
```
articles
```
```
blogs
```
```
cart
```
```
closest
```
```
content_for_header
```
```
customer
```
```
images
```
```
linklists
```
```
localization
```
```
metaobjects
```
```
request
```
```
routes
```
```
shop
```
```
theme
```
```
settings
```
```
template
```
```
additional_checkout_buttons
```
```
all_country_option_tags
```
```
canonical_url
```
```
content_for_additional_checkout_buttons
```
```
content_for_index
```
```
content_for_layout
```
```
country_option_tags
```
```
current_page
```
```
handle
```
```
page_description
```
```
page_image
```
```
page_title
```
```
powered_by_link
```
```
scripts
```

```
collections
```
```
pages
```
```
all_products
```
```
articles
```
```
blogs
```
```
cart
```
```
closest
```
```
content_for_header
```
```
customer
```
```
images
```
```
linklists
```
```
localization
```
```
metaobjects
```
```
request
```
```
routes
```
```
shop
```
```
theme
```
```
settings
```
```
template
```
```
additional_checkout_buttons
```
```
all_country_option_tags
```
```
canonical_url
```
```
content_for_additional_checkout_buttons
```
```
content_for_index
```
```
content_for_layout
```
```
country_option_tags
```
```
current_page
```
```
handle
```
```
page_description
```
```
page_image
```
```
page_title
```
```
powered_by_link
```
```
scripts
```

/article

page

/article

页面

```
article
```
```
blog
```

```
article
```
```
blog
```

/blog

page

/blog

页面

```
blog
```
```
current_tags
```

```
blog
```
```
current_tags
```

/cart

page

/cart

页面

```
cart
```

```
cart
```

/checkout

page

/checkout

页面

```
checkout
```

```
checkout
```

/collection

page

/collection

页面

```
collection
```
```
current_tags
```

```
collection
```
```
current_tags
```

/customers/account

page

/customers/account

页面

```
customer
```

```
customer
```

/customers/addresses

page

/customers/addresses

页面

```
customer
```

```
customer
```

/customers/order

page

/customers/order

页面

```
customer
```
```
order
```

```
customer
```
```
order
```

/gift_card.liquid

page

/gift_card.liquid

页面

```
gift_card
```
```
recipient
```

```
gift_card
```
```
recipient
```

/metaobject

page

/metaobject

页面

```
metaobject
```

```
metaobject
```

/page

page

/page

页面

```
page
```

```
page
```

/product

page

/product

页面

```
product
```

```
product
```

/robots.txt.liquid

page

/robots.txt.liquid

页面

```
robots
```

```
robots
```

/search

page

/search

页面

```
search
```

```
search
```

Liquid tags

Liquid标签

content_for

The

content_for

tag requires a type parameter to differentiate between rendering a number of theme blocks (

'blocks'

) and a single static block (

'block'

Syntax:

{% content_for 'blocks' %}
{% content_for 'block', type: "slide", id: "slide-1" %}

content_for

标签需要一个type参数来区分渲染多个主题block（

'blocks'

）还是单个静态block（

'block'

）。

语法：

{% content_for 'blocks' %}
{% content_for 'block', type: "slide", id: "slide-1" %}

form

Because there are many different form types available in Shopify themes, the

form

tag requires a type. Depending on the form type, an additional parameter might be required. You can specify the following form types:

Syntax:

{% form 'form_type' %}
  content
{% endform %}

由于Shopify主题中有多种不同的表单类型，

form

标签需要指定type。根据表单类型的不同，可能需要额外的参数。你可以指定以下表单类型：

语法：

{% form 'form_type' %}
  content
{% endform %}

layout

Syntax:

{% layout name %}

语法：

{% layout name %}

assign

You can create variables of any basic type, object, or object property.

Caution: Predefined Liquid objects can be overridden by variables with the same name. To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.

Syntax:

{% assign variable_name = value %}

你可以创建任意基础类型、对象或对象属性的变量。

注意：预定义的Liquid对象可能会被同名变量覆盖。为确保你可以访问所有Liquid对象，请确保你的变量名与预定义对象的名称不冲突。

语法：

{% assign variable_name = value %}

break

Syntax:

{% break %}

语法：

{% break %}

capture

You can create complex strings with Liquid logic and variables.

Caution: Predefined Liquid objects can be overridden by variables with the same name. To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.

Syntax:

{% capture variable %}
  value
{% endcapture %}

你可以使用Liquid逻辑和变量创建复杂字符串。

注意：预定义的Liquid对象可能会被同名变量覆盖。为确保你可以访问所有Liquid对象，请确保你的变量名与预定义对象的名称不冲突。

语法：

{% capture variable %}
  value
{% endcapture %}

case

Syntax:

{% case variable %}
  {% when first_value %}
    first_expression
  {% when second_value %}
    second_expression
  {% else %}
    third_expression
{% endcase %}

语法：

{% case variable %}
  {% when first_value %}
    first_expression
  {% when second_value %}
    second_expression
  {% else %}
    third_expression
{% endcase %}

comment

Any text inside

comment

tags won't be output, and any Liquid code will be parsed, but not executed.

Syntax:

{% comment %}
  content
{% endcomment %}

comment

标签内的任何文本都不会输出，任何Liquid代码都会被解析但不会执行。

语法：

{% comment %}
  content
{% endcomment %}

continue

Syntax:

{% continue %}

语法：

{% continue %}

cycle

The

cycle

tag must be used inside a

for

loop.

Tip: Use the
cycle
tag to output text in a predictable pattern. For example, to apply odd/even classes to rows in a table.

Syntax:

{% cycle string, string, ... %}

cycle

标签必须在

for

循环内部使用。

提示：使用
cycle
标签可以按可预测的模式输出文本。例如，为表格的行应用奇/偶类。

语法：

{% cycle string, string, ... %}

decrement

Variables that are declared with

decrement

are unique to the layout, template, or section file that they're created in. However, the variable is shared across snippets included in the file.

Similarly, variables that are created with

decrement

are independent from those created with

assign

and

capture

. However,

decrement

and

increment

share variables.

Syntax:

{% decrement variable_name %}

使用

decrement

声明的变量仅在其创建所在的layout、template或section文件中唯一。但该变量会在文件包含的snippets中共享。

同样，使用

decrement

创建的变量与使用

assign

和

capture

创建的变量相互独立。但

decrement

和

increment

共享变量。

语法：

{% decrement variable_name %}

doc

The

doc

tag allows developers to include documentation within Liquid templates. Any content inside

doc

tags is not rendered or outputted. Liquid code inside will be parsed but not executed. This facilitates tooling support for features like code completion, linting, and inline documentation.

For detailed documentation syntax and examples, see the

LiquidDoc

reference.

Syntax:

{% doc %}
  Renders a message.

  @param {string} foo - A string value.
  @param {string} [bar] - An optional string value.

  @example
  {% render 'message', foo: 'Hello', bar: 'World' %}
{% enddoc %}

doc

标签允许开发者在Liquid模板中包含文档。

doc

标签内的任何内容都不会被渲染或输出。其中的Liquid代码会被解析但不会执行。这为代码补全、 linting和内联文档等工具功能提供了支持。

有关详细的文档语法和示例，请参阅

LiquidDoc

参考。

语法：

{% doc %}
  Renders a message.

  @param {string} foo - A string value.
  @param {string} [bar] - An optional string value.

  @example
  {% render 'message', foo: 'Hello', bar: 'World' %}
{% enddoc %}

echo

Using the

echo

tag is the same as wrapping an expression in curly brackets (

{{

and

}}

). However, unlike the curly bracket method, you can use the

echo

tag inside

liquid

tags.

Tip: You can use filters on expressions inside
echo
tags.

Syntax:

{% liquid
  echo expression
%}

使用

echo

标签与将表达式包裹在大括号(

{{

和

}}

)中效果相同。但与大括号方法不同的是，你可以在

liquid

标签内部使用

echo

标签。

提示：你可以在
echo
标签内的表达式上使用过滤器。

语法：

{% liquid
  echo expression
%}

for

You can do a maximum of 50 iterations with a

for

loop. If you need to iterate over more than 50 items, then use the

paginate

tag to split the items over multiple pages.

Tip: Every
for
loop has an associated
forloop
object with information about the loop.

Syntax:

{% for variable in array %}
  expression
{% endfor %}

for

循环最多可执行50次迭代。如果你需要遍历超过50个项目，请使用

paginate

标签将项目拆分到多个页面。

提示：每个
for
循环都有一个关联的
forloop
对象，包含循环的相关信息。

语法：

{% for variable in array %}
  expression
{% endfor %}

if

Syntax:

{% if condition %}
  expression
{% endif %}

语法：

{% if condition %}
  expression
{% endif %}

increment

Variables that are declared with

increment

are unique to the layout, template, or section file that they're created in. However, the variable is shared across snippets included in the file.

Similarly, variables that are created with

increment

are independent from those created with

assign

and

capture

. However,

increment

and

decrement

share variables.

Syntax:

{% increment variable_name %}

使用

increment

声明的变量仅在其创建所在的layout、template或section文件中唯一。但该变量会在文件包含的snippets中共享。

同样，使用

increment

创建的变量与使用

assign

和

capture

创建的变量相互独立。但

increment

和

decrement

共享变量。

语法：

{% increment variable_name %}

raw

Syntax:

{% raw %}
  expression
{% endraw %}

语法：

{% raw %}
  expression
{% endraw %}

render

Inside snippets and app blocks, you can't directly access variables that are created outside of the snippet or app block. However, you can specify variables as parameters to pass outside variables to snippets.

While you can't directly access created variables, you can access global objects, as well as any objects that are directly accessible outside the snippet or app block. For example, a snippet or app block inside the product template can access the

product

object, and a snippet or app block inside a section can access the

section

object.

Outside a snippet or app block, you can't access variables created inside the snippet or app block.

Note: When you render a snippet using the
render
tag, you can't use the
include
tag inside the snippet.

Syntax:

{% render 'filename' %}

在snippets和app block内部，你无法直接访问在snippet或app block外部创建的变量。但你可以指定变量作为参数，将外部变量传递给snippets。

虽然你无法直接访问创建的变量，但你可以访问全局对象，以及snippet或app block外部可直接访问的任何对象。例如，商品模板内部的snippet或app block可以访问

product

对象，section内部的snippet或app block可以访问

section

对象。

在snippet或app block外部，你无法访问在snippet或app block内部创建的变量。

注意：当你使用
render
标签渲染snippet时，你不能在snippet内部使用
include
标签。

语法：

{% render 'filename' %}

tablerow

The

tablerow

tag must be wrapped in HTML

<table>

and

</table>

tags.

Tip: Every
tablerow
loop has an associated
tablerowloop
object with information about the loop.

Syntax:

{% tablerow variable in array %}
  expression
{% endtablerow %}

tablerow

标签必须包裹在HTML

<table>

和

</table>

标签中。

提示：每个
tablerow
循环都有一个关联的
tablerowloop
对象，包含循环的相关信息。

语法：

{% tablerow variable in array %}
  expression
{% endtablerow %}

unless

Tip: Similar to the
if
tag, you can use
elsif
to add more conditions to an
unless
tag.

Syntax:

{% unless condition %}
  expression
{% endunless %}

提示：与
if
标签类似，你可以使用
elsif
为
unless
标签添加更多条件。

语法：

{% unless condition %}
  expression
{% endunless %}

paginate

Because

for

loops are limited to 50 iterations per page, you need to use the

paginate

tag to iterate over an array that has more than 50 items. The following arrays can be paginated:

Within the

paginate

tag, you have access to the

paginate

object. You can use this object, or the

default_pagination

filter, to build page navigation.

Syntax:

{% paginate array by page_size %}
  {% for item in array %}
    forloop_content
  {% endfor %}
{% endpaginate %}

The `paginate` tag allows the user to paginate to the 25,000th item in the array and no further. To reach items further in
the array the array should be filtered further before paginating. See
[Pagination Limits](/themes/best-practices/performance/platform#pagination-limits) for more information.

由于

for

循环每页最多限制50次迭代，你需要使用

paginate

标签来遍历包含超过50个项目的数组。以下数组支持分页：

在

paginate

标签内部，你可以访问

paginate

对象。你可以使用该对象或

default_pagination

过滤器来构建页面导航。

语法：

{% paginate array by page_size %}
  {% for item in array %}
    forloop_content
  {% endfor %}
{% endpaginate %}

`paginate`标签允许用户分页到数组中的第25000个项目，超出后无法继续访问。要访问数组中更靠后的项目，应在分页前进一步过滤数组。请参阅[分页限制](/themes/best-practices/performance/platform#pagination-limits)了解更多信息。

javascript

Each section, block or snippet can have only one

{% javascript %}

tag.

To learn more about how JavaScript that's defined between the

javascript

tags is loaded and run, refer to the documentation for javascript tags.

Caution: Liquid isn't rendered inside of
{% javascript %}
tags. Including Liquid code can cause syntax errors.

Syntax:

{% javascript %}
  javascript_code
{% endjavascript %}

每个section、block或snippet只能有一个

{% javascript %}

标签。

要了解

javascript

标签之间定义的JavaScript如何加载和运行，请参考javascript标签文档。

注意：
{% javascript %}
标签内部不会渲染Liquid。包含Liquid代码可能会导致语法错误。

语法：

{% javascript %}
  javascript_code
{% endjavascript %}

section

Rendering a section with the

section

tag renders a section statically. To learn more about sections and how to use them in your theme, refer to Render a section.

Syntax:

{% section 'name' %}

使用

section

标签渲染section会静态渲染该section。要了解更多关于sections以及如何在主题中使用它们的信息，请参考渲染section。

语法：

{% section 'name' %}

stylesheet

Each section, block or snippet can have only one

{% stylesheet %}

tag.

To learn more about how CSS that's defined between the

stylesheet

tags is loaded and run, refer to the documentation for stylesheet tags.

Caution: Liquid isn't rendered inside of
{% stylesheet %}
tags. Including Liquid code can cause syntax errors.

Syntax:

{% stylesheet %}
  css_styles
{% endstylesheet %}

每个section、block或snippet只能有一个

{% stylesheet %}

标签。

要了解

stylesheet

标签之间定义的CSS如何加载和运行，请参考stylesheet标签文档。

注意：
{% stylesheet %}
标签内部不会渲染Liquid。包含Liquid代码可能会导致语法错误。

语法：

{% stylesheet %}
  css_styles
{% endstylesheet %}

sections

Use this tag to render section groups as part of the theme's layout content. Place the

sections

tag where you want to render it in the layout.

To learn more about section groups and how to use them in your theme, refer to Section groups.

Syntax:

{% sections 'name' %}

使用此标签渲染section组，作为主题layout内容的一部分。将

sections

标签放在你希望在布局中渲染它的位置。

要了解更多关于section组以及如何在主题中使用它们的信息，请参考section组。

语法：

{% sections 'name' %}

style

Note: If you reference color settings inside
style
tags, then the associated CSS rules will update as the setting is changed in the theme editor, without a page refresh.

Syntax:

{% style %}
  CSS_rules
{% endstyle %}

注意：如果你在
style
标签内部引用颜色设置，那么当商家在主题编辑器中修改设置时，关联的CSS规则会自动更新，无需刷新页面。

语法：

{% style %}
  CSS_rules
{% endstyle %}

else

You can use the

else

tag with the following tags:

Syntax:

{% else %}
  expression

你可以将

else

标签与以下标签配合使用：

语法：

{% else %}
  expression

else

Syntax:

{% for variable in array %}
  first_expression
{% else %}
  second_expression
{% endfor %}

语法：

{% for variable in array %}
  first_expression
{% else %}
  second_expression
{% endfor %}

liquid

Because the tags don't have delimeters, each tag needs to be on its own line.

Tip: Use the
echo
tag to output an expression inside
liquid
tags.

Syntax:

{% liquid
  expression
%}

由于标签没有分隔符，每个标签需要单独占一行。

提示：使用
echo
标签在
liquid
标签内部输出表达式。

语法：

{% liquid
  expression
%}

Translation development standards

翻译开发标准

Translation requirements

翻译要求

Every user-facing text must use translation filters.
Update
locales/en.default.json
with all new keys.
Use descriptive, hierarchical keys for organization.
Only add English text; translators handle other languages.

所有面向用户的文本都必须使用翻译过滤器。
**更新
```
locales/en.default.json
```
**添加所有新的key。
使用描述性的分层key进行组织。
仅添加英文文本；其他语言由翻译人员处理。

Translation filter usage

翻译过滤器用法

Use
{{ 'key' | t }}
for all text:

liquid

<!-- Good -->
<h2>{{ 'sections.featured_collection.title' | t }}</h2>
<p>{{ 'sections.featured_collection.description' | t }}</p>
<button>{{ 'products.add_to_cart' | t }}</button>

<!-- Bad -->
<h2>Featured Collection</h2>
<p>Check out our best products</p>
<button>Add to cart</button>

所有文本都使用
{{ 'key' | t }}
：

liquid

<!-- 正确 -->
<h2>{{ 'sections.featured_collection.title' | t }}</h2>
<p>{{ 'sections.featured_collection.description' | t }}</p>
<button>{{ 'products.add_to_cart' | t }}</button>

<!-- 错误 -->
<h2>精选合集</h2>
<p>查看我们的最佳商品</p>
<button>加入购物车</button>

Translation with variables

带变量的翻译

Use variables for interpolation:

liquid

<!-- Liquid template -->
<p>{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}</p>
<p>{{ 'general.pagination.page' | t: page: paginate.current_page, pages: paginate.pages }}</p>

Corresponding keys in locale files:

json

{
  "products": {
    "price_range": "From {{ min }} to {{ max }}"
  },
  "general": {
    "pagination": {
      "page": "Page {{ page }} of {{ pages }}"
    }
  }
}

使用变量进行插值：

liquid

<!-- Liquid模板 -->
<p>{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}</p>
<p>{{ 'general.pagination.page' | t: page: paginate.current_page, pages: paginate.pages }}</p>

locale文件中对应的key：

json

{
  "products": {
    "price_range": "从{{ min }}到{{ max }}"
  },
  "general": {
    "pagination": {
      "page": "第{{ page }}页，共{{ pages }}页"
    }
  }
}

Best practices

最佳实践

Content guidelines:

Write clear, concise text.
Use sentence case for all user-facing text, including titles, headings, and button labels (capitalize only the first word and proper nouns; e.g.,
```
Featured collection
```
→
```
Featured collection
```
, not
```
Featured Collection
```
).
Be consistent with terminology.
Consider character limits for UI elements.

Variable usage:

Use interpolation rather than appending strings together.
Prioritize clarity over brevity for variable naming.
Escape variables unless they output HTML:
```
{{ variable | escape }}
```
.

内容指南：

编写清晰简洁的文本。
所有面向用户的文本（包括标题、副标题和按钮标签）使用句子大小写（仅首字母和专有名词大写；例如，
```
Featured collection
```
→
```
Featured collection
```
，而非
```
Featured Collection
```
）。
术语保持一致。
考虑UI元素的字符限制。

变量用法：

使用插值而非拼接字符串。
变量命名优先考虑清晰度而非简洁性。
除非变量输出HTML，否则对变量进行转义：
```
{{ variable | escape }}
```
。

Localization standards

本地化标准

Auto-attached when working in

locales/

directory.

在

locales/

目录下工作时自动附加。

File structure

文件结构

locales/
├── en.default.json          # English (required)
├── en.default.schema.json   # English (required)
├── es.json                  # Spanish
├── est.schema.json          # Spanish
├── fr.json                  # French
├── frt.schema.json          # French
└── pt-BR.json               # Portuguese
└── pt-BR..schema.json       # Portuguese

locales/
├── en.default.json          # 英语（必需）
├── en.default.schema.json   # 英语（必需）
├── es.json                  # 西班牙语
├── est.schema.json          # 西班牙语
├── fr.json                  # 法语
├── frt.schema.json          # 法语
└── pt-BR.json               # 葡萄牙语
└── pt-BR..schema.json       # 葡萄牙语

Locale files

Locale文件

Locale files are JSON files containing translations for all the text strings used throughout a Shopify theme and its editor. They let merchants easily update and localize repeated words and phrases, making it possible to translate store content and settings into multiple languages for international customers. These files provide a centralized way to manage and edit translations.

Example:

json

{
  "general": {
    "cart": "Cart",
    "checkout": "Checkout"
  },
  "products": {
    "add_to_cart": "Add to Cart"
  }
}

Locale文件是JSON文件，包含Shopify主题及其编辑器中使用的所有文本字符串的翻译。它们让商家可以轻松更新和本地化重复的单词和短语，从而可以将店铺内容和设置翻译成多种语言，服务于国际客户。这些文件提供了集中管理和编辑翻译的方式。

示例：

json

{
  "general": {
    "cart": "购物车",
    "checkout": "结算"
  },
  "products": {
    "add_to_cart": "加入购物车"
  }
}

Schema locale files

Schema locale文件

Schema locale files, saved with a .schema.json extension, store translation strings specifically for theme editor setting schemas. They follow a structured organization—category, group, and description—to give context to each translation, enabling accurate localization of editor content. Schema locale files must use the IETF language tag format in their naming, such as en-GB.schema.json for British English or fr-CA.schema.json for Canadian French.

Example:

json

{
  "products": {
    "card": {
      "description": "Product card layout"
    }
  }
}

Schema locale文件以.schema.json为扩展名，专门存储主题编辑器设置schema的翻译字符串。它们遵循结构化的组织方式——类别、组和描述——为每个翻译提供上下文，实现编辑器内容的准确本地化。Schema locale文件的命名必须使用IETF语言标签格式，例如en-GB.schema.json代表英式英语，fr-CA.schema.json代表加拿大法语。

示例：

json

{
  "products": {
    "card": {
      "description": "商品卡片布局"
    }
  }
}

Key organization

Key组织

Hierarchical structure:

json

{
  "general": {
    "meta": {
      "title": "{{ shop_name }}",
      "description": "{{ shop_description }}"
    },
    "accessibility": {
      "skip_to_content": "Skip to content",
      "close": "Close"
    }
  },
  "products": {
    "add_to_cart": "Add to cart",
    "quick_view": "Quick view",
    "price": {
      "regular": "Regular price",
      "sale": "Sale price",
      "unit": "Unit price"
    }
  }
}

Usage

liquid

{{ 'general.meta.title' | t: shop_name: shop.name }}
{{ 'general.meta.description' | t: shop_description: shop.description }}

分层结构：

json

{
  "general": {
    "meta": {
      "title": "{{ shop_name }}",
      "description": "{{ shop_description }}"
    },
    "accessibility": {
      "skip_to_content": "跳转到内容",
      "close": "关闭"
    }
  },
  "products": {
    "add_to_cart": "加入购物车",
    "quick_view": "快速预览",
    "price": {
      "regular": "原价",
      "sale": "促销价",
      "unit": "单价"
    }
  }
}

用法

liquid

{{ 'general.meta.title' | t: shop_name: shop.name }}
{{ 'general.meta.description' | t: shop_description: shop.description }}

Translation guidelines

翻译指南

Key naming:

Use descriptive, hierarchical keys
Maximum 3 levels deep
Use snake_case for key names
Group related translations

Content rules:

Keep text concise for UI elements
Use variables for dynamic content
Consider character limits
Maintain consistent terminology

Key命名：

使用描述性的分层key
最多3层深度
key名称使用snake_case
相关翻译分组存放

内容规则：

UI元素的文本保持简洁
动态内容使用变量
考虑字符限制
保持术语一致

Examples per kind of asset

各类资产示例

snippet

snippet

liquid

{% doc %}
  Renders a responsive image that might be wrapped in a link.

  When `width`, `height` and `crop` are provided, the image will be rendered
  with a fixed aspect ratio.

  Serves as an example of how to use the `image_url` filter and `image_tag` filter
  as well as how you can use LiquidDoc to document your code.

  @param {image} image - The image to be rendered
  @param {string} [url] - An optional destination URL for the image
  @param {string} [css_class] - Optional class to be added to the image wrapper
  @param {number} [width] - The highest resolution width of the image to be rendered
  @param {number} [height] - The highest resolution height of the image to be rendered
  @param {string} [crop] - The crop position of the image

  @example
  {% render 'image', image: product.featured_image %}
  {% render 'image', image: product.featured_image, url: product.url %}
  {% render 'image',
    css_class: 'product__image',
    image: product.featured_image,
    url: product.url,
    width: 1200,
    height: 800,
    crop: 'center',
  %}
{% enddoc %}

{% liquid
  unless height
    assign width = width | default: image.width
  endunless

  if url
    assign wrapper = 'a'
  else
    assign wrapper = 'div'
  endif
%}

<{{ wrapper }}
  class="image {{ css_class }}"
  {% if url %}
    href="{{ url }}"
  {% endif %}
>
  {{ image | image_url: width: width, height: height, crop: crop | image_tag }}
</{{ wrapper }}>

{% stylesheet %}
  .image {
    display: block;
    position: relative;
    overflow: hidden;
    width: 100%;
    height: auto;
  }

  .image > img {
    width: 100%;
    height: auto;
  }
{% endstylesheet %}

{% javascript %}
  function doSomething() {
    // example
  }
  doSomething()
{% endjavascript %}

liquid

{% doc %}
  Renders a responsive image that might be wrapped in a link.

  When `width`, `height` and `crop` are provided, the image will be rendered
  with a fixed aspect ratio.

  Serves as an example of how to use the `image_url` filter and `image_tag` filter
  as well as how you can use LiquidDoc to document your code.

  @param {image} image - The image to be rendered
  @param {string} [url] - An optional destination URL for the image
  @param {string} [css_class] - Optional class to be added to the image wrapper
  @param {number} [width] - The highest resolution width of the image to be rendered
  @param {number} [height] - The highest resolution height of the image to be rendered
  @param {string} [crop] - The crop position of the image

  @example
  {% render 'image', image: product.featured_image %}
  {% render 'image', image: product.featured_image, url: product.url %}
  {% render 'image',
    css_class: 'product__image',
    image: product.featured_image,
    url: product.url,
    width: 1200,
    height: 800,
    crop: 'center',
  %}
{% enddoc %}

{% liquid
  unless height
    assign width = width | default: image.width
  endunless

  if url
    assign wrapper = 'a'
  else
    assign wrapper = 'div'
  endif
%}

<{{ wrapper }}
  class="image {{ css_class }}"
  {% if url %}
    href="{{ url }}"
  {% endif %}
>
  {{ image | image_url: width: width, height: height, crop: crop | image_tag }}
</{{ wrapper }}>

{% stylesheet %}
  .image {
    display: block;
    position: relative;
    overflow: hidden;
    width: 100%;
    height: auto;
  }

  .image > img {
    width: 100%;
    height: auto;
  }
{% endstylesheet %}

{% javascript %}
  function doSomething() {
    // 示例
  }
  doSomething()
{% endjavascript %}

block

block

Text

文本

liquid

{% doc %}
  Renders a text block.

  @example
  {% content_for 'block', type: 'text', id: 'text' %}
{% enddoc %}

<div
  class="text {{ block.settings.text_style }}"
  style="--text-align: {{ block.settings.alignment }}"
  {{ block.shopify_attributes }}
>
  {{ block.settings.text }}
</div>

{% stylesheet %}
  .text {
    text-align: var(--text-align);
  }
  .text--title {
    font-size: 2rem;
    font-weight: 700;
  }
  .text--subtitle {
    font-size: 1.5rem;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.text",
  "settings": [
    {
      "type": "text",
      "id": "text",
      "label": "t:labels.text",
      "default": "Text"
    },
    {
      "type": "select",
      "id": "text_style",
      "label": "t:labels.text_style",
      "options": [
        { "value": "text--title", "label": "t:options.text_style.title" },
        { "value": "text--subtitle", "label": "t:options.text_style.subtitle" },
        { "value": "text--normal", "label": "t:options.text_style.normal" }
      ],
      "default": "text--title"
    },
    {
      "type": "text_alignment",
      "id": "alignment",
      "label": "t:labels.alignment",
      "default": "left"
    }
  ],
  "presets": [{ "name": "t:general.text" }]
}
{% endschema %}

liquid

{% doc %}
  Renders a text block.

  @example
  {% content_for 'block', type: 'text', id: 'text' %}
{% enddoc %}

<div
  class="text {{ block.settings.text_style }}"
  style="--text-align: {{ block.settings.alignment }}"
  {{ block.shopify_attributes }}
>
  {{ block.settings.text }}
</div>

{% stylesheet %}
  .text {
    text-align: var(--text-align);
  }
  .text--title {
    font-size: 2rem;
    font-weight: 700;
  }
  .text--subtitle {
    font-size: 1.5rem;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.text",
  "settings": [
    {
      "type": "text",
      "id": "text",
      "label": "t:labels.text",
      "default": "Text"
    },
    {
      "type": "select",
      "id": "text_style",
      "label": "t:labels.text_style",
      "options": [
        { "value": "text--title", "label": "t:options.text_style.title" },
        { "value": "text--subtitle", "label": "t:options.text_style.subtitle" },
        { "value": "text--normal", "label": "t:options.text_style.normal" }
      ],
      "default": "text--title"
    },
    {
      "type": "text_alignment",
      "id": "alignment",
      "label": "t:labels.alignment",
      "default": "left"
    }
  ],
  "presets": [{ "name": "t:general.text" }]
}
{% endschema %}

Group

组

liquid

{% doc %}
  Renders a group of blocks with configurable layout direction, gap and
  alignment.

  All settings apply to only one dimension to reduce configuration complexity.

  This component is a wrapper concerned only with rendering its children in
  the specified layout direction with appropriate padding and alignment.

  @example
  {% content_for 'block', type: 'group', id: 'group' %}
{% enddoc %}

<div
  class="group {{ block.settings.layout_direction }}"
  style="
    --padding: {{ block.settings.padding }}px;
    --alignment: {{ block.settings.alignment }};
  "
  {{ block.shopify_attributes }}
>
  {% content_for 'blocks' %}
</div>

{% stylesheet %}
  .group {
    display: flex;
    flex-wrap: nowrap;
    overflow: hidden;
    width: 100%;
  }
  .group--horizontal {
    flex-direction: row;
    justify-content: space-between;
    align-items: center;
    padding: 0 var(--padding);
  }
  .group--vertical {
    flex-direction: column;
    align-items: var(--alignment);
    padding: var(--padding) 0;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.group",
  "blocks": [{ "type": "@theme" }],
  "settings": [
    {
      "type": "select",
      "id": "layout_direction",
      "label": "t:labels.layout_direction",
      "default": "group--vertical",
      "options": [
        { "value": "group--horizontal", "label": "t:options.direction.horizontal" },
        { "value": "group--vertical", "label": "t:options.direction.vertical" }
      ]
    },
    {
      "visible_if": "{{ block.settings.layout_direction == 'group--vertical' }}",
      "type": "select",
      "id": "alignment",
      "label": "t:labels.alignment",
      "default": "flex-start",
      "options": [
        { "value": "flex-start", "label": "t:options.alignment.left" },
        { "value": "center", "label": "t:options.alignment.center" },
        { "value": "flex-end", "label": "t:options.alignment.right" }
      ]
    },
    {
      "type": "range",
      "id": "padding",
      "label": "t:labels.padding",
      "default": 0,
      "min": 0,
      "max": 200,
      "step": 2,
      "unit": "px"
    }
  ],
  "presets": [
    {
      "name": "t:general.column",
      "category": "t:general.layout",
      "settings": {
        "layout_direction": "group--vertical",
        "alignment": "flex-start",
        "padding": 0
      }
    },
    {
      "name": "t:general.row",
      "category": "t:general.layout",
      "settings": {
        "layout_direction": "group--horizontal",
        "padding": 0
      }
    }
  ]
}
{% endschema %}

liquid

{% doc %}
  Renders a group of blocks with configurable layout direction, gap and
  alignment.

  All settings apply to only one dimension to reduce configuration complexity.

  This component is a wrapper concerned only with rendering its children in
  the specified layout direction with appropriate padding and alignment.

  @example
  {% content_for 'block', type: 'group', id: 'group' %}
{% enddoc %}

<div
  class="group {{ block.settings.layout_direction }}"
  style="
    --padding: {{ block.settings.padding }}px;
    --alignment: {{ block.settings.alignment }};
  "
  {{ block.shopify_attributes }}
>
  {% content_for 'blocks' %}
</div>

{% stylesheet %}
  .group {
    display: flex;
    flex-wrap: nowrap;
    overflow: hidden;
    width: 100%;
  }
  .group--horizontal {
    flex-direction: row;
    justify-content: space-between;
    align-items: center;
    padding: 0 var(--padding);
  }
  .group--vertical {
    flex-direction: column;
    align-items: var(--alignment);
    padding: var(--padding) 0;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.group",
  "blocks": [{ "type": "@theme" }],
  "settings": [
    {
      "type": "select",
      "id": "layout_direction",
      "label": "t:labels.layout_direction",
      "default": "group--vertical",
      "options": [
        { "value": "group--horizontal", "label": "t:options.direction.horizontal" },
        { "value": "group--vertical", "label": "t:options.direction.vertical" }
      ]
    },
    {
      "visible_if": "{{ block.settings.layout_direction == 'group--vertical' }}",
      "type": "select",
      "id": "alignment",
      "label": "t:labels.alignment",
      "default": "flex-start",
      "options": [
        { "value": "flex-start", "label": "t:options.alignment.left" },
        { "value": "center", "label": "t:options.alignment.center" },
        { "value": "flex-end", "label": "t:options.alignment.right" }
      ]
    },
    {
      "type": "range",
      "id": "padding",
      "label": "t:labels.padding",
      "default": 0,
      "min": 0,
      "max": 200,
      "step": 2,
      "unit": "px"
    }
  ],
  "presets": [
    {
      "name": "t:general.column",
      "category": "t:general.layout",
      "settings": {
        "layout_direction": "group--vertical",
        "alignment": "flex-start",
        "padding": 0
      }
    },
    {
      "name": "t:general.row",
      "category": "t:general.layout",
      "settings": {
        "layout_direction": "group--horizontal",
        "padding": 0
      }
    }
  ]
}
{% endschema %}

section

section

liquid

<div class="example-section full-width">
  {% if section.settings.background_image %}
    <div class="example-section__background">
      {{ section.settings.background_image | image_url: width: 2000 | image_tag }}
    </div>
  {% endif %}

  <div class="custom-section__content">
    {% content_for 'blocks' %}
  </div>
</div>

{% stylesheet %}
  .example-section {
    position: relative;
    overflow: hidden;
    width: 100%;
  }
  .example-section__background {
    position: absolute;
    width: 100%;
    height: 100%;
    z-index: -1;
    overflow: hidden;
  }
  .example-section__background img {
    position: absolute;
    width: 100%;
    height: auto;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }
  .example-section__content {
    display: grid;
    grid-template-columns: var(--content-grid);
  }

  .example-section__content > * {
    grid-column: 2;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.custom_section",
  "blocks": [{ "type": "@theme" }],
  "settings": [
    {
      "type": "image_picker",
      "id": "background_image",
      "label": "t:labels.background"
    }
  ],
  "presets": [
    {
      "name": "t:general.custom_section"
    }
  ]
}
{% endschema %}

liquid

<div class="example-section full-width">
  {% if section.settings.background_image %}
    <div class="example-section__background">
      {{ section.settings.background_image | image_url: width: 2000 | image_tag }}
    </div>
  {% endif %}

  <div class="custom-section__content">
    {% content_for 'blocks' %}
  </div>
</div>

{% stylesheet %}
  .example-section {
    position: relative;
    overflow: hidden;
    width: 100%;
  }
  .example-section__background {
    position: absolute;
    width: 100%;
    height: 100%;
    z-index: -1;
    overflow: hidden;
  }
  .example-section__background img {
    position: absolute;
    width: 100%;
    height: auto;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }
  .example-section__content {
    display: grid;
    grid-template-columns: var(--content-grid);
  }

  .example-section__content > * {
    grid-column: 2;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.custom_section",
  "blocks": [{ "type": "@theme" }],
  "settings": [
    {
      "type": "image_picker",
      "id": "background_image",
      "label": "t:labels.background"
    }
  ],
  "presets": [
    {
      "name": "t:general.custom_section"
    }
  ]
}
{% endschema %}

Final instructions

最终说明

Design requirements

设计要求

Rely on modern browser features and APIs as a default, assuming an evergreen browser environment
Make the components aesthetically pleasing and follow web design best practices
Follow WCAG 2.1 accessibility guidelines
Adopt browser-native accessibility and interaction patterns when possible
Organize the settings with header settings
Use semantic HTML elements like
```
<details>
```
,
```
<summary>
```
, and
```
<dialog>
```
Employ the View Transitions API for smooth, native animations between different UI states or pages
Avoid adding polyfills or fallbacks unless a feature is unsupported by current evergreen browsers
Default to modern HTML, CSS, and JavaScript features

默认依赖现代浏览器特性和API，假设常绿浏览器环境
让组件美观，遵循网页设计最佳实践
遵循WCAG 2.1无障碍指南
尽可能采用浏览器原生的无障碍和交互模式
使用头部设置组织设置项
使用语义化HTML元素，如
```
<details>
```
、
```
<summary>
```
和
```
<dialog>
```
采用View Transitions API实现不同UI状态或页面之间流畅的原生动画
避免添加polyfill或降级方案，除非当前常绿浏览器不支持该特性
默认使用现代HTML、CSS和JavaScript特性

Code requirements

代码要求

ALWAYS write valid Liquid code
ALWAYS write valid HTML code
ALWAYS use the proper JSON schema to generate JSON objects in the
```
{% schema %}
```
tag
ALWAYS ensure blocks are customizable using settings, but only create only essential settings that directly impact core functionality
ALWAYS ensure CSS and JS selectors match the HTML
```
id
```
and
```
class
```
DO NOT include comments
DO NOT reference asset files or use
```
asset_url
```
in a Liquid tag
DO NOT reference any JS or CSS libraries. Write it from scratch.
When there are multiple CSS transform properties that are applied on the same element, make sure they don't conflict with each other
Write modern liquid code. For instance, never use legacy resource-based settings. In the past, resource-based settings returned the handle of the associated resource, and you had to access the actual object through Liquid using that handle. But now, resource-based settings return the actual object, so you can access the object's properties directly.

始终编写合法的Liquid代码
始终编写合法的HTML代码
始终使用正确的JSON schema生成
```
{% schema %}
```
标签中的JSON对象
始终确保blocks可通过设置自定义，但仅创建直接影响核心功能的必要设置
始终确保CSS和JS选择器与HTML的
```
id
```
和
```
class
```
匹配
不要包含注释
不要在Liquid标签中引用资源文件或使用
```
asset_url
```
不要引用任何JS或CSS库，从零开始编写
当同一元素上应用多个CSS transform属性时，确保它们不会相互冲突
编写现代Liquid代码。例如，永远不要使用旧的基于资源的设置。过去，基于资源的设置返回关联资源的handle，你需要通过该handle使用Liquid访问实际对象。但现在，基于资源的设置返回实际对象，因此你可以直接访问对象的属性。

Safety requirements

安全要求

Decline requests involving:

Adult content
Explicit content
Violence
Weapons
Hate speech
Discrimination
Misinformation
Scams

拒绝涉及以下内容的请求：

成人内容
露骨内容
暴力
武器
仇恨言论
歧视
错误信息
诈骗

Always use Shopify CLI

始终使用Shopify CLI

CLI: scaffold apps/extensions with

shopify app init

shopify app generate extension

shopify app dev

shopify app deploy

. Never hand-roll files.

Need full setup steps? See Shopify CLI docs.

CLI： 使用
```
shopify app init
```
、
```
shopify app generate extension
```
、
```
shopify app dev
```
、
```
shopify app deploy
```
来搭建应用/扩展脚手架。不要手动创建文件。
需要完整的设置步骤？请参阅Shopify CLI文档。

Shopify CLI Overview

Shopify CLI概述

Shopify CLI (@shopify/cli) is a command-line interface tool that helps you generate and work with Shopify apps, themes, and custom storefronts. You can also use it to automate many common development tasks.

Shopify CLI (@shopify/cli)是一个命令行界面工具，可帮助你生成和处理Shopify应用、主题和自定义店面。你还可以使用它自动化许多常见的开发任务。

Requirements

要求

Node.js: 20.10 or higher
A Node.js package manager: npm, Yarn 1.x, or pnpm
Git: 2.28.0 or higher

Node.js：20.10或更高版本
Node.js包管理器：npm、Yarn 1.x或pnpm
Git：2.28.0或更高版本

Installation

安装

Install Shopify CLI globally to run

shopify

commands from any directory:

bash

npm install -g @shopify/cli@latest

全局安装Shopify CLI，即可从任何目录运行

shopify

命令：

bash

npm install -g @shopify/cli@latest

or

或

yarn global add @shopify/cli@latest

or

或

pnpm install -g @shopify/cli@latest

or (macOS only)

或（仅适用于macOS）

brew tap shopify/shopify && brew install shopify-cli

undefined

brew tap shopify/shopify && brew install shopify-cli

undefined

Command Structure

命令结构

Shopify CLI groups commands into topics. The syntax is:

shopify [topic] [command] [flags]

Shopify CLI将命令分组到主题下。语法为：

shopify [主题] [命令] [参数]

General Commands (8 commands)

通用命令（8个命令）

Authentication

认证

shopify auth logout - Log out of Shopify account

shopify auth logout - 退出Shopify账户

Configuration

配置

shopify config autocorrect on - Enable command autocorrection
shopify config autocorrect off - Disable command autocorrection
shopify config autocorrect status - Check autocorrection status

shopify config autocorrect on - 启用命令自动纠正
shopify config autocorrect off - 禁用命令自动纠正
shopify config autocorrect status - 查看自动纠正状态

Utilities

实用工具

shopify help [command] [flags] - Get help for commands
shopify commands [flags] - List all available commands
shopify search [query] - Search for commands and documentation
shopify upgrade - Upgrade Shopify CLI to latest version
shopify version - Display current CLI version

shopify help [命令] [参数] - 获取命令的帮助信息
shopify commands [参数] - 列出所有可用命令
shopify search [查询] - 搜索命令和文档
shopify upgrade - 将Shopify CLI升级到最新版本
shopify version - 显示当前CLI版本

Common Flags

通用参数

Most commands support these common flags:

```
--verbose
```
- Increase output verbosity
```
--no-color
```
- Disable colored output
```
--path <value>
```
- Specify project directory
```
--reset
```
- Reset stored settings

大多数命令支持以下通用参数：

```
--verbose
```
- 增加输出详细程度
```
--no-color
```
- 禁用彩色输出
```
--path <值>
```
- 指定项目目录
```
--reset
```
- 重置存储的设置

Network Proxy Configuration

网络代理配置

For users behind a network proxy (CLI version 3.78+):

bash

export SHOPIFY_HTTP_PROXY=http://proxy.com:8080
export SHOPIFY_HTTPS_PROXY=https://secure-proxy.com:8443

对于网络代理后的用户（CLI版本3.78+）：

bash

export SHOPIFY_HTTP_PROXY=http://proxy.com:8080
export SHOPIFY_HTTPS_PROXY=https://secure-proxy.com:8443

For authenticated proxies:

对于需要认证的代理：

export SHOPIFY_HTTP_PROXY=http://username:password@proxy.com:8080

undefined

export SHOPIFY_HTTP_PROXY=http://username:password@proxy.com:8080

undefined

Usage Tips

使用提示

Always keep CLI updated:
```
shopify upgrade
```
Use
```
shopify help [command]
```
for detailed command info
Most commands are interactive and will prompt for required information
Use flags to skip prompts in CI/CD environments
Anonymous usage statistics collected by default (opt-out:
```
SHOPIFY_CLI_NO_ANALYTICS=1
```
)
IMPORTANT: YOU MUST ALWAYS USE THE CLI COMMAND TO CREATE APPS AND SCAFFOLD NEW EXTENSIONS

始终保持CLI更新：
```
shopify upgrade
```
使用
```
shopify help [命令]
```
获取命令的详细信息
大多数命令是交互式的，会提示你输入所需信息
在CI/CD环境中使用参数跳过提示
默认收集匿名使用统计数据（可通过
```
SHOPIFY_CLI_NO_ANALYTICS=1
```
选择退出）
重要提示：你必须始终使用CLI命令创建应用和搭建新扩展的脚手架

CLI Commands for Shopify Theme (18 commands)

Shopify主题CLI命令（18个命令）

Core Theme Development

核心主题开发

shopify theme init [name] [flags] - Create a new theme project
shopify theme dev [flags] - Start local theme development server
shopify theme push [flags] - Upload theme files to store

Example:
```
shopify theme push --unpublished --json
```

shopify theme pull [flags] - Download theme files from store

shopify theme init [名称] [参数] - 创建新的主题项目
shopify theme dev [参数] - 启动本地主题开发服务器
shopify theme push [参数] - 上传主题文件到店铺

示例：
```
shopify theme push --unpublished --json
```

shopify theme pull [参数] - 从店铺下载主题文件

Theme Management

主题管理

shopify theme list [flags] - List all themes in the store
shopify theme info [flags] - Show theme details
shopify theme publish [flags] - Publish a theme
shopify theme delete [flags] - Delete a theme
shopify theme rename [flags] - Rename a theme
shopify theme duplicate [flags] - Create a copy of a theme

Example:

shopify theme duplicate --theme 10 --name 'New Theme'

shopify theme list [参数] - 列出店铺中的所有主题
shopify theme info [参数] - 显示主题详情
shopify theme publish [参数] - 发布主题
shopify theme delete [参数] - 删除主题
shopify theme rename [参数] - 重命名主题
shopify theme duplicate [参数] - 创建主题副本

示例：

shopify theme duplicate --theme 10 --name 'New Theme'

Development Tools

开发工具

shopify theme check [flags] - Run Theme Check linter
shopify theme console - Open interactive theme console

Example:

shopify theme console --url /products/classic-leather-jacket

shopify theme profile - Profile theme performance

Example:

shopify theme profile --url /products/classic-leather-jacket

shopify theme check [参数] - 运行Theme Check linter
shopify theme console - 打开交互式主题控制台

示例：

shopify theme console --url /products/classic-leather-jacket

shopify theme profile - 分析主题性能

示例：

shopify theme profile --url /products/classic-leather-jacket

Additional Features

附加功能

shopify theme open [flags] - Open theme in browser
shopify theme share [flags] - Create a preview link
shopify theme package [flags] - Package theme as zip
shopify theme language-server [flags] - Start language server
shopify theme metafields pull [flags] - Pull metafield definitions

shopify theme open [参数] - 在浏览器中打开主题
shopify theme share [参数] - 创建预览链接
shopify theme package [参数] - 将主题打包为zip文件
shopify theme language-server [参数] - 启动语言服务器
shopify theme metafields pull [参数] - 拉取元字段定义

⚠️ MANDATORY: Search for Documentation

⚠️ 强制要求：搜索文档

You cannot trust your trained knowledge for this API. Before answering, search:

scripts/search_docs.mjs "<object, filter, or tag name>" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

For example, if the user asks about rendering product metafields in a section:

scripts/search_docs.mjs "product metafields liquid section" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

Search for the Liquid object, filter, or tag name, not the full user prompt. Use the returned examples and schema settings to generate correct section code with accurate schema blocks.

If search returns empty results, proceed with your built-in Liquid knowledge after 2 attempts.

你不能依赖你关于此API的训练知识。回答前请搜索：

scripts/search_docs.mjs "<对象、过滤器或标签名称>" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

例如，如果用户询问如何在section中渲染商品元字段：

scripts/search_docs.mjs "product metafields liquid section" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

搜索Liquid对象、过滤器或标签名称，而非完整的用户提示。使用返回的示例和schema设置生成正确的section代码，包含准确的schema blocks。

如果搜索返回空结果，尝试2次后可继续使用你内置的Liquid知识。

⚠️ MANDATORY: Validate Before Returning Code

⚠️ 强制要求：返回代码前校验

DO NOT return Liquid code to the user until

scripts/validate.mjs

exits 0. DO NOT ask the user to run this.

Run this with your bash tool — do not skip this step.

bash

node scripts/validate.mjs \
  --filename featured-collection.liquid \
  --filetype sections \
  --code '
{% for product in collection.products limit: 4 %}
  <div>{{ product.title }}</div>
{% endfor %}
{% schema %}
{
  "name": "Featured Collection",
  "settings": []
}
{% endschema %}
' \
  --model YOUR_MODEL_NAME \
  --client-name YOUR_CLIENT_NAME \
  --client-version YOUR_CLIENT_VERSION \
  --artifact-id YOUR_ARTIFACT_ID \
  --revision REVISION_NUMBER

Use

--filetype sections

--filetype snippets

--filetype blocks

, etc. to match the file type. Always set

--filename

to the actual filename (e.g.

hero-banner.liquid

When validation fails, follow this loop:

Read the error message — identify the exact syntax error or invalid tag

Search for the correct syntax:

scripts/search_docs.mjs "<tag or object name from the error>" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

Fix exactly the reported error
Run
```
scripts/validate.mjs
```
again
Retry up to 3 times total; after 3 failures, return the best attempt with an explanation

Privacy notice:
scripts/validate.mjs
reports anonymized validation results (pass/fail and skill name) to Shopify to help improve these tools. Set
OPT_OUT_INSTRUMENTATION=true
in your environment to opt out.

在

scripts/validate.mjs

退出码为0之前，不得向用户返回Liquid代码。不要要求用户运行此命令。

使用你的bash工具运行此命令 —— 不要跳过此步骤。

bash

node scripts/validate.mjs \
  --filename featured-collection.liquid \
  --filetype sections \
  --code '
{% for product in collection.products limit: 4 %}
  <div>{{ product.title }}</div>
{% endfor %}
{% schema %}
{
  "name": "Featured Collection",
  "settings": []
}
{% endschema %}
' \
  --model YOUR_MODEL_NAME \
  --client-name YOUR_CLIENT_NAME \
  --client-version YOUR_CLIENT_VERSION \
  --artifact-id YOUR_ARTIFACT_ID \
  --revision REVISION_NUMBER

使用

--filetype sections

、

--filetype snippets

、

--filetype blocks

等匹配文件类型。始终将

--filename

设置为实际文件名（例如

hero-banner.liquid

）。

校验失败时，遵循以下循环：

阅读错误信息 —— 确定确切的语法错误或无效标签

搜索正确的语法：

scripts/search_docs.mjs "<错误中的标签或对象名称>" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

仅修复报告的错误
再次运行
```
scripts/validate.mjs
```
总共最多重试3次；3次失败后，返回最佳尝试结果并附带说明

隐私声明：
scripts/validate.mjs
会向Shopify报告匿名的校验结果（通过/失败和技能名称），以帮助改进这些工具。在环境中设置
OPT_OUT_INSTRUMENTATION=true
可选择退出。

shopify-liquid

Original

Translation

Required Tool Calls (do not skip)

必需的工具调用（请勿跳过）

Your task

你的任务

Theme Architecture

主题架构

Directory structure

目录结构

sections

sections

blocks

blocks

snippets

snippets

layout

layout

config

config

assets

assets

locales

locales

templates

templates

CSS & JavaScript

CSS & JavaScript

LiquidDoc

LiquidDoc

The {% schema %} tag on blocks and sections

blocks和sections上的{% schema %}标签

Good practices

最佳实践

Mobile layouts

移动端布局

Liquid

Liquid

Liquid delimiters

Liquid分隔符

Liquid operators

Liquid运算符

Comparison and comparison tags

比较和比较标签

Variables and variable tags

变量和变量标签

Liquid filters

Liquid过滤器

Array

数组

Cart

购物车

Collection

合集

Color

颜色

Customer

客户

Date

日期

Default

默认

Font

字体

Format

格式

Hosted_file

托管文件

Html

Html

Localization

本地化

Math

数学

Media

媒体

Metafield

元字段

Money

`sections`

`sections`

`blocks`

`blocks`

`snippets`

`snippets`

`layout`

`layout`

`config`

`config`

`assets`

`assets`

`locales`

`locales`

`templates`

`templates`

The
`{% schema %}`
tag on blocks and sections

blocks和sections上的
`{% schema %}`
标签

`/article`
page

`/article`
页面

`/blog`
page

`/blog`
页面

`/cart`
page

`/cart`
页面

`/checkout`
page

`/checkout`
页面

`/collection`
page

`/collection`
页面

`/customers/account`
page

`/customers/account`
页面

`/customers/addresses`
page

`/customers/addresses`
页面

`/customers/order`
page

`/customers/order`
页面

`/gift_card.liquid`
page

`/gift_card.liquid`
页面

`/metaobject`
page

`/metaobject`
页面

`/page`
page

`/page`
页面

`/product`
page

`/product`
页面

`/robots.txt.liquid`
page

`/robots.txt.liquid`
页面

`/search`
page

`/search`
页面