feat: group_by/group_by_exp/find/find_exp from Jekyll, #443

2026-09-20 23:10:41 -07:00 · 2024-04-14 19:34:07 +08:00
parent 258780e9a8
commit 2b713b721d
29 changed files with 775 additions and 35 deletions
@@ -0,0 +1,25 @@
+---
+title: find
+---
+
+{% since %}v10.11.0{% endsince %}
+
+在数组中找到给定的属性为给定的值的第一个元素并返回；如果没有这样的元素则返回 `nil`。对于 `members` 数组：
+
+```javascript
+const members = [
+  { graduation_year: 2013, name: 'Jay' },
+  { graduation_year: 2014, name: 'John' },
+  { graduation_year: 2014, name: 'Jack' }
+]
+```
+
+输入
+```liquid
+{{ members | find: "graduation_year", 2014 | json }}
+```
+
+输出
+```text
+{"graduation_year":2014,"name":"John"}
+```
@@ -0,0 +1,25 @@
+---
+title: find_exp
+---
+
+{% since %}v10.11.0{% endsince %}
+
+找到数组中给定的表达式值为 `true` 的第一个元素，如果没有这样的元素则返回 `nil`。对于下面的 `members` 数组：
+
+```javascript
+const members = [
+  { graduation_year: 2013, name: 'Jay' },
+  { graduation_year: 2014, name: 'John' },
+  { graduation_year: 2014, name: 'Jack' }
+]
+```
+
+输入
+```liquid
+{{ members | find_exp: "item", "item.graduation_year == 2014" | json }}
+```
+
+输出
+```text
+{"graduation_year":2014,"name":"John"}
+```
@@ -0,0 +1,48 @@
+---
+title: group_by
+---
+
+{% since %}v10.11.0{% endsince %}
+
+把数组元素按照给定的属性的值分组。对于 `members` 数组：
+
+```javascript
+const members = [
+  { graduation_year: 2003, name: 'Jay' },
+  { graduation_year: 2003, name: 'John' },
+  { graduation_year: 2004, name: 'Jack' }
+]
+```
+
+输入
+```liquid
+{{ members | group_by: "graduation_year" | json: 2 }}
+```
+
+输出
+```text
+[
+  {
+    "name": 2003,
+    "items": [
+      {
+        "graduation_year": 2003,
+        "name": "Jay"
+      },
+      {
+        "graduation_year": 2003,
+        "name": "John"
+      }
+    ]
+  },
+  {
+    "name": 2004,
+    "items": [
+      {
+        "graduation_year": 2004,
+        "name": "Jack"
+      }
+    ]
+  }
+]
+```
@@ -0,0 +1,48 @@
+---
+title: group_by_exp
+---
+
+{% since %}v10.11.0{% endsince %}
+
+把数组元素按照给定的 Liquid 表达式的值分组。对于 `members` 数组：
+
+```javascript
+const members = [
+  { graduation_year: 2013, name: 'Jay' },
+  { graduation_year: 2014, name: 'John' },
+  { graduation_year: 2009, name: 'Jack' }
+]
+```
+
+输入
+```liquid
+{{ members | group_by_exp: "item", "item.graduation_year | truncate: 3, ''" | json: 2 }}
+```
+
+输出
+```text
+[
+  {
+    "name": "201",
+    "items": [
+      {
+        "graduation_year": 2013,
+        "name": "Jay"
+      },
+      {
+        "graduation_year": 2014,
+        "name": "John"
+      }
+    ]
+  },
+  {
+    "name": "200",
+    "items": [
+      {
+        "graduation_year": 2009,
+        "name": "Jack"
+      }
+    ]
+  }
+]
+```
@@ -16,3 +16,24 @@ title: json
 ```text
 ["foo","bar","coo"]
 ```
+
+## 格式化
+
+{% since %}v10.11.0{% endsince %}
+
+可以指定一个 `space` 参数来格式化 JSON。
+
+Input
+```liquid
+{% assign arr = "foo bar coo" | split: " " %}
+{{ arr | json: 4 }}
+```
+
+Output
+```text
+[
+    "foo",
+    "bar",
+    "coo"
+]
+```
@@ -12,7 +12,7 @@ LiquidJS 共支持 40+ 个过滤器，可以分为如下几类：
 数学 | plus, minus, modulo, times, floor, ceil, round, divided_by, abs, at_least, at_most
 字符串 | append, prepend, capitalize, upcase, downcase, strip, lstrip, rstrip, strip_newlines, split, replace, replace_first, replace_last, remove, remove_first, remove_last, truncate, truncatewords
 HTML/URI | escape, escape_once, url_encode, url_decode, strip_html, newline_to_br
-数组 | slice, map, sort, sort_natural, uniq, wheres, first, last, join, reverse, concat, compact, size, push, pop, shift, unshift
+数组 | slice, map, sort, sort_natural, uniq, where, group_by, group_by_exp, find, find_exp, first, last, join, reverse, concat, compact, size, push, pop, shift, unshift
 日期 | date
 其他 | default, json

@@ -79,4 +79,29 @@ Featured product: {{ new_shirt.title }}
 Featured product: Hawaiian print sweater vest
 ```

+此外 `property` 可以是任意合法的变量表达式，就像在**输出**结构中一样，只是它的上下文是数组的每一个元素。对于下面的 `products` 数组：
+
+```javascript
+const products = [
+    { meta: { details: { class: 'A' } }, order: 1 },
+    { meta: { details: { class: 'B' } }, order: 2 },
+    { meta: { details: { class: 'B' } }, order: 3 }
+]
+```
+
+输入
+```liquid
+{% assign selected = products | where: 'meta.details["class"]', "B" %}
+{% for item in selected -%}
+- {{ item.order }}
+{% endfor %}
+```
+
+输出
+```text
+- 2
+- 3
+```
+
+
 [truthy]: ../tutorials/truthy-and-falsy.html
@@ -29,10 +29,14 @@ LiquidJS 一直很重视兼容于 Ruby 版本的 Liquid。Liquid 模板语言最
 * 对象的迭代顺序。JavaScript 对象的迭代顺序是插入顺序和数字键递增顺序的组合，但 Ruby Hash 中只是插入顺序（JavaScript 字面量 Object 和 Ruby 字面量 Hash 的插入顺序解释也不同）。
 * 排序稳定性。shopify/liquid 和 LiquidJS 都没有定义 [sort][sort] 过滤器的稳定性在，它取决于 Ruby/JavaScript 内置的排序算法，在 Node.js 12+ 和 Google Chrome 70+ LiquidJS 的排序是 [稳定的][stable-sort]。
 * shopify/liquid 允许过滤器尾部的未匹配字符，但 LiquidJS 不允许。这就是说如果过滤器参数前忘记写冒号比如 `{%raw%}{{ "a b" | split " "}}{%endraw%}` LiquidJS 会抛出异常。这是为了提升 Liquid 模板的易用性，参考 [#208][#208] 和 [#212][#212]。
-* LiquidJS 有额外的标签：[layout][layout] 和相应的 `block`。
-* LiquidJS 有额外的过滤器：[json][json]。
+* LiquidJS 比 [Liquid 语言][liquid] 有更多的标签和过滤器：
+    * LiquidJS 自己定义的标签：[layout][layout]、[render][render] 和相应的 `block`。
+    * LiquidJS 自己定义的过滤器：[json][json]。
+    * 从 [Shopify][shopify-tags] 借来的不依赖 Shopify 平台的标签/过滤器。
+    * 从 [Jekyll][jekyll-filters] 借来的不依赖 Jekyll 框架的标签/过滤器。

-[layout]: https://liquidjs.com/tags/layout.html
+[layout]: ../tags/layout.html
+[render]: ../tags/render.html
 [json]: https://liquidjs.com/filters/json.html
 [#26]: https://github.com/harttle/liquidjs/pull/26
 [#59]: https://github.com/harttle/liquidjs/issues/59
@@ -46,3 +50,6 @@ LiquidJS 一直很重视兼容于 Ruby 版本的 Liquid。Liquid 模板语言最
 [plugins]: ./plugins.html#插件列表
 [ruby-liquid]: https://github.com/Shopify/liquid
 [afs]: https://liquidjs.com/tutorials/render-file.html#Abstract-File-System
+[liquid]: https://shopify.github.io/liquid/basics/introduction/
+[shopify-tags]: https://shopify.dev/docs/api/liquid/tags
+[jekyll-filters]: https://jekyllrb.com/docs/liquid/filters/
@@ -0,0 +1,76 @@
+---
+title: 转义
+---
+
+LiquidJS 种转义有两种含义：
+
+1. 输出语言的转义，即 HTML 转义。用来让输出的变量不包含 HTML 特殊字符，不影响 HTML 的结构，也就是输出 HTML 安全的字符串。
+2. 语言自己的转义，即 Liquid 转义。用来输出包含对于 Liquid 语言来说是特殊字符的字符串，比如你在使用 Liquid 模板语言来编写一篇介绍 Liquid 语法的文章时就会需要 Liquid 转义。
+
+## HTML 转义
+
+默认情况下输出是不转义的，但你可以用 [escape][escape] 过滤器来做 HTML 转义：
+
+输入
+```liquid
+{{ "1 < 2" | escape }}
+```
+
+输出
+```text
+1 &lt; 2
+```
+
+LiquidJS 也提供了其他过滤器来支持不同的转义需求：[escape_once][escape_once], [newline_to_br][newline_to_br], [strip_html][strip_html]。
+
+当输出的变量不被信任时，可以把 [outputEscape][outputEscape] 参数设置为 `"escape"` 来启用默认 HTML 转义。这种情况下，如果你需要某个输出不被转义，则需要使用 [raw][raw] 过滤器：
+
+输入
+```liquid
+{{ "1 < 2" }}
+{{ "<button>OK</button>" | raw }}
+```
+
+输出
+```text
+1 &lt; 2
+<button>OK</button>
+```
+
+## Liquid 转义
+
+为了输出 Liquid 的特殊字符比如 `{{` 和 `{%`，你需要 [raw][raw] 标签。
+
+输入
+```liquid
+{% raw %}
+  In LiquidJS, {{ this | escape }} will be HTML-escaped, but
+  {{{ that }}} will not.
+{% endraw %}
+```
+
+输出
+```text
+In LiquidJS, {{ this | escape }} will be HTML-escaped, but
+{{{ that }}} will not.
+```
+
+Within strings literals in LiquidJS template, `\` can be used to escape special characters in string syntax. For example:
+
+输入
+```liquid
+{{ "\"" }}
+```
+
+输出
+```liquid
+"
+```
+
+[outputEscape]: ./options.html#outputEscape
+[escape]: ../filters/escape.html
+[raw]: ../filters/raw.html
+[escape_once]: ../filters/escape.html
+[strip_html]: ../filters/strip_html.html
+[newline_to_br]: ../filters/newline_to_br.html
+[raw]: ../tags/raw.html
@@ -100,6 +100,14 @@ LiquidJS 把这个选项默认值设为 <code>true</code> 以兼容于 shopify/l

 例如，空字符串在 JavaScript 中为假（`jsTruthy` 为 `true` 时），在 Shopify 真值表中为真。

+## outputEscape
+
+[outputEscape][outputEscape] 用来自动转义输出。它的值可以是 `"escape"`、`"json"` 或 `(val: unknown) => string`，默认为 `undefined`。
+
+- 如果被输出的变量不被信任，可以设置 `outputEscape: "escape"` 来自动把它们 HTML 转义。如果要直接输出则需要使用 [raw][raw] 过滤器。
+- 如果你在用 LiquidJS 来生产 JSON 文件，可以设置为 `"json"`。
+- `outputEscape` 甚至可以是函数，你可以借此控制整个 LiquidJS 的变量输出。注意函数的输入不一定是字符串，因为过滤器的返回值可以不是字符串，你的函数将会接到这个值。
+
 ## 时间日期和时区

 **timezoneOffset** 用来指定一个和你当地时区不同的时区，所有日期和时间输出时都转换到这个指定的时区。例如设置 `timezoneOffset: 0` 将会把所有日期按照 UTC/GMT 00:00 来输出。
@@ -147,3 +155,5 @@ LiquidJS 把这个选项默认值设为 <code>true</code> 以兼容于 shopify/l
 [wc]: ./whitespace-control.html
 [intro]: ./intro-to-liquid.html
 [jekyllInclude]: /api/interfaces/LiquidOptions.html#jekyllInclude
+[raw]: ../filters/raw.html
+[outputEscape]: /api/interfaces/LiquidOptions.html#outputEscape