页面数据筛选：query

用于站点 pages 的数据过滤

1. 支持的功能

1. 支持筛选页面定义的动态变量数据进行页面过滤
2. 支持通过页面属性进行页面过滤
3. 排序
4. 分页

2. 开始使用

2.1 基本语法

{% query 结果变量名 from site.pages %}
  JSON格式的查询条件
{% endquery %}

2.2 JSON 参数中的转义注意事项

1. 字符串转义：在 JSON 中，字符串需要用双引号包裹，且内部的双引号需要使用反斜杠 \\ 进行转义。例如："title": "这是一个\"示例\"标题"。
2. 反斜杠转义：如果字符串中包含反斜杠 \\，需要进行双重转义，即使用 \\\\。例如："path": "C:\\\\Users\\\\Example"。
3. 特殊字符：注意转义特殊字符，如换行符 \\n、制表符 \\t 等。
4. 避免语法错误：确保 JSON 的结构正确，所有的键值对用逗号分隔，最后一个键值对后不应有逗号。
5. 使用工具：建议使用 JSON 格式化工具或库来自动处理转义和格式化，以减少手动错误。

2.3 示例

{% query faq_pages from site.pages %}
  {
    "where": {
      "template_name_eq": "page",
      "settings.var_name_matches": params.any_string,
      "settings.description_start": "帮助"
    },
    "order_by": ["-created_at"],
    "limit": 10,
    "offset": 0
  }
{% endquery %}

<!-- 使用筛选后的结果 -->
{% for page in faq_pages %}
  <a href="{{ page.url }}">{{ page.title }}</a>
{% endfor %}

3. 参数说明

3.1 where

• 用于指定查询条件，支持页面属性和动态变量的筛选。
• 支持复杂的逻辑组合，如 and 和 or。

示例

"where": {
  "属性名_操作符": 值,
  "settings.变量名_操作符": 值,
  "settings.模版文件完整路径:变量名_操作符": 值, // 指定检索使用某模版创建的页面中动态变量的数据
  "and": {
    // 嵌套的AND条件
  },
  "or": {
    // 嵌套的OR条件
  }
}

"where": {
  "template_name_eq": "product",
  "or": {
    "name_start": "文章标题",
    "settings.description_cont": "智能设备"
  }
}

3.2 order_by

• 用于指定结果的排序规则。
• 格式为：["字段名", ...]。

排序方向

• 升序（默认）：直接使用字段名，如 "created_at"
• 降序：在字段名前加 - 前缀，如 "-created_at"

支持的排序字段

• created_at: 创建时间
• visits_count: 访问次数
• edited_at: 编辑时间
• published_at: 发布时间

示例

"order_by": ["-visits_count", "created_at"]

3.3 分页 limit 和 offset

• 用于指定结果的分页

"limit": 10,
"offset": 20

示例

{% assign page_size = 10 %}
{% assign current_page = params.page | default: 1 | floor %}
{% assign offset = page_size | times: current_page | minus: page_size %}

{% query paginated_results from site.pages %}
  {
    "where": { "template_name_eq": "article" },
    "limit": {{ page_size }},
    "offset": {{ offset }},
    "order_by": ["-created_at"]
  }
{% endquery %}

4. where - 页面动态变量

4.1 动态变量筛选逻辑

1. 字段格式：字段名由 模板名:变量名_操作符 构成（如：description_start, 'templates/index.list.liquid:description_start'）。
2. 数据类型限制操作符：每个字段根据数据类型限制支持的操作符。
3. 支持 AND / OR 组合查询：可组合多条件查询。
4. 模糊模版匹配：若未指定模板路径，将查询所有模板下匹配变量并使用 OR 合并查询。
5. 可筛选字段：必须在页面 schema 的 settings 中标注 queryable: true 才支持该字段筛选。

4.2 设置模板可用于筛选的动态变量

{% schema %}
{
  "name": "Help Center",
  "settings": [
    {
      "id": "description",
      "type": "textarea",
      "label": "描述",
      "queryable": true
    }
  ]
}
{% endschema %}

4.3 动态变量数据类型

5. where - 页面属性

5.1 页面属性筛选逻辑

1. 字段格式：字段名由 属性名_操作符 构成（如：visits_count_gt, 'created_at_lteq'）。
2. 数据类型限制操作符：每个字段根据数据类型限制支持的操作符。
3. 支持 AND / OR 组合查询：可组合多条件查询。
4. 可筛选字段：仅下面列出的字段支持筛选。

5.2 可用作筛选的页面属性

6. 筛选操作符表及其解释

| 操作符 | 含义 | 适用类型 | 例如 |
|--------|------|----------|------|
| `eq` | 等于 | 所有类型 | `"name_eq": "产品"` |
| `not_eq` | 不等于 | 所有类型 | `"name_not_eq": "产品"` |
| `lt` | 小于 | 数值、日期 | `"visits_count_lt": 100` |
| `gt` | 大于 | 数值、日期 | `"visits_count_gt": 100` |
| `lteq` | 小于等于 | 数值、日期 | `"created_at_lteq": "2023-01-01"` |
| `gteq` | 大于等于 | 数值、日期 | `"created_at_gteq": "2023-01-01"` |
| `cont` | 包含(区分大小写) | 字符串 | `"title_cont": "关键词"` |
| `i_cont` | 包含(忽略大小写) | 字符串 | `"title_i_cont": "关键词"` |
| `not_cont` | 不包含(区分大小写) | 字符串 | `"title_not_cont": "关键词"` |
| `not_i_cont` | 不包含(忽略大小写) | 字符串 | `"title_not_i_cont": "关键词"` |
| `start` | 以...开头 | 字符串 | `"name_start": "产品"` |
| `not_start` | 不以...开头 | 字符串 | `"name_not_start": "产品"` |
| `end` | 以...结尾 | 字符串 | `"name_end": "产品"` |
| `not_end` | 不以...结尾 | 字符串 | `"name_not_end": "产品"` |
| `matches` | 正则匹配 | 字符串 | `"name_matches": "^产品.*"` |
| `does_not_match` | 正则不匹配 | 字符串 | `"name_does_not_match": "^产品.*"` |
| `matches_any` | 任意正则匹配 | 字符串 | `"name_matches_any": ["^产品.*", ".*服务$"]` |
| `matches_all` | 所有正则匹配 | 字符串 | `"name_matches_all": ["^产品.*", ".*服务$"]` |
| `does_not_match_any` | 任意正则不匹配 | 字符串 | `"name_does_not_match_any": ["^产品.*", ".*服务$"]` |
| `does_not_match_all` | 所有正则不匹配 | 字符串 | `"name_does_not_match_all": ["^产品.*", ".*服务$"]` |
| `in` | 在集合中 | 字符串 | `"name_in": ["产品1", "产品2"]` |
| `not_in` | 不在集合中 | 字符串 | `"name_not_in": ["产品1", "产品2"]` |
| `start_any` | 任意以...开头 | 字符串 | `"name_start_any": ["产品", "服务"]` |
| `start_all` | 所有以...开头 | 字符串 | `"name_start_all": ["产品", "服务"]` |
| `not_start_any` | 任意不以...开头 | 字符串 | `"name_not_start_any": ["产品", "服务"]` |
| `not_start_all` | 所有不以...开头 | 字符串 | `"name_not_start_all": ["产品", "服务"]` |
| `end_any` | 任意以...结尾 | 字符串 | `"name_end_any": ["产品", "服务"]` |
| `end_all` | 所有以...结尾 | 字符串 | `"name_end_all": ["产品", "服务"]` |
| `not_end_any` | 任意不以...结尾 | 字符串 | `"name_not_end_any": ["产品", "服务"]` |
| `not_end_all` | 所有不以...结尾 | 字符串 | `"name_not_end_all": ["产品", "服务"]` |
| `cont_any` | 任意包含(区分大小写) | 字符串 | `"name_cont_any": ["产品", "服务"]` |
| `cont_all` | 所有包含(区分大小写) | 字符串 | `"name_cont_all": ["产品", "服务"]` |
| `not_cont_any` | 任意不包含(区分大小写) | 字符串 | `"name_not_cont_any": ["产品", "服务"]` |
| `not_cont_all` | 所有不包含(区分大小写) | 字符串 | `"name_not_cont_all": ["产品", "服务"]` |
| `i_cont_any` | 任意包含(忽略大小写) | 字符串 | `"name_i_cont_any": ["产品", "服务"]` |
| `i_cont_all` | 所有包含(忽略大小写) | 字符串 | `"name_i_cont_all": ["产品", "服务"]` |
| `not_i_cont_any` | 任意不包含(忽略大小写) | 字符串 | `"name_not_i_cont_any": ["产品", "服务"]` |
| `not_i_cont_all` | 所有不包含(忽略大小写) | 字符串 | `"name_not_i_cont_all": ["产品", "服务"]` |
| `true` | 为真 | 布尔值 | `"is_active_true": true` |
| `false` | 为假 | 布尔值 | `"is_active_false": false` |
| `array_cont_all` | 包含所有指定值 | 数组 | `"array_cont_all": ["热门", "促销"]` |
| `not_array_cont_all` | 不包含所有指定值 | 数组 | `"not_array_cont_all": ["热门", "促销"]` |
| `array_cont_any` | 包含任一指定值 | 数组 | `"array_cont_any": ["热门", "促销"]` |
| `not_array_cont_any` | 不包含任一指定值 | 数组 | `"not_array_cont_any": ["热门", "促销"]` |
| `array_equals` | 数组完全相等 | 数组 | `"array_equals": ["热门", "促销"]` |
| `not_array_equals` | 数组不完全相等 | 数组 | `"not_array_equals": ["热门", "促销"]` |

7. 数据类型可允许的操作符

8. 完整示例

{% query featured_products from site.pages %}
  {
    "where": {
      "and": {
        "template_name_eq": "product",
        "settings.featured_true": true
      },
      "or": {
        "settings.category_eq": "电子产品",
        "settings.tags_contains_any": ["热门", "促销"]
      }
    },
    "order_by": ["visits_count"],
    "limit": 5,
    "offset": 0
  }
{% endquery %}

{% for product in featured_products %}
  <div class="product">
    <h3>{{ product.title }}</h3>
    <p>{{ product.settings.description }}</p>
    <a href="{{ product.url }}">查看详情</a>
  </div>
{% endfor %}