页面数据筛选:query
User 69e88e27
发布于:2025-04-11
用于站点
pages
的数据过滤
1. 支持的功能
支持动态变量的不同数据过滤
页面属性过滤
内容检索(TODO)
排序(TODO)
分页(TODO)
2. 开始使用
2.1 基本语法
query
标签的基本语法:
{% query 结果变量名 from site.pages %}
JSON格式的查询条件
{% endquery %}
2.2 JSON 参数中的转义注意事项
在使用 JSON 格式的查询条件时,特别是对于动态值,使用者需要注意以下几点以确保正确的转义和格式:
字符串转义:在 JSON 中,字符串需要用双引号包裹,且内部的双引号需要使用反斜杠
\\
进行转义。例如:"title": "这是一个\"示例\"标题"
。反斜杠转义:如果字符串中包含反斜杠
\\
,需要进行双重转义,即使用\\\\
。例如:"path": "C:\\\\Users\\\\Example"
。特殊字符:注意转义特殊字符,如换行符
\\n
、制表符\\t
等。动态变量:如果在 JSON 中使用动态变量,确保变量的值在插入时已经正确转义。例如:
"description": "{{ page.description | escape }}"
。避免语法错误:确保 JSON 的结构正确,所有的键值对用逗号分隔,最后一个键值对后不应有逗号。
使用工具:建议使用 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 动态变量筛选逻辑
字段格式:字段名由
模板名:变量名_操作符
构成(如:description_start
, 'templates/index.list.liquid:description_start')。数据类型限制操作符:每个字段根据数据类型限制支持的操作符。
支持 AND / OR 组合查询:可组合多条件查询。
模糊模版匹配:若未指定模板路径,将查询所有模板下匹配变量并使用
OR
合并查询。可筛选字段:必须在页面 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 页面属性筛选逻辑
字段格式:字段名由
属性名_操作符
构成(如:visits_count_gt
, 'created_at_lteq')。数据类型限制操作符:每个字段根据数据类型限制支持的操作符。
支持 AND / OR 组合查询:可组合多条件查询。
可筛选字段:仅下面列出的字段支持筛选。
5.2 可用作筛选的页面属性
页面属性是指页面自身的属性,可用于筛选。支持的页面属性包括:
属性名 | 说明 | 数据类型 |
---|---|---|
name | 页面名称 | string |
visits_count | 访问次数 | integer |
full_path | 完整路径 | string |
template_name | 模板名称 | string |
template_style | 模板样式 | string |
updated_at | 更新时间 | datetime |
created_at | 创建时间 | datetime |
6. 筛选操作符表及其解释
操作符 | 含义 | 适用类型 | 例如 |
---|---|---|---|
| 等于 | 所有类型 |
|
| 不等于 | 所有类型 |
|
| 小于 | 数值、日期 |
|
| 大于 | 数值、日期 |
|
| 小于等于 | 数值、日期 |
|
| 大于等于 | 数值、日期 |
|
| 包含(区分大小写) | 字符串 |
|
| 包含(忽略大小写) | 字符串 |
|
| 不包含(区分大小写) | 字符串 |
|
| 不包含(忽略大小写) | 字符串 |
|
| 以...开头 | 字符串 |
|
| 不以...开头 | 字符串 |
|
| 以...结尾 | 字符串 |
|
| 不以...结尾 | 字符串 |
|
| 正则匹配 | 字符串 |
|
| 正则不匹配 | 字符串 |
|
| 任意正则匹配 | 字符串 |
|
| 所有正则匹配 | 字符串 |
|
| 任意正则不匹配 | 字符串 |
|
| 所有正则不匹配 | 字符串 |
|
| 在集合中 | 字符串 |
|
| 不在集合中 | 字符串 |
|
| 任意以...开头 | 字符串 |
|
| 所有以...开头 | 字符串 |
|
| 任意不以...开头 | 字符串 |
|
| 所有不以...开头 | 字符串 |
|
| 任意以...结尾 | 字符串 |
|
| 所有以...结尾 | 字符串 |
|
| 任意不以...结尾 | 字符串 |
|
| 所有不以...结尾 | 字符串 |
|
| 任意包含(区分大小写) | 字符串 |
|
| 所有包含(区分大小写) | 字符串 |
|
| 任意不包含(区分大小写) | 字符串 |
|
| 所有不包含(区分大小写) | 字符串 |
|
| 任意包含(忽略大小写) | 字符串 |
|
| 所有包含(忽略大小写) | 字符串 |
|
| 任意不包含(忽略大小写) | 字符串 |
|
| 所有不包含(忽略大小写) | 字符串 |
|
| 为真 | 布尔值 |
|
| 为假 | 布尔值 |
|
| 包含所有指定值 | 数组 |
|
| 包含任一指定值 | 数组 |
|
| 不包含所有指定值 | 数组 |
|
| 数组完全相等 | 数组 |
|
| 数组不完全相等 | 数组 |
|
7. 数据类型可允许的操作符
数据类型 | 支持的操作符 |
---|---|
boolean |
|
string |
|
text |
|
date / datetime |
|
float / integer |
|
array |
|
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 %}