Liquid中文使用手册转载
Liquid 是一门开源的模板语言,由 Shopify 创造并用 Ruby 实现。它是 Shopify 主题的骨骼,并且被用于加载店铺系统的动态内容。 从 2006 年起,Liquid 就被 Shopify 所使用,现在更是被大量 web 应用所使用。
基础
简介
Liquid 代码可分为 对象(object)、标记(tag) 和 过滤器(filter)。
对象
对象 告诉 Liquid 在页面的哪个位置展示内容。对象和变量名由双花括号标识:{{
和 }}
。
{{ page.title }}
→Introduction
上述实例中,Liquid 输出 page.title
对象的内容,此对象保存的是文本 Introduction
。
标记(tag)
标记(tag) 创造了模板的逻辑和控制流。他们由单括号加百分号标识: {%
和 %}
。
标记(tag)并不产生任何可见的文本输出。这意味着你可以用他们为变量赋值、创建条件和循环逻辑,并且不在页面上显示出任何 Liquid 逻辑代码。
{% if user %}
Hello {{ user.name }}!
{% endif %}
→Hello Adam!
标记被分为三类:
你可以在每一类标记所对应的章节了解更多信息。
过滤器
过滤器 改变 Liquid 对象的输出。他们被用在输出上,通过一个 |
符号分隔。
{{ "/my/fancy/url" | append: ".html" }}
→/my/fancy/url.html
多个过滤器可以共同作用于同一个输出,并按照从左到右的顺序执行。
{{ "adam!" | capitalize | prepend: "Hello " }}
→Hello Adam!
操作符
Liquid 包含了大量逻辑(logical)和比较操作符(comparison operator)。
基本操作符
== |
相等 |
---|---|
!= |
不相等 |
> |
大于 |
< |
小于 |
>= |
大于或等于 |
<= |
小于或等于 |
or |
逻辑或 |
and |
逻辑与 |
例如:
{% if product.title == "Awesome Shoes" %}
These shoes are awesome!
{% endif %}
可以在一个标记(tag)中使用多个操作符:
{% if product.type == "Shirt" or product.type == "Shoes" %}
This is a shirt or a pair of shoes.
{% endif %}
contains(包含)
contains
用于检查在一个字符串中是否存在某个子串。
{% if product.title contains 'Pack' %}
This product's title contains the word Pack.
{% endif %}
contains
还可以用于检查一个字符串数组中是否存在某个字符串。
{% if product.tags contains 'Hello' %}
This product has been tagged with 'Hello'.
{% endif %}
contains
只能用于搜索字符串。你不能将其用于从一个对象数组中检查是否存在某个对象。
真值与假值
编程时,在条件判断中任何返回 true
的都被叫做 真值(truthy)。任何返回 false
的都被叫做 假值(falsy)。所有的对象(object)类型都可以被描述为真值(truthy)或假值(falsy)。
真值(Truthy)
除了 nil
和 false
之外的所有值都是真值。
如下例,字符串 “Tobi” 虽不是布尔类型,但是其在条件判断时被当做真值(truthy):
{% assign tobi = "Tobi" %}
{% if tobi %}
This condition will always be true.
{% endif %}
字符串(String),即便是空字符串,也是真值(truthy)。如下例,如果 settings.fp_heading
是个空字符串将会输出空 HTML 标签:
{% if settings.fp_heading %}
<h1>{{ settings.fp_heading }}</h1>
{% endif %}
→<h1></h1>
假值(Falsy)
总结
下表总结了在 Liquid 中什么是真值什么是假值。
真值(truthy) | 假值(falsy) | |
---|---|---|
true | • | |
false | • | |
nil | • | |
string | • | |
empty string | • | |
0 | • | |
integer | • | |
float | • | |
array | • | |
empty array | • | |
page | • | |
EmptyDrop | • |
数据类型
Liquid 对象的类型可以是以下五种:
你可以通过 assign 或 capture 标记来初始化 Liquid 变量。
String(字符串)
将变量的值包裹在单引号或双引号之中就声明了一个字符串:
{% assign my_string = "Hello World!" %}
Number(数字)
数字类型包括浮点数和整数:
{% assign my_int = 25 %}
{% assign my_float = 39.756 %}
Boolean(布尔)
Booleans 类型只能是 true
或 false
。布尔值千万不能加引号,否则就成为字符串了。
{% assign foo = true %}
{% assign bar = false %}
Nil(空)
Nil 是一个特殊的空值,当 Liquid 代码没有可输出的结果时将返回 Nil。他并不是由 “nil” 这个三个字符组成的字符串。
在 if
条件判断和其他 Liquid 标记(tag)判断语句中,Nil 被当做 false 。
下例中,如果 user 不存在(也就是 user
返回 nil
),Liquid 不输出问候语:
{% if user %}
Hello {{ user.name }}!
{% endif %}
如果 Liquid 标记(tag)或输出返回的是 nil
,页面上将不会有任何内容。
The current user is {{ user.name }}
→
The current user is
Array(数组)
数组能够存储一组任意类型的变量。
访问数组中的项
通过 迭代标记(iteration tag) 可以访问数组中的所有项。
<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{% for user in site.users %}
{{ user }}
{% endfor %}
→
Tobi Laura Tetsuro Adam
访问数组中的特定项
利用方括号 [
]
能够访问数组中的特定项。数组的索引从 0 开始。
<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[3] }}
→
Tobi
Laura
Adam
初始化数组
你无法只通过 Liquid 语法初始化一个数组。
然而,你可以利用 split 过滤器将一个字符串分割为一个子字符串数组。
Liquid 的各种分支
Liquid 是一门灵活、安全的模版语言,被用于许多不同环境中。Liquid 被创建之初是用在 Shopify 商店系统中的,后来也被广泛用于 Jekyll 网站中。随着时间的推移,Shopify 和 Jekyll 分别为 Liquid 添加了针对各自用途的对象(object)、标记(tag)和过滤器(filter)。目前最流行的 Liquid 版本包括 Liquid、Shopify Liquid 和 Jekyll Liquid。
本站点托管的是最新版本的 Liquid 的文档,包括了 beta 和 release candidate 版本中包含的特性,也就是说,是独立于 Shopify 和 Jekyll 之外的 Liquid。如果你是从 Liquid 仓库下载的代码或者安装的的是 gem 包,你所选择的 Liquid 版本对应你能够访问的对象(object)、标记(tag)和过滤器。
Shopify
Shopify 一直采用的都是最新版本的 Liquid,并且 Shopify 会针对 merchants’ store 为 Liquid 添加大量的对象(object)、标记(tag)和过滤器。这些新增的内容包括代表商店(store)、产品(product)和顾客信息的对象,以及用于展示商店数据和操作产品照片的过滤器。
Shopify 版本的 Liquid 所对应的文档在 Shopify Help Center。如果你希望尝试 Shopify 版本的 Liquid,你可以试用 Shopify 或者使用类似 DropPen 的工具。
Jekyll
Jekyll 是一个静态网站生成器,一个用于将模版和内容合并到一起从而创建网站的命令行工具。ekyll 将 Liquid 作为自身的模版语言,并且添加了许多对象(object)、标记(tag)和过滤器(filter)。这些新增内容包括代表内容页面的对象、用于在页面中引入内容片段的标记(tag),以及用于操作字符串和 URL 的过滤器。
Jekyll 还是 GitHub Pages 的底层引擎。GitHub Pages 是一项网站托管服务,允许你将 Jekyll 网站推送到 GitHub 仓库,最终得到一个发布到公网的站点。本网站就是由 GitHub Pages 托管的。
Jekyll 可能使用的不是最新版本的 Liquid。也就意味着本文档所列出的标记(tag)和过滤器不能在 Jekyll 中使用。通常 Jekyll 项目使用的是稳定版的 Liquid,而不使用 beta 或 release candidate 版本。通过 Jekyll 的 gem 信息也 可查看 Jekyll 所依赖的所有 gem 包,从而可以了解 Jekyll 所使用的 Liquid 版本。
Jekyll 版本的 Liquid 的文档在 Templates section of Jekyll’s documentation。如果你希望尝试 Jekyll 版本的 Liquid,你可以克隆 Jekyll 项目或者安装 Jekyll 的 gem 包,然后在静态网站中测试 Liquid。
控制输出的空白符
在 Liquid 模版中,你可以将连字符放在标记(tag)中,例如 {{-
、-}}
、{%-
和 -%}
,用于将标记(tag)渲染之后的输出内容的左侧或右侧的空拍符剔除。
通常,即使不输出文本,模版中的任何 Liquid 表达式仍然会在渲染之后输出的 HTML 中包含一个空行:
请注意渲染之后输出的 “tomato” 字符前面包含了一个空行:
{% assign my_variable = "tomato" %}
{{ my_variable }}
→tomato
通过为 assign
标记(tag)添加连字符,可以将渲染之后所输出的空拍符删除:
{%- assign my_variable = "tomato" -%}
{{ my_variable }}
→tomato
如果你不希望任何标记(tag)被渲染之后所输出的内容有任何空白符,只需在所有标记(tag)两侧全部添加连字符即可,例如 ({%-
和 -%}
):
不做空白符控制的输出
{% assign username = "John G. Chalmers-Smith" %}
{% if username and username.size > 10 %}
Wow, {{ username }}, you have a long name!
{% else %}
Hello there!
{% endif %}
→ Wow, John G. Chalmers-Smith, you have a long name!
带有空白符控制的输出
{%- assign username = "John G. Chalmers-Smith" -%}
{%- if username and username.size > 10 -%}
Wow, {{ username }}, you have a long name!
{%- else -%}
Hello there!
{%- endif -%}
→Wow, John G. Chalmers-Smith, you have a long name!
标签
注释
comment
标记让你能够在 Liquid 模板中书写的内容不被输出。任何书写在 comment
起始与结束标记之间的内容都不会被输出,如果是 Liquid 代码则不会被执行。
Anything you put between {% comment %} and {% endcomment %} tags
is turned into a comment.
→
Anything you put between tags
is turned into a comment.
控制流
控制流标记(control flow tag)能够根据编程逻辑改变 Liquid 输出的信息。
if
只有当某个条件为 true
时才执行一段代码。
{% if product.title == 'Awesome Shoes' %}
These shoes are awesome!
{% endif %}
→These shoes are awesome!
unless
与 if
相对 – 只有当某个条件不成立时才执行一段代码。
{% unless product.title == 'Awesome Shoes' %}
These shoes are not awesome.
{% endunless %}
→These shoes are not awesome.
和如下实例的执行结果一致:
{% if product.title != 'Awesome Shoes' %}
These shoes are not awesome.
{% endif %}
elsif / else
为 if
或 unless
添加更多状态判断。
<!-- If customer.name = 'anonymous' -->
{% if customer.name == 'kevin' %}
Hey Kevin!
{% elsif customer.name == 'anonymous' %}
Hey Anonymous!
{% else %}
Hi Stranger!
{% endif %}
→Hey Anonymous!
case/when
创建一个开关表达式,用于将一个变量和多个不同值进行比较。case
用于初始化一个开关表达式,when
用于比较他们的值。
{% assign handle = 'cake' %}
{% case handle %}
{% when 'cake' %}
This is a cake
{% when 'cookie' %}
This is a cookie
{% else %}
This is not a cake nor a cookie
{% endcase %}
→This is a cake
迭代/循环
迭代(或循环)标记(iteration tag)用于重复运行一段代码。
for
重复运行一段代码。for
循环中所能够使用的属性请参考 forloop (object)。
{% for product in collection.products %}
{{ product.title }}
{% endfor %}
→hat shirt pants
break
循环过程中若干遇到 break
标记(tag)即停止循环。
{% for i in (1..5) %}
{% if i == 4 %}
{% break %}
{% else %}
{{ i }}
{% endif %}
{% endfor %}
→1 2 3
continue
循环过程中若遇到 continue
标记(tag)则跳出当前循环。
{% for i in (1..5) %}
{% if i == 4 %}
{% continue %}
{% else %}
{{ i }}
{% endif %}
{% endfor %}
→1 2 3 5
for (parameters)
limit
限定循环执行的次数。
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array limit:2 %}
{{ item }}
{% endfor %}
→1 2
offset
从指定索引号开始执行循环。
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array offset:2 %}
{{ item }}
{% endfor %}
→3 4 5 6
range
定义循环执行的范围。可利用数字或变量来定义此执行范围。
{% for i in (3..5) %}
{{ i }}
{% endfor %}
{% assign num = 4 %}
{% for i in (1..num) %}
{{ i }}
{% endfor %}
→
3 4 5
1 2 3 4
reversed
反转循环的执行顺序。注意和 reverse
过滤器(filter)的拼写是不同的。
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array reversed %}
{{ item }}
{% endfor %}
→6 5 4 3 2 1
cycle
循环一组字符串并按照它们传入的顺序将其输出。每次调用 cycle
时,传入的参数中的下一个字符串将被输出。
cycle
必须用在 for 循环中。
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
→
one
two
three
one
cycle
的使用场景包括:
- 对表格中的奇数/偶数行输出相应的类(class)
- 在一行中的最后一列输出一个唯一的类(class)
cycle (parameters)
cycle
能够接受一个叫做 cycle group
的参数,以便满足你在模版中需要使用多个 cycle
代码块的情况。如果没有为 cycle group 命名,那么将会假定带有相同参数的 cycle 调用属于同一个组(group)。
tablerow
生成一个 HTML 表格。必须用 <table>
和 </table>
这两个 HTML 标签将其包裹起来。
<table>
{% tablerow product in collection.products %}
{{ product.title }}
{% endtablerow %}
</table>
→
<table>
<tr class="row1">
<td class="col1">
Cool Shirt
</td>
<td class="col2">
Alien Poster
</td>
<td class="col3">
Batman Poster
</td>
<td class="col4">
Bullseye Shirt
</td>
<td class="col5">
Another Classic Vinyl
</td>
<td class="col6">
Awesome Jeans
</td>
</tr>
</table>
tablerow (parameters)
cols
定义表格应当有多少列。
{% tablerow product in collection.products cols:2 %}
{{ product.title }}
{% endtablerow %}
→
<table>
<tr class="row1">
<td class="col1">
Cool Shirt
</td>
<td class="col2">
Alien Poster
</td>
</tr>
<tr class="row2">
<td class="col1">
Batman Poster
</td>
<td class="col2">
Bullseye Shirt
</td>
</tr>
<tr class="row3">
<td class="col1">
Another Classic Vinyl
</td>
<td class="col2">
Awesome Jeans
</td>
</tr>
</table>
limit
在执行到指定的脚标(index)之后退出 tablerow 。
{% tablerow product in collection.products cols:2 limit:3 %}
{{ product.title }}
{% endtablerow %}
offset
在指定的脚标(index)之后开始执行 tablerow 。
{% tablerow product in collection.products cols:2 offset:3 %}
{{ product.title }}
{% endtablerow %}
range
定义循环执行的范围。可利用数字和变量来定义执行范围。
<!--variable number example-->
{% assign num = 4 %}
<table>
{% tablerow i in (1..num) %}
{{ i }}
{% endtablerow %}
</table>
<!--literal number example-->
<table>
{% tablerow i in (3..5) %}
{{ i }}
{% endtablerow %}
</table>
原始内容
raw
标记临时禁止处理其所包围的代码。如果输出的内容与 Liquid 模板语言有冲突时(例如 Mustache、Handlebars 模板语言)可以避免冲突。
下方应该是 {%, 没有空格,因为文章展示时有冲突,所以加了空格
{ % raw % }
In Handlebars, {{ this }} will be HTML-escaped, but
{{{ that }}} will not.
{ % endraw % }
→In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
变量
变量标记(variable tag)用于创建新的 Liquid 变量。
assign
创建一个新变量。
{% assign my_variable = false %}
{% if my_variable != true %}
This statement is valid.
{% endif %}
→ This statement is valid.
将变量用 "
包裹之后则将其当做字符串对待。
{% assign foo = "bar" %}
{{ foo }}
→bar
capture
将 capture
开始与结束标记之间的字符串捕获之后赋值给一个变量。通过 {% capture %}
创建的变量都是字符串。
{% capture my_variable %}I am being captured.{% endcapture %}
{{ my_variable }}
→I am being captured.
使用 capture
时,你还可以利用 assign
创建的其他变量创造一个复杂的字符串。
{% assign favorite_food = 'pizza' %}
{% assign age = 35 %}
{% capture about_me %}
I am {{ age }} and my favorite food is {{ favorite_food }}.
{% endcapture %}
{{ about_me }}
→I am 35 and my favourite food is pizza.
increment
创建一个全新的数值变量,并且在后续每次调用时将此变量的值加 1。初始值是 0。
{% increment my_counter %}
{% increment my_counter %}
{% increment my_counter %}
→
0
1
2
通过 increment
标记(tag)创建的变量与通过 assign
或 capture
创建的变量是相互独立的。
在下面的实例中,名为 “var” 的变量是通过 assign
创建的。然后将 increment
标记(tag)在相同的变量名上应用了几次。注意,increment
标记(tag)不会对 assign
创建的变量 “var” 及其值产生任何影响。
{% assign var = 10 %}
{% increment var %}
{% increment var %}
{% increment var %}
{{ var }}
→
0
1
2
10
decrement
创建一个全新的数值变量,并且在后续每次调用时将此变量的值减 1。初始值是 -1。
{% decrement variable %}
{% decrement variable %}
{% decrement variable %}
→
-1
-2
-3
和 increment 类似,在 decrement
之中创建的变量与通过 assign
或 capture
创建的变量是互相独立的。
筛选器
abs
返回一个数字的绝对值。
{{ -17 | abs }}
→17
{{ 4 | abs }}
→4
如果组成字符串的各个字符全是数字,abs
也能够对此字符串求绝对值。
{{ "-19.86" | abs }}
→19.86
append
将两个字符串拼接起来并返回拼接之后的值。
{{ "/my/fancy/url" | append: ".html" }}
→/my/fancy/url.html
append
同样能够作用于变量:
{% assign filename = "/index.html" %}
{{ "website.com" | append: filename }}
→website.com/index.html
at_least
将数字限制在最小值。
{{ 4 | at_least: 5 }}
→5
{{ 4 | at_least: 3 }}
→4
at_most
将数字限制在最大值。
{{ 4 | at_most: 5 }}
→
4
{{ 4 | at_most: 3 }}
→
3
capitalize
将字符串首字母转为大写。
{{ "title" | capitalize }}
→
Title
capitalize
只把字符串的首字母转为大写,其他字符不受影响:
{{ "my great title" | capitalize }}
→
My great title
ceil
将一个浮点数向上取整并返回一个最接近的整数。在 ceil 过滤器执行之前 Liquid 会先尝试将输入转换为数字格式。
{{ 1.2 | ceil }}
→
2
{{ 2.0 | ceil }}
→
2
{{ 183.357 | ceil }}
→
184
以下实例所用输入是字符串:
{{ "3.5" | ceil }}
→
4
compact
删除数组中的所有 nil
值。
例如,假定整个网站所有内容页面作为一个数组保存在 site.pages
变量中,其中某些页面被设置了 category
属性用于指定该页面的内容分类。如果我们利用 map
过滤器将所有页面的 category
属性保存到一个数组中,就会出现如果某个页面没有 category
属性,其在数组中的值就会是 nil
。
{% assign site_categories = site.pages | map: 'category' %}
{% for category in site_categories %}
{{ category }}
{% endfor %}
→
business
celebrities
lifestyle
sports
technology
在创建 site_categories
数组时,通过使用 compact
过滤器我们可以删除此数组中的所有 nil
值。
{% assign site_categories = site.pages | map: 'category' | compact %}
{% for category in site_categories %}
{{ category }}
{% endfor %}
→
business
celebrities
lifestyle
sports
technology
concat
连接(联接)多个数组。结果数组包含输入数组中的所有项。
{% assign fruits = "apples, oranges, peaches" | split: ", " %}
{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
{% assign everything = fruits | concat: vegetables %}
{% for item in everything %}
- {{ item }}
{% endfor %}
→
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
您可以将linat
过滤器串在一起,连接两个以上的数组:
{% assign furniture = "chairs, tables, shelves" | split: ", " %}
{% assign everything = fruits | concat: vegetables | concat: furniture %}
{% for item in everything %}
- {{ item }}
{% endfor %}
→
- apples
- oranges
- peaches
- carrots
- turnips
- potatoes
- chairs
- tables
- shelves
date
将时间戳(timestamp)转换为另一种日期格式。格式化语法与 strftime
一致。输入格式与 Ruby 中的 Time.parse
一致。
{{ article.published_at | date: "%a, %b %d, %y" }}
→
Fri, Jul 17, 15
{{ article.published_at | date: "%Y" }}
→
2015
date
能够作用于包含良好格式化的日期字符串:
{{ "March 14, 2016" | date: "%b %d, %y" }}
→
Mar 14, 16
将 "now"
(或 "today"
) 单词传入 date
过滤器可以获取当前时间:
This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
→
This page was last updated at 2020-05-01 14:41.
注意,上述实例输出的日期是最后一次生成当前页面的时间,并不是页面呈现给用户的时间。
default
指定一个默认值,以防预期的值不存在。如果左侧的值为 nil
、false
或空,default
将输出此默认值。
如下实例中,product_price
并未被定义,因此将输出默认值。
{{ product_price | default: 2.99 }}
→
2.99
如下实例中,product_price
已被定义,不再输出默认值。
{% assign product_price = 4.99 %}
{{ product_price | default: 2.99 }}
→
4.99
如下实例中,product_price
的值为空,因此将输出默认值。
{% assign product_price = "" %}
{{ product_price | default: 2.99 }}
→
2.99
divided_by
将两个数相除。
如果除数(divisor)为整数,则将相除之后得到的结果向下取整得到最接近的整数(也就是对应 floor 的功能)。
{{ 16 | divided_by: 4 }}
→
4
{{ 5 | divided_by: 3 }}
→
1
控制舍入
divided_by
返回的结果于除数是同一数据类型的,也就是说,如果除数是整数,返回的结果也是整数;如果除数是浮点数(带有小数),返回的结果也是浮点数。
如下实例,除数为整数:
{{ 20 | divided_by: 7 }}
→
2
除数为浮点数:
{{ 20 | divided_by: 7.0 }}
→
2.857142857142857
改变变量的类型
某些情况你需要将除数设置为一个变量,这种情况下你无法简单的给这个变量添加 .0
将其转变为浮点数。这时,你可以通过 times
过滤器将其转变为浮点数,并通过 assign
创建一个新变量来保存转换之后的浮点数。
下例中,除数是一个变量,保存的是一个整数,所以返回值也是一个整数:
{% assign my_integer = 7 %}
{{ 20 | divided_by: my_integer }}
→
2
下面,我们将这个变量乘以 1.0
来得到一个浮点数,然后将此浮点数作为除数进行运算:
{% assign my_integer = 7 %}
{% assign my_float = my_integer | times: 1.0 %}
{{ 20 | divided_by: my_float }}
→
2.857142857142857
downcase
用于将字符串中的各个字符转换为小写形式。对于已经是小写形式的字符串没有任何影响。
{{ "Parker Moore" | downcase }}
→
parker moore
{{ "apple" | downcase }}
→
apple
escape
对字符串转义操作就是将字符串中的某些字符替换为转义序列(escape sequence),这样整个字符串就能够用于 URL 了。如果字符串不需要转义则不会对字符串做任何操作。
{{ "Have you read 'James & the Giant Peach'?" | escape }}
→
Have you read 'James & the Giant Peach'?
{{ "Tetsuro Takara" | escape }}
→
Tetsuro Takara
escape_once
转义一个字符串并且不修改已经转义过的实体(entities)。对于无须转义的字符串不做任何修改。
{{ "1 < 2 & 3" | escape_once }}
→
1 < 2 & 3
{{ "1 < 2 & 3" | escape_once }}
→
1 < 2 & 3
first
返回数组的第一项。
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array.first }}
→
apples
{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
{{ my_array.first }}
→
zebra
floor
将一个浮点数通过舍弃小数部分得到最近的整数。在 floor 过滤器执行之前 Liquid 会先尝试将输入转换为数字格式。
{{ 1.2 | floor }}
→
1
{{ 2.0 | floor }}
→
2
{{ 183.357 | floor }}
→
183
以下实例所用输入是字符串:
{{ "3.5" | floor }}
→
3
join
将数组中的各个字符串合并为一个字符串,并将 split
参数作为字符串之间的分隔符。
{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{{ beatles | join: " and " }}
→join将数组中的各个字符串合并为一个字符串,并将 split 参数作为字符串之间的分隔符。输入{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}{{ beatles | join: " and " }}输出John and Paul and George and Ringo
John and Paul and George and Ringo
last
返回数组中的最后一项。
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array.last }}
→
plums
{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
{{ my_array.last }}
→
tiger
lstrip
删除字符串左侧的所有空白符(制表符、空格和换行符)。字符串中间的所有空白符不受影响。
{{ " So much room for activities! " | lstrip }}
→
So much room for activities!
map
从对象(object)中提取指定名称的属性的值,并用这些值构建一个数组。
以下实例中,假定 site.pages
包含了整个网站的元数据信息。利用 assign
和 map
过滤器创建一个变量,此变量只包含 site.pages
对象中 category
属性对应的所有值。
{% assign all_categories = site.pages | map: "category" %}
{% for item in all_categories %}
{{ item }}
{% endfor %}
→
business
celebrities
lifestyle
sports
technology
minus
从一个数中减去另一个数。
{{ 4 | minus: 2 }}
→
2
{{ 16 | minus: 4 }}
→
12
{{ 183.357 | minus: 12 }}
→
171.357
modulo
返回除法运算的余数。
{{ 3 | modulo: 2 }}
→
1
{{ 24 | modulo: 7 }}
→
3
{{ 183.357 | modulo: 12 }}
→
3.357
newline_to_br
将所有换行符(\n
) 替换为 HTML 的 (<br>
) 标签。
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | newline_to_br }}
→
<br />
Hello<br />
there<br />
plus
两个数相加。
{{ 4 | plus: 2 }}
→
6
{{ 16 | plus: 4 }}
→
20
{{ 183.357 | plus: 12 }}
→
195.357
prepend
在一个字符串前面附加另一个字符串。
{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}
→
Some fruit: apples, oranges, and bananas
prepend
也能作用于变量:
{% assign url = "example.com" %}
{{ "/index.html" | prepend: url }}
→
example.com/index.html
remove
从一个字符串中删除所有出现的另一个子字符串。
{{ "I strained to see the train through the rain" | remove: "rain" }}
→
I sted to see the t through the
remove_first
从一个字符串中仅仅删除第一次出现的另一个子字符串。
{{ "I strained to see the train through the rain" | remove_first: "rain" }}
→
I sted to see the train through the rain
replace
将参数中给出的第一个参数全部替换为第二个参数。
{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}
→
Take your protein pills and put your helmet on
replace_first
将字符串中出现的第一个参数替换为第二个参数。
{% assign my_string = "Take my protein pills and put my helmet on" %}
{{ my_string | replace_first: "my", "your" }}
→
Take your protein pills and put my helmet on
reverse
将数组中的所有项的顺序反转。reverse
不能操作字符串。
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array | reverse | join: ", " }}
→
plums, peaches, oranges, apples
reverse
不能直接应用到字符串上,但是你可以先将字符串分割成字符数组,然后再将数组反转,最后将反转之后的数组合并。
{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}
→
.moT rojaM ot lortnoc dnuorG
round
将浮点数舍入到最近的整数,或者,如果传入的参数是一个数值的话,将浮点数舍入到参数指定的小数位。
{{ 1.2 | round }}
→
1
{{ 2.7 | round }}
→
3
{{ 183.357 | round: 2 }}
→
183.36
rstrip
将字符串右侧的所有空白字符(制表符 - tab、空格符 - space 和 回车符 - newline)删除。
{{ " So much room for activities! " | rstrip }}
→
So much room for activities!
size
返回字符串中所包含的字符数或者数组中所包含的条目数量。size
还支持“点标记”(例如 {{ my_string.size }}
)。这种用法便于你在标签(tag)中使用 size
过滤器,例如条件判断标签(tag)。
{{ "Ground control to Major Tom." | size }}
→
28
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array | size }}
→
4
使用“点标记”:
{% if site.pages.size > 10 %}
This is a big website!
{% endif %}
slice
只传入一个参数时将返回此参数作为下标所对应的单个字符。第二个参数是可选的,用于指定返回的子字符串的长度。
String indices are numbered starting from 0.
{{ "Liquid" | slice: 0 }}
→
L
{{ "Liquid" | slice: 2 }}
→
q
{{ "Liquid" | slice: 2, 5 }}
→
quid
If the first parameter is a negative number, the indices are counted from the end of the string:
{{ "Liquid" | slice: -3, 2 }}
→
ui
sort
对数组中的所有进行排序。排序后的数组是按照区分大小写的顺序排列的。
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}
{{ my_array | sort | join: ", " }}
→
Sally Snake, giraffe, octopus, zebra
sort_natural
对数组进行排序,并且大小写无关。
{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}
{{ my_array | sort_natural | join: ", " }}
→
giraffe, octopus, Sally Snake, zebra
split
根据参数传入的分隔符将字符串分解为数组。split
通常被用于将以逗号为分隔符的字符串转换为数组。
{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{% for member in beatles %}
{{ member }}
{% endfor %}
→
John
Paul
George
Ringo
strip
删除字符串左右两侧的所有空白符号(包括制表符、空格、换行符)。对于字符串中间的空白符不做任何处理。
{{ " So much room for activities! " | strip }}
→So much room for activities!
strip_html
从字符串中删除所有 HTML 标签。
{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}
→
Have you read Ulysses?
strip_newlines
从字符串中删除所有换行字符(newline character)。
{% capture string_with_newlines %}
Hello
there
{% endcapture %}
{{ string_with_newlines | strip_newlines }}
→
Hellothere
times
将一个数乘以另一个数。
{{ 3 | times: 2 }}
→
6
{{ 24 | times: 7 }}
→
168
{{ 183.357 | times: 12 }}
→
2200.284
truncate
truncate
将字符串截短为指定的字符个数。如果指定的字符数量小于字符串的长度,则会在字符串末尾添加一个省略号(…) 并将此省略号计入字符个数中。
{{ "Ground control to Major Tom." | truncate: 20 }}
→
Ground control to...
自定义省略号
truncate
还支持第二个可选参数,用于指定一个字符序列,此字符序列将被添加到截短字符串的后面。默认是省略号(…),但是你可以按照你的需要传递一个新的。
第二个参数的长度将被计入第一个参数的字符个数中。例如,如果你希望将字符串截短为 10 个字符,并且使用由 3 个字符组成的省略号,这时,你需要将 truncate
的第一个参数设置为 13,是因为需要计入省略号的 3 个字符。
{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
→
Ground control, and so on
无省略号
你可以将字符串按照第一个参数截短为指定长度,并且可以通过传递一个空字符作为第二个参数,从而让截短之后的字符串不显示省略号。
{{ "Ground control to Major Tom." | truncate: 20, "" }}
→
Ground control to Ma
truncatewords
将字符串截短为指定的单词个数。如果指定的单词数量小于字符串中包含的单词个数,则会在字符串末尾添加一个省略号(…)。
{{ "Ground control to Major Tom." | truncatewords: 3 }}
→
Ground control to...
自定义省略号
truncatewords
还支持第二个可选参数,用于指定一个字符序列,此字符序列将被添加到截短字符串的后面。默认是省略号(…),但是你可以按照你的需要传递一个新的。
{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
→
Ground control to--
无省略号
如果你不希望在末尾添加省略号,可以将 truncatewords
的第二个参数设置为空字符串:
{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
→
Ground control to
uniq
删除数组中的所有冗余项。
{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " %}
{{ my_array | uniq | join: ", " }}
→
ants, bugs, bees
upcase
将字符串中的每个字符都转换为大写形式。对于已经全是大写的字符串不做任何操作。
{{ "Parker Moore" | upcase }}
→
PARKER MOORE
{{ "APPLE" | upcase }}
→
APPLE
url_decode
对于作为 URL 进行编码或通过 url_encode
编码的字符串进行解码。
{{ "%27Stop%21%27+said+Fred" | url_decode }}
→
'Stop!' said Fred
url_encode
将字符串中非 URL 安全的字符转换为百分号编码(percent-encoded)的字符。
{{ "john@liquid.com" | url_encode }}
→
john%40liquid.com
{{ "Tetsuro Takara" | url_encode }}
→
Tetsuro+Takara