页面数据筛选：query

用于站点 pages 的数据过滤

1. 支持的功能

1. 支持动态变量的不同数据过滤

2. 页面属性过滤

3. 内容检索(TODO)

4. 排序(TODO)

5. 分页(TODO)

2. 开始使用

2.1 基本语法

query 标签的基本语法：

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

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

在使用 JSON 格式的查询条件时，特别是对于动态值，使用者需要注意以下几点以确保正确的转义和格式：

1. 字符串转义：在 JSON 中，字符串需要用双引号包裹，且内部的双引号需要使用反斜杠 \\ 进行转义。例如："title": "这是一个\"示例\"标题"。

2. 反斜杠转义：如果字符串中包含反斜杠 \\，需要进行双重转义，即使用 \\\\。例如："path": "C:\\\\Users\\\\Example"。

3. 特殊字符：注意转义特殊字符，如换行符 \\n、制表符 \\t 等。

4. 动态变量：如果在 JSON 中使用动态变量，确保变量的值在插入时已经正确转义。例如："description": "{{ page.description | escape }}"。

5. 避免语法错误：确保 JSON 的结构正确，所有的键值对用逗号分隔，最后一个键值对后不应有逗号。

6. 使用工具：建议使用 JSON 格式化工具或库来自动处理转义和格式化，以减少手动错误。

通过注意这些细节，可以确保在使用 JSON 格式的查询条件时，动态值能够被正确解析和处理。

2.3 示例

{% query faq_pages from site.pages %}
  {
    "where": {
      "template_name_eq": "faq",
      "settings.description_start": "帮助"
    },
    "order_by": ["created_at desc"],
    "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: 创建时间

• visits_count: 访问次数

• edited_at: 编辑时间

• published_at: 发布时间

示例

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

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 desc"]
  }
{% endquery %}

3.4 q

• 用于指定内容检索的关键字。

• 格式为："q": "搜索关键词"。

示例

{% query search_results from site.pages %}
  {
    "q": "智能设备",
    "where": { "template_name_eq": "product" },
    "order_by": ["visits_count desc"],
    "limit": 10,
    "offset": 0
  }
{% endquery %}

4. 动态变量

4.1 动态变量筛选逻辑

1. 字段格式：字段名由 模板名:变量名_操作符 构成（如：description_start, 'templates/index.list.liquid:description_start'）。

2. 数据类型限制操作符：每个字段根据数据类型限制支持的操作符。

3. 支持 AND / OR 组合查询：可组合多条件查询。

4. 模糊模版匹配：若未指定模板路径，将查询所有模板下匹配变量并使用 OR 合并查询。

5. 可筛选字段：必须在页面 schema 的 settings 中标注 filterable: true 才支持该字段筛选。

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

在模板文件的 settings_schema 中添加 filterable: true：

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

4.3 动态变量数据类型

5. 页面属性

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 desc"],
    "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 %}