页面数据筛选：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. 筛选操作符表及其解释

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 %}