在网站运营中，如何让用户更高效地查找和浏览内容，是提升用户体验和网站价值的关键。尤其对于文档列表页，如果能够提供灵活的筛选功能，让用户根据自己的需求动态调整内容的显示，无疑会大大增强网站的互动性和内容的可用性。AnQiCMS 凭借其灵活的内容模型和强大的模板标签功能，能够轻松实现这一需求。

要实现文档列表页的动态筛选，我们主要会用到 AnQiCMS 的 内容模型自定义字段、文档参数筛选标签（archiveFilters） 和 文档列表标签（archiveList），并通过 URL 参数传递筛选条件，让内容得以动态呈现。

一、准备工作：构建可筛选的内容模型

一切动态筛选的基础都源于数据本身的结构。在 AnQiCMS 中，这意味着我们需要在“内容模型”中定义好可以用于筛选的自定义字段。

  1. 进入内容模型管理： 登录 AnQiCMS 后台，导航至“内容管理”模块，然后点击“内容模型”。这里列出了您网站所有的内容模型，例如“文章模型”或“产品模型”。您可以选择一个现有模型进行编辑，或者创建一个新的模型。

  2. 创建或编辑自定义字段： 在内容模型的编辑页面，找到“内容模型自定义字段”部分。在这里，您可以添加新的字段。为了实现筛选功能，我们建议使用以下几种字段类型：

    • 单项选择（Radio）： 适用于只有一个选项能被选中的情况，例如“房屋类型：住宅/商铺/写字楼”。
    • 多项选择（Checkbox）： 允许用户选择多个选项，例如“配套设施：停车位/学区房/地铁房”。
    • 下拉选择（Select）： 当选项较多时，以下拉菜单形式呈现，例如“价格区间”、“面积大小”。

    在添加这些字段时，请注意填写“参数名”（这是在模板中调用时的唯一标识）和“参数值”（选项的实际内容，一行一个）。例如，您可以创建一个名为“房屋类型”的字段，其参数名为 houseType，并在默认值中填写“住宅”、“商铺”、“写字楼”。

  3. 为文档填充数据： 完成自定义字段设置后，当您在相应内容模型下发布或编辑文档时，就会看到这些新增的字段。请务必为您的文档准确地填写这些自定义字段的值，这样它们才能被筛选出来。

二、核心功能：生成筛选条件的 archiveFilters 标签

数据准备就绪后，我们就可以在模板中生成用户界面上的筛选条件了。AnQiCMS 提供了 archiveFilters 标签，专门用于自动生成这些动态筛选链接。

这个标签通常放置在文档列表页的顶部或侧边栏，它会根据您内容模型中定义的字段，以及当前页面的上下文（例如当前的 moduleId），自动生成一系列筛选链接。

基本用法示例：

{# 在文档列表页的模板文件 (例如 {模型table}/list.html) 中 #}

<div>
    <h3>筛选条件</h3>
    {% archiveFilters filters with moduleId=1 allText="全部" %}
        {% for item in filters %}
        <ul class="filter-group">
            <li class="filter-name">{{item.Name}}: </li> {# item.Name 会显示您在后台定义的“参数名” #}
            {% for val in item.Items %}
            <li class="filter-item {% if val.IsCurrent %}active{% endif %}">
                <a href="{{val.Link}}">{{val.Label}}</a>
            </li>
            {% endfor %}
        </ul>
        {% endfor %}
    {% endarchiveFilters %}
</div>

代码解析：

  • {% archiveFilters filters with moduleId=1 allText="全部" %}：这是调用 archiveFilters 标签的开始。
    • filters 是您为筛选结果数据定义的变量名，您可以在后续的 for 循环中通过这个变量访问筛选数据。
    • moduleId=1：指定要筛选的内容模型 ID。这里假设您的文章模型 ID 是 1。这是非常重要的，确保筛选条件是针对正确的内容类型。
    • allText="全部"：定义所有筛选条件下的默认文本，例如“全部房屋类型”、“所有配套”。
  • {% for item in filters %}：这个循环会遍历每个可筛选的自定义字段（例如“房屋类型”、“配套设施”）。
    • item.Name：显示自定义字段的名称，例如“房屋类型”。
    • item.Items：包含了当前自定义字段的所有可选值（例如“住宅”、“商铺”）。
  • {% for val in item.Items %}：这个内层循环会遍历每个字段的所有可选值。
    • val.Label：显示当前筛选选项的文本，例如“住宅”。
    • val.Link：这是最关键的部分！AnQiCMS 会自动为您生成一个包含该筛选条件的 URL。当用户点击这个链接时，页面会刷新并带上相应的 URL 查询参数。
    • val.IsCurrent：一个布尔值，如果当前选项已被选中，则为 true，您可以利用它为当前选中的筛选条件添加 active 类名，以提供视觉反馈。

三、动态显示内容：archiveList 标签的配合

当用户点击 archiveFilters 生成的筛选链接后，页面会刷新，并在 URL 中带上类似 ?houseType=住宅&area=50-100 这样的查询参数。此时，文档列表标签 archiveList 会发挥其强大的自动匹配能力。

archiveList 标签在文档列表页的模板中，当其 type 参数设置为 page 时，它会智能地解析当前 URL 中的所有查询参数（包括由 archiveFilters 生成的筛选参数，以及搜索关键词 q 等），并自动将这些参数应用到文档查询中。这意味着您无需编写额外的逻辑来获取 URL 参数并手动构建查询条件，AnQiCMS 都帮您处理好了。

基本用法示例：

”`twig {# 假设这是与 archiveFilters 标签在同一个模板文件中的文档列表部分 #}

{% archiveList archives with moduleId=1 type="page" limit="10" %}
    {% for doc in archives %}
    <div class="document-item">
        <h4><a href="{{doc.Link}}">{{doc.Title}}</a></h4>
        <p>{{doc.Description}}</p>