shopify-liquid-themes

Shopify Liquid 主题

主题架构

.
├── sections/    # Full-width page modules with {% schema %} — hero, product grid, testimonials
├── blocks/      # Nestable components with {% schema %} — slides, feature items, text blocks
├── snippets/    # Reusable fragments via {% render %} — buttons, icons, image helpers
├── layout/      # Page wrappers (must include {{ content_for_header }} and {{ content_for_layout }})
├── templates/   # JSON files defining which sections appear on each page type
├── config/      # Global theme settings (settings_schema.json, settings_data.json)
├── locales/     # Translation files (en.default.json, fr.json, etc.)
└── assets/      # Static CSS, JS, images (prefer {% stylesheet %}/{% javascript %} instead)

何时使用哪种组件

需求	使用	原因
全宽可自定义模块	Section	包含 {% schema %}，显示在编辑器中，可渲染区块
带有编辑器设置、可嵌套的小型组件	Block	包含 {% schema %}，可嵌套在 Section/Block 中
不可由商家编辑的可复用逻辑	Snippet	没有 schema，通过 {% render %} 渲染，可接收参数
多个区块/片段共用的逻辑	Snippet	Block 不能通过 {% render %} 渲染其他 Block

Liquid 语法

分隔符

• {{ ... }} — 输出（打印一个值）
• {{- ... -}} — 输出并去除空白
• {% ... %} — 逻辑标签（if、for、assign）— 不输出内容
• {%- ... -%} — 逻辑标签并去除空白

运算符

比较： ==、!=、>、<、>=、<= 逻辑： and、or、contains

重要注意事项

1. 条件中不能使用括号 — 请改用嵌套的 {% if %}
2. 不支持三元运算符 — 始终使用 {% if cond %}value{% else %}other{% endif %}
3. for 循环最多迭代 50 次 — 处理更大的数组时请使用 {% paginate %}
4. contains 仅适用于字符串 — 不能用于检查数组中的对象
5. {% stylesheet %}/{% javascript %} 不会渲染 Liquid — 其中不能包含 Liquid
6. Snippet 无法访问外部作用域中的变量 — 请将变量作为 render 参数传入
7. include 已弃用 — 始终使用 {% render 'snippet_name' %}
8. {% liquid %} 标签 — 无需分隔符即可编写多行逻辑；使用 echo 输出内容

变量

{% assign my_var = 'value' %}
{% capture my_var %}computed {{ value }}{% endcapture %}
{% increment counter %}
{% decrement counter %}

过滤器速查

过滤器通过 | 链接。一个过滤器的输出类型会作为下一个过滤器的输入。

数组： compact、concat、find、find_index、first、has、join、last、map、reject、reverse、size、sort、sort_natural、sum、uniq、where 字符串： append、capitalize、downcase、escape、handleize、lstrip、newline_to_br、prepend、remove、replace、rstrip、slice、split、strip、strip_html、truncate、truncatewords、upcase、url_decode、url_encode 数学： abs、at_least、at_most、ceil、divided_by、floor、minus、modulo、plus、round、times 金额： money、money_with_currency、money_without_currency、money_without_trailing_zeros 颜色： color_brightness、color_darken、color_lighten、color_mix、color_modify、color_saturate、color_desaturate、color_to_hex、color_to_hsl、color_to_rgb 媒体： image_url、image_tag、video_tag、external_video_tag、media_tag、model_viewer_tag URL： asset_url、asset_img_url、file_url、shopify_asset_url HTML： link_to、script_tag、stylesheet_tag、time_tag、placeholder_svg_tag 本地化： t（翻译）、format_address、currency_selector 其他： date、default、json、structured_data、font_face、font_url、payment_button

完整详情：语言过滤器、HTML/媒体过滤器、商务过滤器

标签速查

类别	标签
主题	content_for、layout、section、sections、schema、stylesheet、javascript、style
控制	if、elsif、else、unless、case、when
迭代	for、break、continue、cycle、tablerow、paginate
变量	assign、capture、increment、decrement、echo
HTML	form、render、raw、comment、liquid
文档	doc

含语法和参数的完整详情：references/tags.md

对象速查

全局对象（随处可用）

cart、collections、customer、localization、pages、request、routes、settings、shop、template、theme、linklists、images、blogs、articles、all_products、metaobjects、canonical_url、content_for_header、content_for_layout、page_title、page_description、handle、current_page

页面专属对象

模板	对象
/product	product、remote_product
/collection	collection、current_tags
/cart	cart
/article	article、blog
/blog	blog、current_tags
/page	page
/search	search
/customers/*	customer、order

完整参考：commerce objects、content objects、tier 2、tier 3

Schema 标签

Section 和 block 需要使用 {% schema %}，并提供有效的 JSON 对象。Section 使用 section.settings.*，block 使用 block.settings.*。

Section schema 结构

{
  "name": "t:sections.hero.name",
  "tag": "section",
  "class": "hero-section",
  "limit": 1,
  "settings": [],
  "max_blocks": 16,
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:sections.hero.name" }],
  "enabled_on": { "templates": ["index"] },
  "disabled_on": { "templates": ["password"] }
}

Block schema 结构

{
  "name": "t:blocks.slide.name",
  "tag": "div",
  "class": "slide",
  "settings": [],
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:blocks.slide.name" }]
}

设置类型决策表

需求	设置类型	关键字段
开/关切换	checkbox	default: true/false
短文本	text	placeholder
长文本	textarea	placeholder
富文本（带 <p>）	richtext	—
行内富文本（不带 <p>）	inline_richtext	—
数字输入	number	placeholder
滑块	range	min、max、default（均为必填）、step、unit
下拉菜单/分段选项	select	options: [{value, label}]
单选按钮	radio	options: [{value, label}]
文本对齐方式	text_alignment	default: "left"/"center"/"right"
颜色选择器	color	default: "#000000"
图片上传	image_picker	—
视频上传	video	—
外部视频 URL	video_url	accept: ["youtube", "vimeo"]
产品选择器	product	—
系列选择器	collection	—
页面选择器	page	—
博客选择器	blog	—
文章选择器	article	—
URL 输入	url	—
菜单选择器	link_list	—
字体选择器	font_picker	default（必填）
编辑器标题	header	content（无需 id）
编辑器说明	paragraph	content（无需 id）

visible_if 模式

{
  "visible_if": "{{ block.settings.layout == 'vertical' }}",
  "type": "select",
  "id": "alignment",
  "label": "t:labels.alignment",
  "options": [...]
}

根据其他设置的值，在编辑器中有条件地显示或隐藏设置。

Block 条目类型

• { "type": "@theme" } — 接受任意主题 block
• { "type": "@app" } — 接受应用 block
• { "type": "slide" } — 仅接受 slide block 类型

完整的 schema 详情和全部 33 种设置类型：references/schema-and-settings.md

CSS 和 JavaScript

组件级样式和脚本

在 section、block 和 snippet 中使用 {% stylesheet %} 和 {% javascript %}：

{% stylesheet %}
  .my-component { display: flex; }
{% endstylesheet %}

{% javascript %}
  console.log('loaded');
{% endjavascript %}

• 每个文件各用一个标签 — 多个 {% stylesheet %} 标签会导致错误
• 不能包含 Liquid — 这些标签不会处理 Liquid；请改用 CSS 变量或类
• 仅支持 sections/、blocks/ 和 snippets/

{% style %} 标签（支持 Liquid 的 CSS）

适用于需要 Liquid 的动态 CSS（例如，在编辑器中实时更新的颜色设置）：

{% style %}
  .section-{{ section.id }} {
    background: {{ section.settings.bg_color }};
  }
{% endstyle %}

设置的 CSS 模式

单个 CSS 属性 — 使用 CSS 变量：

<div style="--gap: {{ block.settings.gap }}px">

多个 CSS 属性 — 使用 CSS 类作为选择值：

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

LiquidDoc（{% doc %}）

必需用于： snippet（始终需要）、block（通过 {% content_for 'block' %} 静态渲染时需要）

{% doc %}
  Brief description of what this file renders.

  @param {type} name - Description of required parameter
  @param {type} [name] - Description of optional parameter (brackets = optional)

  @example
  {% render 'snippet-name', name: value %}
{% enddoc %}

参数类型： string、number、boolean、image、object、array

翻译

所有面向用户的字符串都必须使用 t 过滤器

<h2>{{ 'sections.hero.heading' | t }}</h2>
<button>{{ 'products.add_to_cart' | t }}</button>


<h2>Welcome to our store</h2>

变量插值

{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}

语言环境文件：

{
  "products": {
    "price_range": "From {{ min }} to {{ max }}"
  }
}

语言环境文件结构

locales/
├── en.default.json          # English translations (required)
├── en.default.schema.json   # Editor setting translations (required)
├── fr.json                  # French translations
└── fr.schema.json           # French editor translations

键命名约定

• 使用 snake_case 和 分层键（最多 3 层）
• 所有文本使用 句子式大小写（仅首词首字母大写）
• 架构标签使用 t: 前缀："label": "t:labels.heading"
• 按组件分组：sections.hero.heading、blocks.slide.title

参考资料

• 筛选器：语言（77）、HTML/媒体（45）、商务（30）
• 标签参考（30 个标签）
• 对象：商务（5）、内容（10）、第 2 层（69）、第 3 层（53）
• 架构与设置参考（33 种类型）
• 完整示例（代码片段、块、分区）