5--- title: “过滤器完全指南” description: “全面掌握Shopify Liquid过滤器，包含所有过滤器的详细说明和实际代码示例”

过滤器完全指南

过滤器是 Liquid 模板语言的核心功能之一，用于修改对象的输出。本指南将详细介绍所有可用的 Shopify Liquid 过滤器，并提供实际的代码示例。

过滤器基础

基本语法


{{ object | filter_name }}
{{ object | filter_name: parameter }}
{{ object | filter_name: parameter1, parameter2 }}

链式过滤器


{{ product.title | downcase | replace: ' ', '-' | append: '.html' }}

字符串过滤器

文本转换

`upcase` - 转换为大写


{{ 'hello world' | upcase }}
<!-- 输出: HELLO WORLD -->
 
{{ product.title | upcase }}
<!-- 输出产品标题的大写形式 -->

`downcase` - 转换为小写


{{ 'HELLO WORLD' | downcase }}
<!-- 输出: hello world -->
 
{{ customer.email | downcase }}
<!-- 确保邮箱地址为小写 -->

`capitalize` - 首字母大写


{{ 'hello world' | capitalize }}
<!-- 输出: Hello world -->
 
{{ customer.first_name | capitalize }}
<!-- 客户名字首字母大写 -->

`strip` - 移除首尾空格


{{ '  hello world  ' | strip }}
<!-- 输出: hello world -->

文本处理

`truncate` - 截断文本


{{ product.description | truncate: 100 }}
<!-- 截断到100个字符 -->
 
{{ product.description | truncate: 100, '...' }}
<!-- 自定义截断标记 -->
 
{{ article.content | strip_html | truncate: 150 }}
<!-- 先移除HTML再截断 -->

`strip_html` - 移除HTML标签


{{ product.description | strip_html }}
<!-- 移除所有HTML标签 -->
 
{{ article.content | strip_html | truncate: 200 }}
<!-- 移除HTML标签后截断 -->

`strip_newlines` - 移除换行符


{{ product.description | strip_newlines }}
<!-- 移除所有换行符 -->

`newline_to_br` - 换行符转换为`<br />`


{{ product.description | newline_to_br }}
<!-- 将\n转换为<br>标签 -->

字符串操作

`replace` - 替换文本


{{ product.title | replace: 'iPhone', 'Apple iPhone' }}
<!-- 替换指定文本 -->
 
{{ product.handle | replace: '-', ' ' | capitalize }}
<!-- 将连字符替换为空格并首字母大写 -->

`remove` - 移除文本


{{ product.title | remove: 'Brand:' }}
<!-- 移除指定文本 -->
 
{{ product.tags | join: ', ' | remove: 'hidden' }}
<!-- 从标签列表中移除特定标签 -->

`append` - 添加到末尾


{{ product.title | append: ' - 限时特价' }}
<!-- 在标题末尾添加文本 -->
 
{{ product.url | append: '?utm_source=newsletter' }}
<!-- 在URL后添加参数 -->

`prepend` - 添加到开头


{{ product.title | prepend: '热销商品: ' }}
<!-- 在标题开头添加文本 -->

`split` - 分割字符串


{{ product.tags | split: ',' }}
<!-- 将标签字符串分割为数组 -->

URL和编码

`url_encode` - URL编码


{{ product.title | url_encode }}
<!-- URL编码产品标题 -->
 
{{ search.terms | url_encode }}
<!-- 编码搜索词 -->

`url_decode` - URL解码


{{ encoded_text | url_decode }}
<!-- URL解码 -->

`escape` - HTML转义


{{ product.description | escape }}
<!-- 转义HTML特殊字符 -->
 
{{ customer.note | escape }}
<!-- 安全显示用户输入内容 -->

`escape_once` - HTML转义(只转义一次)


{{ content | escape_once }}
<!-- 避免重复转义 -->

数字过滤器

金额格式化

`money` - 格式化为货币


{{ product.price | money }}
<!-- 输出: ¥99.00 -->
 
{{ cart.total_price | money }}
<!-- 购物车总价格式化 -->

`money_without_currency` - 不显示货币符号


{{ product.price | money_without_currency }}
<!-- 输出: 99.00 -->

`money_with_currency` - 显示货币代码


{{ product.price | money_with_currency }}
<!-- 输出: ¥99.00 CNY -->

数学运算

`plus` - 加法


{{ product.price | plus: 10 }}
<!-- 价格加10 -->
 
{{ cart.item_count | plus: 1 }}
<!-- 购物车数量加1 -->

`minus` - 减法


{{ product.compare_at_price | minus: product.price }}
<!-- 计算折扣金额 -->

`times` - 乘法


{{ product.price | times: 0.9 }}
<!-- 9折价格 -->
 
{{ item.quantity | times: item.price }}
<!-- 计算总价 -->

`divided_by` - 除法


{{ product.price | divided_by: 2 }}
<!-- 价格除以2 -->
 
{{ total_savings | divided_by: original_price | times: 100 }}
<!-- 计算折扣百分比 -->

`modulo` - 取余


{{ forloop.index | modulo: 2 }}
<!-- 判断奇偶数 -->

数字格式化

`round` - 四舍五入


{{ 4.6 | round }}
<!-- 输出: 5 -->
 
{{ product.price | divided_by: 3 | round: 2 }}
<!-- 保留两位小数 -->

`ceil` - 向上取整


{{ 4.2 | ceil }}
<!-- 输出: 5 -->

`floor` - 向下取整


{{ 4.8 | floor }}
<!-- 输出: 4 -->

`abs` - 绝对值


{{ -5 | abs }}
<!-- 输出: 5 -->

日期过滤器

`date` - 日期格式化


<!-- 基本格式 -->
{{ article.published_at | date: '%Y-%m-%d' }}
<!-- 输出: 2023-12-01 -->
 
{{ article.published_at | date: '%B %d, %Y' }}
<!-- 输出: December 01, 2023 -->
 
<!-- 中文格式 -->
{{ article.published_at | date: '%Y年%m月%d日' }}
<!-- 输出: 2023年12月01日 -->
 
{{ article.published_at | date: '%m月%d日 %H:%M' }}
<!-- 输出: 12月01日 14:30 -->
 
<!-- 完整示例 -->
{{ order.created_at | date: '%Y年%m月%d日 %H:%M:%S' }}
<!-- 订单创建时间 -->
 
{{ customer.created_at | date: '%Y年%m月' }}
<!-- 客户注册月份 -->

常用日期格式


<!-- 完整日期时间 -->
{{ 'now' | date: '%Y-%m-%d %H:%M:%S' }}
 
<!-- 短日期 -->
{{ 'now' | date: '%m/%d/%Y' }}
 
<!-- 长日期 -->
{{ 'now' | date: '%A, %B %d, %Y' }}
 
<!-- 时间戳 -->
{{ 'now' | date: '%s' }}
 
<!-- ISO 8601 格式 -->
{{ 'now' | date: '%Y-%m-%dT%H:%M:%S%z' }}

数组过滤器

数组信息

`size` - 获取数组长度


{{ collection.products | size }}
<!-- 集合中产品数量 -->
 
{{ cart.items | size }}
<!-- 购物车商品种类数 -->
 
{{ product.tags | size }}
<!-- 产品标签数量 -->

`first` - 获取第一个元素


{{ collection.products | first }}
<!-- 第一个产品 -->
 
{{ product.images | first | img_url: '300x300' }}
<!-- 第一张产品图片 -->

`last` - 获取最后一个元素


{{ collection.products | last }}
<!-- 最后一个产品 -->
 
{{ blog.articles | last }}
<!-- 最新文章 -->

数组操作

`join` - 连接数组元素


{{ product.tags | join: ', ' }}
<!-- 用逗号连接标签 -->
 
{{ breadcrumb | join: ' > ' }}
<!-- 面包屑导航 -->

`split` - 分割字符串为数组


{{ 'red,green,blue' | split: ',' }}
<!-- 分割为颜色数组 -->
 
{{ product.tags | split: ',' | join: ' | ' }}
<!-- 重新格式化标签 -->

`reverse` - 反转数组


{% assign products = collection.products | reverse %}
{% for product in products %}
  <!-- 从最新到最旧显示产品 -->
{% endfor %}

`sort` - 排序数组


{{ product.tags | sort }}
<!-- 按字母顺序排序标签 -->
 
{% assign sorted_products = collection.products | sort: 'price' %}
<!-- 按价格排序产品 -->

`sort_natural` - 自然排序


{{ product.tags | sort_natural }}
<!-- 自然排序(数字按数值排序) -->

`uniq` - 去重


{{ all_tags | uniq }}
<!-- 移除重复标签 -->

数组筛选

`where` - 筛选数组


{% assign available_products = collection.products | where: 'available', true %}
<!-- 筛选有库存的产品 -->
 
{% assign featured_articles = blog.articles | where: 'tags', 'featured' %}
<!-- 筛选特色文章 -->

`map` - 提取属性


{{ collection.products | map: 'title' }}
<!-- 提取所有产品标题 -->
 
{{ cart.items | map: 'product.vendor' | uniq %}
<!-- 获取购物车中所有供应商 -->

图片过滤器

`img_url` - 生成图片URL


<!-- 指定尺寸 -->
{{ product.featured_image | img_url: '300x300' }}
<!-- 300x300 像素 -->
 
{{ product.featured_image | img_url: '500x' }}
<!-- 宽度500像素，高度自适应 -->
 
{{ product.featured_image | img_url: 'x400' }}
<!-- 高度400像素，宽度自适应 -->
 
<!-- 预设尺寸 -->
{{ product.featured_image | img_url: 'master' }}
{{ product.featured_image | img_url: 'grande' }}
{{ product.featured_image | img_url: 'large' }}
{{ product.featured_image | img_url: 'medium' }}
{{ product.featured_image | img_url: 'compact' }}
{{ product.featured_image | img_url: 'small' }}
{{ product.featured_image | img_url: 'thumb' }}
{{ product.featured_image | img_url: 'icon' }}
 
<!-- 响应式图片 -->
<img src="{{ product.featured_image | img_url: '300x300' }}"
     srcset="{{ product.featured_image | img_url: '300x300' }} 1x,
             {{ product.featured_image | img_url: '600x600' }} 2x"
     alt="{{ product.featured_image.alt | escape }}">

`img_tag` - 生成img标签


{{ product.featured_image | img_tag: '300x300', alt: product.title }}
<!-- 生成完整的img标签 -->
 
{{ article.image | img_tag: 'large', class: 'article-image', loading: 'lazy' }}
<!-- 带CSS类和懒加载 -->

颜色过滤器

`color_to_rgb` - 转换为RGB


{{ '#ff0000' | color_to_rgb }}
<!-- 输出: rgb(255, 0, 0) -->

`color_to_hsl` - 转换为HSL


{{ '#ff0000' | color_to_hsl }}
<!-- 输出: hsl(0, 100%, 50%) -->

`color_to_hex` - 转换为HEX


{{ 'rgb(255, 0, 0)' | color_to_hex }}
<!-- 输出: #ff0000 -->

`color_brightness` - 获取亮度


{{ '#ffffff' | color_brightness }}
<!-- 输出亮度值 -->

`color_lighten` - 调亮颜色


{{ '#ff0000' | color_lighten: 20 }}
<!-- 将红色调亮20% -->

`color_darken` - 调暗颜色


{{ '#ff0000' | color_darken: 20 }}
<!-- 将红色调暗20% -->

实际应用示例

产品卡片完整示例


<!-- snippets/product-card.liquid -->
<div class="product-card" data-product-id="{{ product.id }}">
  <!-- 产品图片 -->
  <div class="product-image">
    <a href="{{ product.url }}">
      {% if product.featured_image %}
        <img src="{{ product.featured_image | img_url: '300x300' }}"
             srcset="{{ product.featured_image | img_url: '300x300' }} 1x,
                     {{ product.featured_image | img_url: '600x600' }} 2x"
             alt="{{ product.featured_image.alt | escape | default: product.title }}"
             loading="lazy">
      {% else %}
        <div class="no-image">暂无图片</div>
      {% endif %}
    </a>
    
    <!-- 促销标签 -->
    {% if product.compare_at_price > product.price %}
      {% assign discount = product.compare_at_price | minus: product.price %}
      {% assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price | round %}
      <span class="sale-badge">-{{ discount_percent }}%</span>
    {% endif %}
  </div>
 
  <!-- 产品信息 -->
  <div class="product-info">
    <!-- 供应商 -->
    {% if product.vendor != blank %}
      <div class="product-vendor">{{ product.vendor | upcase }}</div>
    {% endif %}
 
    <!-- 产品标题 -->
    <h3 class="product-title">
      <a href="{{ product.url }}">
        {{ product.title | truncate: 60 }}
      </a>
    </h3>
 
    <!-- 产品价格 -->
    <div class="product-price">
      {% if product.compare_at_price > product.price %}
        <span class="price-compare">{{ product.compare_at_price | money }}</span>
        <span class="price-sale">{{ product.price | money }}</span>
      {% else %}
        <span class="price">{{ product.price | money }}</span>
      {% endif %}
    </div>
 
    <!-- 产品标签 -->
    {% if product.tags.size > 0 %}
      <div class="product-tags">
        {% assign display_tags = product.tags | where_not: 'hidden' | slice: 0, 3 %}
        {% for tag in display_tags %}
          <span class="tag">{{ tag | replace: '_', ' ' | capitalize }}</span>
        {% endfor %}
      </div>
    {% endif %}
 
    <!-- 变体信息 -->
    {% if product.variants.size > 1 %}
      <div class="variant-info">
        {{ product.variants.size }} 个选项可选
      </div>
    {% endif %}
  </div>
</div>

购物车摘要示例


<!-- snippets/cart-summary.liquid -->
<div class="cart-summary">
  <!-- 购物车商品数量 -->
  <div class="cart-count">
    购物车 ({{ cart.item_count }} {% if cart.item_count == 1 %}件商品{% else %}件商品{% endif %})
  </div>
 
  <!-- 商品列表 -->
  {% for item in cart.items limit: 5 %}
    <div class="cart-item-summary">
      <img src="{{ item.image | img_url: '60x60' }}" 
           alt="{{ item.title | escape }}">
      <div class="item-details">
        <div class="item-title">{{ item.product.title | truncate: 30 }}</div>
        {% unless item.variant.title contains 'Default' %}
          <div class="item-variant">{{ item.variant.title }}</div>
        {% endunless %}
        <div class="item-quantity-price">
          {{ item.quantity }} × {{ item.price | money }}
        </div>
      </div>
    </div>
  {% endfor %}
 
  <!-- 显示更多 -->
  {% if cart.item_count > 5 %}
    <div class="more-items">
      还有 {{ cart.item_count | minus: 5 }} 件商品...
    </div>
  {% endif %}
 
  <!-- 总计 -->
  <div class="cart-total">
    <div class="subtotal">
      小计: {{ cart.total_price | money }}
    </div>
    {% if cart.total_discounts > 0 %}
      <div class="discounts">
        折扣: -{{ cart.total_discounts | money }}
      </div>
    {% endif %}
  </div>
</div>

博客文章预览


<!-- snippets/article-preview.liquid -->
<article class="article-preview">
  <!-- 文章图片 -->
  {% if article.image %}
    <div class="article-image">
      <a href="{{ article.url }}">
        <img src="{{ article.image | img_url: '400x250' }}"
             alt="{{ article.image.alt | escape | default: article.title }}"
             loading="lazy">
      </a>
    </div>
  {% endif %}
 
  <!-- 文章内容 -->
  <div class="article-content">
    <!-- 文章标题 -->
    <h2 class="article-title">
      <a href="{{ article.url }}">{{ article.title }}</a>
    </h2>
 
    <!-- 文章元信息 -->
    <div class="article-meta">
      <time datetime="{{ article.published_at | date: '%Y-%m-%d' }}">
        {{ article.published_at | date: '%Y年%m月%d日' }}
      </time>
      {% if article.author != blank %}
        <span class="author">作者: {{ article.author }}</span>
      {% endif %}
      {% if article.tags.size > 0 %}
        <div class="tags">
          {% for tag in article.tags limit: 3 %}
            <span class="tag">{{ tag | replace: '_', ' ' | capitalize }}</span>
          {% endfor %}
        </div>
      {% endif %}
    </div>
 
    <!-- 文章摘要 -->
    <div class="article-excerpt">
      {% if article.excerpt != blank %}
        {{ article.excerpt | strip_html | truncate: 200 }}
      {% else %}
        {{ article.content | strip_html | truncate: 200 }}
      {% endif %}
    </div>
 
    <!-- 阅读时间估算 -->
    {% assign reading_time = article.content | strip_html | split: ' ' | size | divided_by: 200 | at_least: 1 %}
    <div class="reading-time">
      预计阅读时间: {{ reading_time }} 分钟
    </div>
 
    <a href="{{ article.url }}" class="read-more">阅读全文</a>
  </div>
</article>

过滤器最佳实践

1. 性能考虑


<!-- 好的做法：在循环外处理数据 -->
{% assign featured_products = collection.products | where: 'tags', 'featured' %}
{% for product in featured_products %}
  <!-- 渲染产品 -->
{% endfor %}
 
<!-- 避免：在循环内重复处理 -->
{% for product in collection.products %}
  {% if product.tags contains 'featured' %}
    <!-- 渲染产品 -->
  {% endif %}
{% endfor %}

2. 安全性


<!-- 始终转义用户输入 -->
{{ customer.note | escape }}
{{ search.terms | escape }}
 
<!-- 处理可能为空的值 -->
{{ product.featured_image.alt | escape | default: product.title }}

3. 可读性


<!-- 使用变量提高可读性 -->
{% assign discount_percent = product.compare_at_price | minus: product.price | times: 100 | divided_by: product.compare_at_price | round %}
 
<!-- 而不是一行完成所有计算 -->
{{ product.compare_at_price | minus: product.price | times: 100 | divided_by: product.compare_at_price | round }}%

5--- title: “过滤器完全指南” description: “全面掌握Shopify Liquid过滤器，包含所有过滤器的详细说明和实际代码示例”

过滤器完全指南

过滤器基础

基本语法

链式过滤器

字符串过滤器

文本转换

upcase - 转换为大写

downcase - 转换为小写

capitalize - 首字母大写

strip - 移除首尾空格

文本处理

truncate - 截断文本

strip_html - 移除HTML标签

strip_newlines - 移除换行符

newline_to_br - 换行符转换为<br />

字符串操作

replace - 替换文本

remove - 移除文本

append - 添加到末尾

prepend - 添加到开头

split - 分割字符串

URL和编码

url_encode - URL编码

url_decode - URL解码

escape - HTML转义

escape_once - HTML转义(只转义一次)

数字过滤器

金额格式化

money - 格式化为货币

money_without_currency - 不显示货币符号

money_with_currency - 显示货币代码

数学运算

plus - 加法

minus - 减法

times - 乘法

divided_by - 除法

modulo - 取余

数字格式化

round - 四舍五入

ceil - 向上取整

floor - 向下取整

abs - 绝对值

日期过滤器

date - 日期格式化

常用日期格式

数组过滤器

数组信息

size - 获取数组长度

first - 获取第一个元素

last - 获取最后一个元素

数组操作

join - 连接数组元素

split - 分割字符串为数组

reverse - 反转数组

sort - 排序数组

sort_natural - 自然排序

uniq - 去重

数组筛选

where - 筛选数组

map - 提取属性

图片过滤器

img_url - 生成图片URL

img_tag - 生成img标签

颜色过滤器

color_to_rgb - 转换为RGB

color_to_hsl - 转换为HSL

color_to_hex - 转换为HEX

color_brightness - 获取亮度

color_lighten - 调亮颜色

color_darken - 调暗颜色

实际应用示例

产品卡片完整示例

购物车摘要示例

博客文章预览

过滤器最佳实践

1. 性能考虑

2. 安全性

3. 可读性

相关资源

`upcase` - 转换为大写

`downcase` - 转换为小写

`capitalize` - 首字母大写

`strip` - 移除首尾空格

`truncate` - 截断文本

`strip_html` - 移除HTML标签

`strip_newlines` - 移除换行符

`newline_to_br` - 换行符转换为`<br />`

`replace` - 替换文本

`remove` - 移除文本

`append` - 添加到末尾

`prepend` - 添加到开头

`split` - 分割字符串

`url_encode` - URL编码

`url_decode` - URL解码

`escape` - HTML转义

`escape_once` - HTML转义(只转义一次)

`money` - 格式化为货币

`money_without_currency` - 不显示货币符号

`money_with_currency` - 显示货币代码

`plus` - 加法

`minus` - 减法

`times` - 乘法

`divided_by` - 除法

`modulo` - 取余

`round` - 四舍五入

`ceil` - 向上取整

`floor` - 向下取整

`abs` - 绝对值

`date` - 日期格式化

`size` - 获取数组长度

`first` - 获取第一个元素

`last` - 获取最后一个元素

`join` - 连接数组元素

`split` - 分割字符串为数组

`reverse` - 反转数组

`sort` - 排序数组

`sort_natural` - 自然排序

`uniq` - 去重

`where` - 筛选数组

`map` - 提取属性

`img_url` - 生成图片URL

`img_tag` - 生成img标签

`color_to_rgb` - 转换为RGB

`color_to_hsl` - 转换为HSL

`color_to_hex` - 转换为HEX

`color_brightness` - 获取亮度

`color_lighten` - 调亮颜色

`color_darken` - 调暗颜色