在AnQiCMS中，我们经常需要以多种方式展示网站内容，例如按分类、按标签，甚至根据内容的特定属性进行筛选。当面对更复杂的内容组织需求时，比如在一个产品列表页，不仅要展示产品，还需要根据产品的“颜色”、“尺寸”、“材质”等自定义属性进行多维度筛选时，archiveFilters标签便能大显身手，帮助我们轻松实现这些复杂的内容筛选与展示。

核心功能与应用场景

archiveFilters标签的核心作用是为我们的内容模型生成动态的筛选条件。它不仅仅是简单的分类筛选，而是能够深入到内容模型中定义的自定义字段，将这些字段的值作为筛选选项呈现给用户。

想象一下，您正在搭建一个产品展示网站，产品除了常规的名称、描述外，还有“颜色（红、蓝、绿）”、“材质（木质、金属、塑料）”、“尺寸（大、中、小）”等属性。当用户访问产品列表页时，他们希望能根据这些属性来快速找到自己想要的产品。这时，如果手动去编写每个筛选条件的逻辑，将是一项繁琐且难以维护的任务。

archiveFilters正是为了解决这样的痛点而生。它能够读取您在AnQiCMS后台为内容模型配置的自定义字段，并自动生成对应的筛选链接，用户点击这些链接后，页面上展示的内容（通常通过archiveList标签调用）便会随之更新，实现动态筛选。

准备工作：定义内容模型与自定义字段

要利用archiveFilters标签，首先需要在AnQiCMS后台进行一些准备工作，即定义内容模型并添加自定义字段。

  1. 进入后台：登录AnQiCMS后台，导航至“内容管理” -> “内容模型”。
  2. 选择或创建内容模型：您可以选择现有的“文章模型”、“产品模型”，或者根据业务需求创建一个全新的内容模型（例如“房产信息”）。
  3. 添加自定义字段：进入您选择或创建的内容模型编辑页面。在这里，您可以添加新的自定义字段，例如：
    • 字段名称：例如“户型”、“房屋面积”、“朝向”。
    • 调用字段：使用英文字母，如 house_type、area、orientation。
    • 字段类型：为了让archiveFilters能够正确识别并生成筛选条件，建议选择“单项选择”、“多项选择”或“下拉选择”等类型。这样，您在“默认值”中填写的选项（每行一个）将直接作为筛选器的可选值。
    • 是否必填：根据实际需求设置。
  4. 发布内容并填写字段：确保您发布的内容在对应的自定义字段中填写了数据。只有存在数据的字段，archiveFilters才能生成有意义的筛选选项。

完成这些步骤后，我们的网站内容就具备了多维度筛选的基础。

archiveFilters标签的参数解读

archiveFilters标签在使用时，可以通过一些参数来控制其行为：

  • 变量名：这是可选的。如果您为archiveFilters指定一个变量名（例如 filters），那么它返回的筛选器数据将存储在这个变量中，您可以在标签内部通过这个变量名来访问数据。如果不指定，则默认为直接输出。
  • moduleId：指定您希望生成筛选器的内容模型ID。例如，moduleId="1"通常代表“文章模型”，moduleId="2"可能代表“产品模型”。这是非常重要的参数，它告诉标签应该从哪个模型中获取自定义字段来生成筛选条件。
  • allText：设置所有筛选条件都未选中时的显示文本，例如“全部”、“不限”。如果不想显示这个选项，可以设置为 allText=false。
  • siteId：如果您启用了多站点管理，并且需要调用特定站点的数据，可以通过此参数指定站点ID。通常情况下，此参数无需填写，系统会默认获取当前站点的数据。

理解 archiveFilters 的数据结构

当您使用archiveFilters标签并将其结果存储在一个变量中（例如 filters），这个变量实际上是一个嵌套的数组对象，结构清晰，便于我们进行循环渲染：

  • filters：一个包含多个筛选维度（item）的数组。
  • 每个 item 对象代表一个具体的筛选条件分组，例如“户型”或“区域”。它包含以下字段：
    • Name：筛选条件分组的显示名称（例如“户型”）。
    • FieldName：筛选条件对应的自定义字段名（例如 house_type）。
    • Items：一个包含该筛选条件下所有可选值（val）的数组。
  • 每个 val 对象代表一个具体的筛选选项，例如“一室一厅”或“东城区”。它包含以下字段：
    • Label：筛选选项的显示名称（例如“两居室”）。
    • Link：点击此选项后跳转的URL。AnQiCMS会自动处理URL参数，确保正确筛选。
    • IsCurrent：一个布尔值，表示当前选项是否处于选中状态。这对于为选中选项添加高亮样式非常有用。

在模板中实现筛选界面

有了上述数据结构，我们就可以在模板中构建动态的筛选界面了。通常，我们会使用嵌套的for循环来遍历这些数据。

”`twig {# 参数筛选代码区域 #} 

<h3>内容筛选</h3>
{% archiveFilters filters with moduleId="1" allText="不限" %} {# 假设模型ID为1，显示“不限” #}
    {% for item in filters %} {# 遍历每个筛选条件分组（如户型、面积等） #}
    <div class="filter-group">
        <span class="filter-name">{{ item.Name }}：</span>
        <ul class="filter-options">
            {% for val in item.Items %} {# 遍历每个筛选分组下的具体选项（如两居室、三居室） #}
            <li class="filter-option {% if val.IsCurrent %}active{% endif %}">
                <a href="{{ val.Link }}">{{ val.Label }}</a>
            </li>
            {% endfor %}
        </ul>
    </div>
    {% endfor %}
{% endarchiveFilters %}

{# 文档列表代码区域，它将自动响应上面的筛选条件 #} 

{% archiveList archives with moduleId="1" type="page" limit="10" %} {# 同样指定模型ID为1，并开启分页 #}
    {% for archive_item in archives %} {# 遍历筛选后的文档列表 #}
    <div class="content-