site name
道盒发布

内置过滤器

lower

转换字母为小写

upper

转换字母为大写

wordcount

输出单词的数量

capitalize

句子单词首字母大写

title

每个单词首字母大写

replace

替换字符串

{{ name | replace(from="Robert", to="Bob")}}

addslashes

引号转换

{{ set value = "I'm using Daobox" }}
{{ value | addslashes }}

输出 I\\'m using Daobox

slugify

转换为可命名的字符串

{{ set value = "-Hello world! " }}
{{ value | slugify }}

输出hello-world

trim

过滤两端空格

trim_start

过滤左侧空格

trim_end

过滤右侧空格

trim_start_matches

过滤左侧匹配正则

{{ set value = "//a/b/c//" }}
{{ value | trim_start_matches(pat="//") }}

输出a/b/c//

trim_end_matches

过滤左侧匹配正则

{{ set value = "//a/b/c//" }}
{{ value | trim_start_matches(pat="//") }}

输出//a/b/c

truncate

截取指定长度的字符串。长度不够则全保留。截取后尾部增加“…”，可以通过end参数修改后缀。

{{ value | truncate(length=10, end="") }}

linebreaksbr

替换换行符\n, \r\n 为<br>

spaceless

去除HTML标记内的空格与换行。

{% set value = "<p>\n<a> </a>\r\n </p>" %}
{{ value | spaceless }}

输出：<p><a></a></p>

striptags

过滤HTML标记

{% set value = "<b>Joel</b>" %}
{{ value | striptags }}

输出：Joel

first

返回列表第一个元素，如果列表为空，则返回空字符串。

last

返回列表最后一个元素，如果列表为空，则返回空字符串。

nth

返回列表第N（序号从0开始）个元素，如果列表为空，则返回空字符串。

{{ value | nth(n=2) }}

join

使用分隔符连接列表中的字符串

{% set value = ['a', 'b', 'c'] %}
{{ value | join(sep=" // ") }}

输出：a // b // c

length

返回列表、对象、字符串的长度

index_of

返回指定元素在列表中位置，从 0 开始。

参数

参数名 含义 类型 可选 说明
search 搜索的列表 元素列表

返回

整数。未找到时返回 -1。

e.g.

{% set s = "hello" %}
{{ s | index_of(search=["a", "b", "hello"]) }}

{# output: 2 #}

reverse

返回逆序排列的字符串或列表

sort

列表排序。列表中的元素必须是可排序的。

  • 数字按值大小
  • 字符串按Asc大小
  • 列表按其长度
  • 布尔值，真=1，假=0

如果列表元素时对象（键值对），可指定排序使用的属性

{% set people = [
  {
    "name": ["daobox", "yu"],
    "age": 30
  }
] %}

{# 按姓名第一个姓氏排序 #}
{{ people | sort(attribute="name.0") }}

{# 按年龄排序 #}
{{ people | sort(attribute="age") }}

unique

列表去重。用法同sort，当时参考值为字符串，可通过case_sensitive指定是否忽略大小写。

{{ people | unique(attribute="age") }}
{{ people | unique(attribute="name.1", case_sensitive="true") }}

slice

对列表切片。通过参数start，end指定开始与结束索引序号（0开始），返回从start开始（包括）至end结束（不包括）的子列表。两个参数均可省略，默认为两端位置。

{% for i in my_arr | slice(end=5) %}
{% for i in my_arr | slice(start=1) %}
{% for i in my_arr | slice(start=1, end=5) %}

使用小于0的序号表示从尾部倒数。

{% set  my_array = [1, 2, 3, 4, 5] %}
{{  my_arr | slice(end=-2) }}

结果是：[1, 2, 3]

group_by

对列表分组。指定attribute参数作为分组依据，返回以attribute值为键，对应值为属性相等的列表的对象（键值对）。如果元素缺少分组属性将被忽略。

如下对象定义（伪代码）

Author {
    name: String,
};

Post {
    content: String,
    year: u32,
    author: Author,
}

posts=[Post, Post]

按year分组

{{ posts | group_by(attribute="year") }}

按authore.name分组

{% for name, author_posts in posts | group_by(attribute="author.name") %}
    {{ name }}
    {% for post in author_posts %}
        {{ post.year }}: {{ post.content }}
    {% endfor %}
{% endfor %}

可以自定义分组

{% set map = section.pages | group_by(attribute="year") %}
{% set_global years = [] %}
{% for year, ignored in map %}
    {% set_global years = years | concat(with=year) %}
{% endfor %}
{% for year in years | reverse %}
    {% set posts = map[year] %}
{% endfor %}

filter

过滤列表。仅返回属性等于指定值元素列表。缺少属性或者为空的将忽略。

attribute参数是必须的，value可省略，表示过滤掉属性为空的元素。

Author {
    name: String,
};

Post {
    content: String,
    year: u32,
    author: Author,
    draft: bool,
}

{{ posts | filter(attribute="draft", value=true) }}
{{ posts | filter(attribute="author.name", value="Vincent") }}

map

提取每个元素的指定的属性，返回列表。

Name(String, String);

Person {
    name: Name,
    age: u32,
}

返回所有的年龄

{{ people | map(attribute="age") }}

concat

追加一个或一组元素到列表

{{ posts | concat(with=drafts) }}

urlencode

转码字符串为安全的人URL编码，根据RFC3986，/不参与转码。

{% set value = "/foo?a=b&c=d" %}
{{ value | urlencode }}

输出：/foo%3Fa%3Db%26c%3Dd

urlencode_strict

功能同urlencode，但转码包括/。

round

浮点数截取。

参数：

  • method：取值范围
    1. common：四舍五入（默认）
    2. ceil 向上截取
    3. floor 向下截取
  • precision：小数位数。默认为0

filesizeformat

整数转换为友好格式。

{{ num | filesizeformat }}

date

转化时间戳或者日期到指定日期格式。

{{ ts | date }} 
{{ ts | date(format="%Y-%m-%d %H:%M") }}

timezone参数可指定，省略时默认为Asia/Chongqing。

escape

转换特殊字符

  • & ⇒ &amp;
  • < ⇒ &lt;
  • > ⇒ &gt;
  • " ⇒ &quot;
  • ' ⇒ &#x27;
  • / ⇒ &#x2F;

escape_xml

转换XML特殊字符

  • & ⇒ &amp;
  • < ⇒ &lt;
  • > ⇒ &gt;
  • " ⇒ &quot;
  • ' ⇒ &#x27;

safe

通常的内容输出，默认会进行HTML特殊字符转码，safe可控制最后的内容不做HTML转码。

get

通过key取出对象中的值，支持多级。default参数可选，用来指定不存在key时返回的默认值。

{{ sections | get(key="posts/content", default="default") }}

split

将字符串按指定的分隔符切割为列表

{{ path | split(pat="/") }}

int

转换值为整数。值可识别前缀0b、0o、0x

参数：

  • default：可选。转换出错时使用的默认值。
  • base：可选。整数的位数。有效值为10、2、8、16。

float

转换为浮点数。可通过default参数指定转换出错时使用的默认值。

json_encode

转换为标准的json字符串，出于安全原因，道盒发布会自动转换HTML字符，因此可以搭配safe一起使用来禁止转码。

{{ value | json_encode | safe }}

参数：

  • pretty：可选。输出美化后的JSON串。有效值true或false
{{ value | json_encode(pretty=true) | safe }}

default

对未定义的变量提供默认值。

注意：仅对未定义的变量有效。对空字符串（""）、0、false无效。

I would like to read more {{ "" | default (value="Louise Michel") }}!

输出：I would like to read more !

json

将文本转换为JSON对象。

{{ value | json }}

markdown_html

别名 md_html, 将Markdown文本转换为HTML。

{{ value | md_html }}

thumbnail

自动生成缩略图

参数

键名 含义 类型 可选 说明
wxh 最大宽度x最大高度 字符串 ✔️ 省略时，降级使用配置项 cfg.thumbnail.default_dimension ，若未指定，则使用原图。高度和宽度可以指定其中一个，eg. 400x (限定宽度为400px) 或 x300 (限定高度为300px)。

返回

缩略图信息。

键名 含义 类型 可选 说明
url 缩略图地址 字符串
width 缩略图宽度 整数
height 缩略图高度 整数

object_keys

获取对象 key 列表

返回

[
    "<key>",
]

object_values

获取对象 value 列表

返回

[
    <value>,
]
内置断言
内置函数
关于道盒 鄂ICP备2023015790号