Back to Details

shopify-liquid-templates

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify Liquid Templates

Shopify Liquid 模板

Best practices for Liquid templates, snippets, logic flow, image handling, and SVG usage in Shopify themes.
Shopify主题中Liquid模板、代码片段、逻辑流程、图片管理及SVG使用的最佳实践。

When to Use

适用场景

  • Creating or modifying Liquid templates
  • Working with snippets
  • Handling images and media
  • Writing Liquid logic
  • Using SVG icons
  • 创建或修改Liquid模板
  • 代码片段开发
  • 图片与媒体资源管理
  • 编写Liquid逻辑
  • 使用SVG图标

Snippets

代码片段

Usage

使用规范

  • Use 
    {% render %}
    only (never 
    include
    )
  • Inside each snippet, add a Usage block at the top
  • 仅使用
    {% render %}
    标签（禁止使用
    include
    ）
  • 在每个代码片段顶部添加使用说明块

Snippet Structure

代码片段结构

liquid
{%- comment -%}
Usage:
{% render 'snippet-name', param: value, another_param: value %}
{%- endcomment -%}

<div class="snippet-name">
  {{ param }}
</div>
liquid
{%- comment -%}
Usage:
{% render 'snippet-name', param: value, another_param: value %}
{%- endcomment -%}

<div class="snippet-name">
  {{ param }}
</div>

Snippet Parameters

代码片段参数

Pass data to snippets via parameters:
liquid
{% render 'product-card', 
  product: product, 
  show_price: true, 
  image_size: 'large' %}
通过参数向代码片段传递数据：
liquid
{% render 'product-card', 
  product: product, 
  show_price: true, 
  image_size: 'large' %}

Why 
render
Instead of 
include

为何使用
render
而非
include

  • render
    is more performant
  • Better variable scoping
  • Recommended by Shopify
  • render
    性能更优
  • 变量作用域管理更完善
  • 为Shopify官方推荐用法

Liquid Logic

Liquid逻辑

Use 
{% liquid %}
Tag

使用
{% liquid %}
标签

For long or complex logic, use the 
{% liquid %}
tag:
liquid
{% liquid
  assign discount = product.compare_at_price | minus: product.price
  assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
  if discount_percent > 20
    assign is_big_discount = true
  endif
%}
针对冗长或复杂的逻辑，使用
{% liquid %}
标签：
liquid
{% liquid
  assign discount = product.compare_at_price | minus: product.price
  assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
  if discount_percent > 20
    assign is_big_discount = true
  endif
%}

Logic Best Practices

逻辑编写最佳实践

  • Avoid deeply nested conditionals
  • Prefer readable, linear logic
  • Break complex logic into multiple 
    liquid
    blocks if needed
  • Use meaningful variable names
  • 避免深层嵌套条件判断
  • 优先采用可读性强的线性逻辑
  • 若有需要，将复杂逻辑拆分为多个
    liquid
    块
  • 使用具备明确含义的变量名

Example: Clean Logic Flow

示例：清晰的逻辑流程

liquid
{% liquid
  if product.available
    assign button_text = 'Add to Cart'
    assign button_class = 'btn--primary'
  else
    assign button_text = 'Sold Out'
    assign button_class = 'btn--disabled'
  endif
%}

<button class="{{ button_class }}">
  {{ button_text }}
</button>
liquid
{% liquid
  if product.available
    assign button_text = 'Add to Cart'
    assign button_class = 'btn--primary'
  else
    assign button_text = 'Sold Out'
    assign button_class = 'btn--disabled'
  endif
%}

<button class="{{ button_class }}">
  {{ button_text }}
</button>

Images

图片管理

Always Use 
image_tag

始终使用
image_tag

  • Always use 
    image_tag
    filter
  • Use responsive 
    srcset
    and sizes
  • Do NOT hardcode 
    <img>
    tags
  • 务必使用
    image_tag
    过滤器
  • 采用响应式
    srcset
    与sizes属性
  • 禁止硬编码
    <img>
    标签

Image Tag Syntax

图片标签语法

liquid
{{ image | image_tag: widths: '360, 720, 1080', loading: 'lazy' }}
liquid
{{ image | image_tag: widths: '360, 720, 1080', loading: 'lazy' }}

Responsive Images

响应式图片示例

liquid
{% assign image_widths = '360, 540, 720, 900, 1080, 1296, 1512, 1728, 1944, 2160' %}

{{ product.featured_image | image_tag: 
  widths: image_widths,
  sizes: '(min-width: 1200px) 50vw, 100vw',
  loading: 'lazy',
  alt: product.featured_image.alt | escape }}
liquid
{% assign image_widths = '360, 540, 720, 900, 1080, 1296, 1512, 1728, 1944, 2160' %}

{{ product.featured_image | image_tag: 
  widths: image_widths,
  sizes: '(min-width: 1200px) 50vw, 100vw',
  loading: 'lazy',
  alt: product.featured_image.alt | escape }}

Image Settings

图片设置参数

Common 
image_tag
parameters:
  • widths
    : Comma-separated list of widths for srcset
  • sizes
    : Sizes attribute for responsive images
  • loading
    : 'lazy' or 'eager'
  • alt
    : Alt text (use 
    | escape
    filter)
image_tag
常用参数：
  • widths
    : 用于srcset的逗号分隔宽度列表
  • sizes
    : 响应式图片的sizes属性
  • loading
    : 'lazy'（懒加载）或'eager'（立即加载）
  • alt
    : 替代文本（需使用
    | escape
    过滤器）

SVG Files

SVG文件

Inline SVGs

内联SVG

Inline SVGs using the 
inline_asset_content
filter:
liquid
{{ 'icon-arrow.svg' | inline_asset_content }}
使用
inline_asset_content
过滤器实现SVG内联：
liquid
{{ 'icon-arrow.svg' | inline_asset_content }}

Do NOT Paste Raw SVG

禁止粘贴原始SVG代码

  • Do NOT paste raw SVG markup into templates
  • Store SVG files in 
    assets/
    directory
  • Use 
    inline_asset_content
    filter to include them
  • 禁止将原始SVG标记直接粘贴到模板中
  • 将SVG文件存储在
    assets/
    目录下
  • 使用
    inline_asset_content
    过滤器引入SVG

SVG Example

SVG示例

liquid
<button class="icon-button">
  {{ 'icon-close.svg' | inline_asset_content }}
  <span class="visually-hidden">Close</span>
</button>
liquid
<button class="icon-button">
  {{ 'icon-close.svg' | inline_asset_content }}
  <span class="visually-hidden">Close</span>
</button>

SVG Styling

SVG样式设置

SVGs can be styled with CSS when inlined:
css
.icon-button svg {
  width: 24px;
  height: 24px;
  fill: currentColor;
}
内联后的SVG可通过CSS设置样式：
css
.icon-button svg {
  width: 24px;
  height: 24px;
  fill: currentColor;
}

Shopify Theme Documentation

Shopify主题官方文档

Reference these official Shopify resources:
参考以下Shopify官方资源：

Common Liquid Patterns

常见Liquid模式

Product Card Snippet

产品卡片代码片段

liquid
{%- comment -%}
Usage:
{% render 'product-card', product: product, show_vendor: false %}
{%- endcomment -%}

<div class="product-card">
  <a href="{{ product.url }}">
    {{ product.featured_image | image_tag: widths: '360, 720', loading: 'lazy' }}
    <h3>{{ product.title }}</h3>
    <p>{{ product.price | money }}</p>
  </a>
</div>
liquid
{%- comment -%}
Usage:
{% render 'product-card', product: product, show_vendor: false %}
{%- endcomment -%}

<div class="product-card">
  <a href="{{ product.url }}">
    {{ product.featured_image | image_tag: widths: '360, 720', loading: 'lazy' }}
    <h3>{{ product.title }}</h3>
    <p>{{ product.price | money }}</p>
  </a>
</div>

Conditional Rendering

条件渲染示例

liquid
{% liquid
  if section.settings.show_title
    assign title_visible = true
  else
    assign title_visible = false
  endif
%}

{% if title_visible %}
  <h2>{{ section.settings.title }}</h2>
{% endif %}
liquid
{% liquid
  if section.settings.show_title
    assign title_visible = true
  else
    assign title_visible = false
  endif
%}

{% if title_visible %}
  <h2>{{ section.settings.title }}</h2>
{% endif %}

Instructions

操作指南

  1. Use 
    render
     for snippets, never 
    include
  2. Add Usage comments to all snippets
  3. Use 
    liquid
    tag     for complex logic
  4. Always use 
    image_tag
     - never hardcode 
    <img>
  5. Inline SVGs using 
    inline_asset_content
    filter
  6. Keep logic linear - avoid deep nesting
  7. Use responsive images with proper srcset and sizes
  1. **使用
    render
    **引入代码片段，禁止使用
    include
  2. 为所有代码片段添加使用说明注释
  3. 针对复杂逻辑使用
    liquid
    标签
  4. 始终使用
    image_tag
     - 禁止硬编码
    <img>
    标签
  5. 使用
    inline_asset_content
    过滤器内联SVG
  6. 保持逻辑线性 - 避免深层嵌套
  7. 使用响应式图片并配置正确的srcset与sizes属性