theme-shopify-liquid-templates

Shopify Liquid 模板

Shopify 主题中 Liquid 模板、片段、逻辑流程、图像处理和 SVG 使用的最佳实践。

使用场景

• 创建或修改 Liquid 模板
• 使用片段
• 处理图像和媒体
• 编写 Liquid 逻辑
• 使用 SVG 图标

片段

用法

• 只使用 {% render %}（绝不使用 include）
• 在每个片段顶部添加 用法 区块

片段结构

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

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

片段参数

通过参数向片段传递数据：

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

为什么使用 render 而不是 include

• render 的性能更好
• 变量作用域更清晰
• Shopify 推荐使用

Liquid 逻辑

使用 {% 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
%}

逻辑最佳实践

• 避免条件语句嵌套过深
• 优先采用可读、线性的逻辑
• 如有需要，将复杂逻辑拆分到多个 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>

图像

始终使用 image_tag

• 始终使用 image_tag 过滤器
• 使用响应式 srcset 和尺寸
• 不要硬编码 <img> 标签
• 使用 <image_url> 生成图像 URL。
• 对 <image_url> 始终指定宽度或高度参数。

Image Tag 语法

{{ image | image_url: width: image.width | image_tag: widths: '360, 720, 1080', loading: 'lazy' }}

响应式图像

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

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

图像设置

常见的 image_tag 参数：

• widths：用于 srcset 的逗号分隔宽度列表
• sizes：响应式图像的 sizes 属性
• loading：'lazy' 或 'eager'
• alt：替代文本（使用 | escape 过滤器）

SVG 文件

内联 SVG

使用 inline_asset_content 过滤器内联 SVG：

{{ 'icon-arrow.svg' | inline_asset_content }}

不要粘贴原始 SVG

• 不要将原始 SVG 标记粘贴到模板中
• 将 SVG 文件存放在 assets/ 目录中
• 使用 inline_asset_content 过滤器引入 SVG

SVG 示例

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

SVG 样式

内联后，可以使用 CSS 为 SVG 设置样式：

.icon-button svg {
  width: 24px;
  height: 24px;
  fill: currentColor;
}

Shopify 主题文档

请参考以下 Shopify 官方资源：

• Liquid 文档
• Liquid 对象
• Liquid 过滤器
• Liquid 标签
• 主题模板
• 片段
• 图像过滤器

常见 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
  if section.settings.show_title
    assign title_visible = true
  else
    assign title_visible = false
  endif
%}

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

说明

1. 使用 render 调用片段，绝不使用 include
2. 为所有片段添加用法注释
3. 对复杂逻辑使用 liquid 标签
4. 始终使用 image_tag，绝不硬编码 <img>
5. 使用 inline_asset_content 过滤器内联 SVG
6. 保持逻辑线性，避免嵌套过深
7. 使用合适的 srcset 和 sizes 创建响应式图像