页面数据筛选:query

User 69e88e27

发布于:2025-04-11

用于站点 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

  • 用于指定查询条件,支持页面属性和动态变量的筛选。

  • 支持复杂的逻辑组合,如 andor

示例

"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 分页 limitoffset

  • 用于指定结果的分页

"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 动态变量数据类型

settings_type(表单类型)

数据类型

checkbox

boolean

color, color_background, font_picker, image_picker, link, radio, select, tag_picker, text, video_picker

multiple = true ? array : string

date

date

html, richtext, textarea

text

number, range

float

5. 页面属性

5.1 页面属性筛选逻辑

  1. 字段格式:字段名由 属性名_操作符 构成(如:visits_count_gt, 'created_at_lteq')。

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

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

  4. 可筛选字段:仅下面列出的字段支持筛选。

5.2 可用作筛选的页面属性

页面属性是指页面自身的属性,可用于筛选。支持的页面属性包括:

属性名

说明

数据类型

name

页面名称

string

visits_count

访问次数

integer

full_path

完整路径

string

template_name

模板名称

string

template_style

模板样式

string

updated_at

更新时间

datetime

created_at

创建时间

datetime

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

contains_all

包含所有指定值

数组

"tags_contains_all": ["热门", "促销"]

contains_any

包含任一指定值

数组

"tags_contains_any": ["热门", "促销"]

not_contains_all

不包含所有指定值

数组

"tags_not_contains_all": ["热门", "促销"]

array_equals

数组完全相等

数组

"tags_array_equals": ["热门", "促销"]

array_not_equals

数组不完全相等

数组

"tags_array_not_equals": ["热门", "促销"]

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

数据类型

支持的操作符

boolean

true, false

string

eq not_eq matches does_not_match matches_any matches_all does_not_match_any does_not_match_all in not_in start not_start start_any start_all not_start_any not_start_all end not_end end_any end_all not_end_any not_end_all cont cont_any cont_all not_cont not_cont_any not_cont_all i_cont i_cont_any i_cont_all not_i_cont not_i_cont_any not_i_cont_all

text

i_cont cont not_i_cont not_cont eq not_eq start not_start end not_end

date / datetime

eq, not_eq, lt, gt, lteq, gteq

float / integer

eq, not_eq, lt, gt, lteq, gteq

array

contains_all, not_contains_all, contains_any, array_equals, array_not_equals

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

提交反馈