可用的 Liquid 篩選

發行項
08/23/2023

Liquid 篩選用來修改字串、數字、變數和物件的輸出。它們會藉由 | 與要套用它們的值分隔。

{{ 'hal 9000' | upcase }} 

某些篩選可接受參數。篩選也可以結合，並且會從左到右依序套用。

{{ 2 | times: 2 | minus: 1 }} <!-- Output: 3 -->

{{ "Hello, " | append: user.firstname }} <!-- Output: Hello, Dave -->

下一節描述各種不同的篩選。

陣列篩選

陣列篩選用來搭配 arrays 使用。

batch

將陣列分成特定大小的多個陣列。

代碼

{% assign batches = entityview.records | batch: 2 %}

{% for batch in batches %}

<ul>

{% for item in batch %}

<li>{{ item.fullname }}</li>

{% endfor %}

</ul>

{% endfor %}

輸出

<ul>

<li>John Smith</li>

<li>Dave Thomas</li>

</ul>

<ul>

<li>Jake Johnson</li>

<li>Jack Robinson</li>

</ul>

concat

將兩個陣列串連成單一新陣列。

若指定單一項目做為參數，concat 會傳回新陣列，當中包含原始陣列，而指定的項目會是最後一個元素。

代碼

Group #1: {{ group1 | join: ', ' }}

Group #2: {{ group2 | join: ', ' }}

Group #1 + Group #2: {{ group1 | concat: group2 | join: ', ' }}

輸出

Group #1: John, Pete, Hannah

Group #2: Joan, Bill

Group #1 + Group #2: John, Pete, Hannah, Joan, Bill

except

選取陣列中的所有物件，其中所指屬性沒有所指的值。 (這是 where 的反轉。)

代碼

{% assign redmond = entityview.records | except: 'address1_city', 'Redmond' %}

{% for item in redmond %}

{{ item.fullname }}

{% endfor %}

輸出

Jack Robinson

第一

傳回陣列的第一個元素。

first 也可以搭配特殊點符號使用，當它需要在標籤內使用時。

代碼

{% assign words = This is a run of text | split:   %}

{{ words | first }}

{% if words.first == This %}

The first word is This.

{% endif %}

輸出

This

The first word is This.

group_by

根據特定屬性將陣列中的項目設為群組。

代碼

{% assign groups = entityview.records | group_by: 'address1_city' %}

{% for group in groups %}

{{ group.key }}:

{% for item in group.items %}

{{ item.fullname }}

{% endfor %}

{% endfor %}

輸出

Redmond:

John Smith

Dave Thomas

Jake Johnson

New York:

Jack Robinson

join

加入陣列的元素，並傳遞字元做為參數。結果是單一字串。

代碼

{% assign words = This is a run of text | split:   %}

{{ words | join: ,  }}

輸出

This, is, a, run, of, text

最後一

傳回陣列的最後一個元素。

last 也可以搭配特殊點符號使用，當它需要在標籤內使用時。

代碼

{% assign words = This is a run of text | split:   -%}

{{ words | last }}

{% if words.last == text -%}

The last word is text.

{% endif -%}

輸出

text

The last word is text.

order_by

傳回陣列的元素，依陣列元素的特定屬性排列。

您也可以選擇提供 desc 做為依遞減順序排序元素的第二個參數，而不是遞增排序。

代碼

{{ entityview.records | order_by: 'fullname' | join: ', ' }}

{{ entityview.records | order_by: 'fullname', 'desc' | join: ', ' }}

輸出

Dave Thomas, Jack Robinson, Jake Johnson, John Smith

John Smith, Jake Johnson, Jack Robinson, Dave Thomas

random

從陣列傳回單一隨機選取的項目。

代碼

{{ group1 | join: ', ' }}

{{ group1 | random }}

輸出

John, Pete, Hannah

Pete

選取

為陣列中的每一個項目選取特定屬性的值，並傳回這些值做為陣列。

代碼

{{ entityview.records | select: 'address1_city' | join: ', ' }}

輸出

Redmond, New York

shuffle

套用至陣列，會傳回具有相同項目的新陣列並隨機排列。

代碼

{{ group1 | join: ', ' }}

{{ group1 | shuffle | join: ', ' }}

輸出

John, Pete, Hannah

Hannah, John, Pete

size

傳回陣列中的項目數。

size 也可以搭配特殊點符號使用，當它需要在標籤內使用時。

代碼

{% assign words = This is a run of text | split:   -%}

{{ words | size }}

{% if words.size == 6 -%}

The text contains 6 words.

{% endif -%}

輸出

6

The text contains 6 words.

skip

跳過陣列中的特定項目數，並傳回其餘項目。

代碼

{% assign words = This is a run of text | split:   %}

{{ words | skip: 3 | join: ', ' }}

輸出

run, of, text

take

從陣列中取用特定項目數，傳回所取用的項目。

代碼

{% assign words = This is a run of text | split:   %}

{{ words | take: 3 | join: ', ' }}

輸出


This, is, a

then_by

對已依照 order_by 排列的陣列新增額外的後續順序。

您也可以選擇提供 desc 做為依遞減順序排序元素的第二個參數，而不是遞增排序。

代碼

{{ entityview.records | order_by: 'address1_city' | then_by: 'fullname' | join: ', ' }}

{{ entityview.records | order_by: 'address1_city' | then_by: 'fullname', 'desc' | join: ', ' }}

輸出

Dave Thomas, Jack Robinson, Jake Johnson, John Smith

John Smith, Jake Johnson, Jack Robinson, Dave Thomas

where

選取陣列中的所有物件，其中所指屬性有所指的值。

代碼

{% assign redmond = entityview.records | where: 'address1_city', 'Redmond' %}

{% for item in redmond %}

{{ item.fullname }}

{% endfor %}

輸出

John Smith

Dave Thomas

Jake Johnson

日期篩選

日期篩選可用於日期算術或將日期時間值轉換成各種格式。

日期

使用 .NET 格式字串將日期時間值格式化。

標準日期和時間格式字串

自訂日期和時間格式字串

代碼

{{ now | date: 'g' }}

{{ now | date: 'MMMM dd, yyyy' }}

輸出

5/7/2018 7:20 AM

May 07, 2018

date_add_days

新增指定數目的整數和分數天數至日期時間值。參數可以是正值或負值。

代碼

{{ now }}

{{ now | date_add_days: 1 }}

{{ now | date_add_days: -2.5 }}

輸出

5/7/2018 7:20:46 AM

5/8/2018 7:20:46 AM

5/4/2018 7:20:46 PM

date_add_hours

新增指定數目的整數和分數時數至日期時間值。參數可以是正值或負值。

代碼

{{ now }}

{{ now | date_add_hours: 1 }}

{{ now | date_add_hours: -2.5 }}

輸出

5/7/2018 7:20:46 AM

5/7/2018 8:20:46 AM

5/7/2018 4:50:46 AM

date_add_minutes

新增指定數目的整數和分數分鐘數至日期時間值。參數可以是正值或負值。

代碼

{{ now }}

{{ now | date_add_minutes: 10 }}

{{ now | date_add_minutes: -2.5 }}

輸出

5/7/2018 7:20:46 AM

5/7/2018 7:30:46 AM

5/7/2018 7:18:16 AM

date_add_months

新增指定數目的整數月份至日期時間值。參數可以是正值或負值。

代碼

{{ now }}

{{ now | date_add_months: 1 }}

{{ now | date_add_months: -2 }}

輸出

5/7/2018 7:20:46 AM

6/7/2018 7:20:46 AM

3/7/2018 7:20:46 AM

date_add_seconds

新增指定數目的整數和分數秒數至日期時間值。參數可以是正值或負值。

代碼

{{ now }}

{{ now | date_add_seconds: 10 }}

{{ now | date_add_seconds: -1.25 }}

輸出

5/7/2018 7:20:46 AM

5/7/2018 7:20:56 AM

5/7/2018 7:20:45 AM

date_add_years

新增指定數目的整數年份至日期時間值。參數可以是正值或負值。

代碼

{{ now }}

{{ now | date_add_years: 1 }}

{{ now | date_add_years: -2 }}

輸出

5/7/2018 7:20:46 AM

5/7/2019 7:20:46 AM

5/7/2016 7:20:46 AM

date_to_iso8601

根據 ISO 8601 標準格式化日期時間值。在建立 Atom 摘要或 HTML5 <time> 元素時很實用。

代碼

{{ now | date_to_iso8601 }}

輸出

2018-05-07T07:20:46Z

date_to_rfc822

根據 RFC 822 標準格式化日期時間值。在建立 RSS 摘要時很實用。

代碼

{{ now | date_to_rfc822 }}

輸出

Mon, 07 May 2018 07:20:46 Z

逸出篩選

逸出序列提供了一種在字串中包含特殊字元的方式，而不與程式設計語言或格式對這些字元的常規解釋發生衝突。

下列轉義篩選會以逸出序列取代字串字元，或根據目標類型移除無效的字串字元。

escape

HTML 逸出字串。

代碼

{{ '<p>test</p>' | escape }}

輸出

&lt;p&gt;test&lt;/p&gt;

html_safe_escape

將指定的 HTML 字串轉換為安全的 HTML 片斷。

代碼

{{ '<img src="images/myimage.jpg" onerror="alert(1);">' | html_safe_escape }}

輸出

<img src="images/myimage.jpg">

url_escape

URI 逸出字串，以便包含在 URL 中。

代碼

{{ 'This & that//' | url_escape }}

輸出

This+%26+that%2F%2F

xml_escape

XML 逸出字串，以便包含在 XML 輸出中。

代碼

{{ '<p>test</p>' | xml_escape }}

輸出

&lt;p&gt;test&lt;/p&gt;

清單篩選

清單篩選用來處理特定 entitylist 屬性值，以及協助建立清單檢視。

current_sort

提供排序運算式，傳回特定屬性目前的排序方向。

代碼

{{ 'name ASC, createdon DESC' | current_sort: 'createdon' }}

輸出

DESC

metafilters

將 entitylist filter_definition JSON 值剖析成篩選選項群組物件。

可以選擇為 metafilters 提供目前屬性篩選查詢和目前的 entitylist，允許將傳回的篩選物件標示為已選取或取消選取。

代碼

{% assign filters = entitylist | metafilters: params.mf, entityview %}
{% if filters.size > 0 %}
  <ul id=entitylist-filters>
    {% for filter in filters %}
      <li class=entitylist-filter-option-group>
        {% if filter.selection_mode == 'Single' %}
          {% assign type = 'radio' %}
        {% else %}
          {% assign type = 'checkbox' %}
        {% endif %}
        <h4 class=entitylist-filter-option-group-label
          data-filter-id={{ filter.id | h }}>
          {{ filter.label | h }}
        </h4>
        <ul>
          {% for option in filter.options %}
            <li class=entitylist-filter-option>
              {% if option.type == 'text' %}
                <div class=input-group entitylist-filter-option-text>
                  <span class=input-group-addon>
                    <span class=fa fa-filter aria-hidden=true></span>
                  </span>
                  <input class=form-control
                    type=text
                    name={{ filter.id | h }}
                    value={{ option.text | h }} />
                </div>
              {% else %}
                <div class={{ type | h }}>
                  <label>
                    <input
                      type={{ type | h }}
                      name={{ filter.id | h }}
                      value={{ option.id | h }}
                      {% if option.checked %}
                        checked=checked
                        data-checked=true{% endif %}
                      />
                    {{ option.label | h }}
                  </label>
                </div>
              {% endif %}
            </li>
          {% endfor %}
        </ul>
      </li>
    {% endfor %}
  </ul>
  <button class=btn btn-default data-serialized-query=mf data-target=#entitylist-filters>Apply Filters</button>
{% endif %}

reverse_sort

提供排序方向，傳回反向排序方向。

代碼

<!-- Sort direction is not case-sensitive -->

{{ 'ASC' | reverse_sort }}

{{ 'desc' | reverse_sort }}

輸出

DESC

ASC

數學篩選

數學篩選可讓您對 numbers 執行數學計算。

就像使用所有篩選一樣，數學篩選可以鏈接，並且會從左到右依序套用。

代碼

{{ 10 | times: 2 | minus: 5 | divided_by: 3 }}

輸出

ceil

將值向上捨入至最接近的整數。

代碼

{{ 4.6 | ceil }}

{{ 4.3 | ceil }}

輸出

5

5

divided_by

用另一個數字除某一數字。

代碼

{{ 10 | divided_by: 2 }}

{{ 10 | divided_by: 3 }}

{{ 10.0 | divided_by: 3 }}

輸出

floor

將值向下捨入至最接近的整數。

代碼

{{ 4.6 | floor }}

{{ 4.3 | floor }}

輸出

4

4

minus

將兩個數字相減。

代碼

<!-- entityview.page = 11 -->

{{ entityview.page | minus: 1 }}

{{ 10 | minus: 1.1 }}

{{ 10.1 | minus: 1 }}

輸出

modulo

以另一個數字除某一數字，並傳回餘數。

代碼

{{ 12 | modulo: 5 }}

輸出

plus

將兩個數字相加。

代碼

<!-- entityview.page = 11 -->

{{ entityview.page | plus: 1 }}

{{ 10 | plus: 1.1 }}

{{ 10.1 | plus: 1 }}

輸出

round

將值捨入至最接近的整數或指定的十進位數字。

代碼

{{ 4.6 | round }}

{{ 4.3 | round }}

{{ 4.5612 | round: 2 }}

輸出

times

將兩個數字相乘。

代碼

{{ 10 | times: 2 }}

{{ 10 | times: 2.2 }}

{{ 10.1 | times: 2 }}

輸出

字串篩選

字串篩選會操作 strings。

附加

附加字串至其他字串的結尾。

代碼

{{ 'filename' | append: '.js' }}

輸出

filename.js

capitalize

將字串中的每字都變成大寫。

代碼

{{ 'capitalize me' | capitalize }}

輸出

Capitalize Me

downcase

將字串轉換成小寫。

代碼

{{ 'MIxed Case TExt' | downcase }}

輸出

mixed case text

newline_to_br

插入 <br /> 換行 HTML 標籤，在字串中的每個換行處。

代碼

{% capture text %}

A

B

C

{% endcapture %}

{{ text | newline_to_br }}

輸出

A<br />

B<br />

C<br />

prepend

將字串附加至另一個字串的開頭。

代碼

{{ 'Jane Johnson' | prepend: 'Dr. ' }}

輸出

Dr. Jane Johnson

remove

從字串中移除所有出現的子字串。

代碼

{{ 'Hello, Dave. How are you, Dave?' | remove: 'Dave' }}

輸出

Hello, . How are you, ?

remove_first

從字串中移除出現的第一個子字串。

代碼

{{ 'Hello, Dave. How are you, Dave?' | remove_first: 'Dave' }}

輸出

Hello, . How are you, Dave?

replace

用子字串取代所有出現的字串。

代碼

{{ 'Hello, Dave. How are you, Dave?' | replace: 'Dave', 'John' }}

輸出

Hello, John. How are you, John?

replace_first

用子字串取代第一個出現的字串。

代碼

{{ 'Hello, Dave. How are you, Dave?' | replace_first: 'Dave', 'John' }}

輸出

Hello, John. How are you, Dave?

split

split 篩選會採用子字串做為參數。子字串會做為分隔符號用來將字串分割成陣列。

代碼

{% assign words = This is a demo of the split filter | split: ' ' %}

First word: {{ words.first }}

First word: {{ words[0] }}

Second word: {{ words[1] }}

Last word: {{ words.last }}

All words: {{ words | join: ', ' }}

輸出

First word: This

First word: This

Second word: is

Last word: filter

All words: This, is, a, demo, of, the, split, filter

strip_html

從字串中刪去所有 HTML 標籤。

代碼

<p>Hello</p>

輸出

Hello

strip_newlines

從字串中刪去任何換行符號。

代碼

{% capture text %}

A

B

C

{% endcapture %}

{{ text | strip_newlines }}

輸出

ABC

text_to_html

將純文字字串格式化為簡單的 HTML。文字會進行 HTML 編碼，文字區塊會以空行分隔並包裝在段落 <p> 標籤內，單行換行符號將被取代為 <br>，而 URL 會轉換成超連結。

代碼

{{ note.notetext | text_to_html }}

輸出

<p>This is the first paragraph of notetext. It contains a URL: <a href="https://example.com/" rel="nofollow">https://example.com</a></p>

<p>This is a second paragraph.</p>

truncate

截斷字串，分成特定字元數。省略符號 (...) 會附加至字串，並且包含在字串計數中。

代碼

{{ 'This is a long run of text.' | truncate: 10 }}

輸出

This is...

truncate_words

截斷字串，分成特定字數。省略符號 (...) 會附加至被截斷的字串。

代碼

{{ 'This is a long run of text.' | truncate_words: 3 }}

輸出

This is a...

upcase

將字串轉換成大寫。

代碼

{{ 'MIxed Case TExt' | upcase }}

輸出

MIXED CASE TEXT

類型篩選

類型篩選可讓您將某一種類型的值轉換成其他類型。

boolean

嘗試將字串值轉換成布林值。如果值已是布林值，則會原封不動傳回。如果值無法轉換成布林值，則會傳回 Null。

此篩選也會將「開啟」、「已啟用」或「是」接受為 true，並將「關閉」、「已停用」和「否」接受為 false。

代碼

{{ true | boolean }}

{{ 'false' | boolean }}

{{ 'enabled' | boolean }}

{{ settings['something/enabled'] | boolean | default: false }}

輸出

true

false

true

false

decimal

嘗試將字串值轉換成十進位數字。如果值已是十進位數字，則會原封不動傳回。如果值無法轉換成十進位數字，則會傳回 Null。

代碼

{{ 10.1 | decimal }}

{{ '3.14' | decimal }}

{{ 'text' | decimal | default: 3.14 }}

輸出

integer

嘗試將字串值轉換成整數。如果值已是整數，則會原封不動傳回。如果值無法轉換成整數，則會傳回 Null。

代碼

{{ 10 | integer }}

{{ '10' | integer }}

{{ '10.1' | integer }}

{{ 'text' | integer | default: 2 }}

輸出

string

嘗試將值轉換成其字串表示。如果值已是字串，則會原封不動傳回。如果值是 null，則會傳回 null。

URL 篩選

URL 篩選可讓您建置或擷取 URL 的部分。

add_query

附加查詢字串參數至 URL。如果參數已在 URL 中，參數值會更新。

如果此篩選套用至完整絕對 URL，更新的絕對 URL 將會是結果。如果套用至路徑，更新的路徑將會是結果。

代碼

{{ 'https://example.com/path?page=1' | add_query: 'foo', 'bar' }}

{{ '/path?page=1' | add_query: 'page', 2 }}

輸出

https://example.com/path?page=1&foo=bar

/path?page=2

base

取得特定 URL 的基底 URL。

代碼

{{ 'https://example.com/path?foo=bar&page=2' | base }}

輸出

https://example.com

host

取得 URL 的主機部分。

代碼

{{ 'https://example.com/path?foo=bar&page=2' | host }}

輸出

example.com

path

取得 URL 的路徑部分。

代碼

{{ 'https://example.com/path?foo=bar&page=2' | path }}

{{ '/path?foo=bar&page=2' | path }}

輸出

/path

/path

path_and_query

取得 URL 的路徑和查詢部分。

代碼

{{ 'https://example.com/path?foo=bar&page=2' | path_and_query }}

{{ '/path?foo=bar&page=2' | path_and_query }}

輸出

/path?foo=bar&page=2

/path?foo=bar&page=2

port

取得 URL 的連接埠號碼。

代碼

{{ 'https://example.com/path?foo=bar&page=2' | port }}

{{ 'https://example.com/path?foo=bar&page=2' | port }}

{{ 'https://example.com:9000/path?foo=bar&page=2' | port }}

輸出

remove_query

從 URL 移除查詢字串參數。如果參數不存在 URL 中，URL 將原封不動傳回。