`archiveFilters`标签如何实现复杂参数筛选条件在前端的动态显示？

在网站内容运营中，为用户提供灵活、高效的筛选功能是提升用户体验、帮助用户快速定位所需信息的重要一环。安企CMS（AnQiCMS）深知这一点，通过其强大的模板标签系统，特别是archiveFilters标签，让前端动态显示复杂参数筛选条件变得轻而易举。

核心功能与实现原理

archiveFilters标签的核心作用是根据内容模型的自定义字段，自动生成前端可供用户选择的筛选条件及其对应的动态链接。当用户点击某个筛选条件时，页面URL会自动附加相应的参数，后台的archiveList标签则会根据这些URL参数动态调整文档列表的展示内容，从而实现精确筛选。这个过程无需手动编写复杂的后端逻辑，大大简化了开发和维护工作。

准备工作：搭建筛选基础

要使用archiveFilters标签，首先需要在安企CMS后台做好一些准备工作：

  1. 自定义内容模型字段：archiveFilters标签依赖于内容模型中预先定义的自定义字段。只有那些设置为“单项选择”、“多项选择”或“下拉选择”类型的字段，才能够被archiveFilters标签识别并生成筛选条件。

    • 举例来说，如果你正在构建一个房产网站，可以创建一个名为“房产模型”的内容模型。在该模型中，可以添加以下自定义字段：
      • “房屋类型”（单项选择，选项有“住宅”、“商铺”、“写字楼”）
      • “户型”（单项选择，选项有“一居室”、“两居室”、“三居室”等）
      • “装修程度”（下拉选择，选项有“毛坯”、“简装”、“精装”） 后台在这些字段中填写的“默认值”将成为前端筛选条件的“选项”。

  2. 明确标签应用场景：archiveFilters标签主要设计用于文档首页或文档分类的模板页面，并且通常会与文档分页列表（即archiveList标签的type="page"模式）结合使用，以确保筛选结果能够正确分页。

archiveFilters标签用法深度解析

archiveFilters标签的基本用法如下：

{% archiveFilters filters with moduleId="..." allText="..." %}
    {# 循环输出筛选组 #}
    {% for item in filters %}
        <ul>
            <li>{{item.Name}}: </li> {# 筛选组名称，如“房屋类型” #}
            {% for val in item.Items %} {# 循环输出每个筛选选项 #}
            <li class="{% if val.IsCurrent %}active{% endif %}">
                <a href="{{val.Link}}">{{val.Label}}</a>
            </li>
            {% endfor %}
        </ul>
    {% endfor %}
{% endarchiveFilters %}

让我们详细拆解一下这个标签的参数和返回的变量：

  • moduleId 参数： 这是archiveFilters标签中一个非常重要的参数。它用于指定要获取哪个内容模型的筛选条件。例如，如果你想筛选“文章模型”的文档，moduleId通常设置为1；如果筛选“产品模型”，moduleId可能设置为2。这个ID可以在后台的“内容模型”管理界面中查看到。通过指定moduleId，系统能够精准地调取相应模型下定义的筛选字段。

  • allText 参数： 这个参数用于设置筛选条件中“全部”选项的显示文本。例如，allText="不限"会显示“不限”字样。如果你不希望显示“全部”选项，可以将其设置为false，如allText=false。

  • filters 变量： archiveFilters标签会将生成的筛选条件组织成一个名为filters的数组对象（当然，你可以自定义其他变量名）。这个filters数组的每一个元素都代表一个筛选条件组，例如“房屋类型”就是一个组，“户型”是另一个组。每个组对象包含以下关键属性：

    • item.Name：这是该筛选组的显示名称，如“房屋类型”、“户型”等，通常直接呈现在前端界面上。
    • item.FieldName：这是该筛选组在URL参数中使用的字段名，由系统自动生成，用于后端识别具体的筛选条件。
    • item.Items：这是一个内层数组，包含了当前筛选组下所有可用的筛选选项。

  • val 变量（在item.Items循环中）： item.Items数组中的每个元素都是一个筛选选项对象，它包含以下关键属性：

    • val.Label：这是该筛选选项的显示文本，如“住宅”、“一居室”等。
    • val.Link：这是实现动态筛选的核心。val.Link是一个预先构建好的URL，当用户点击这个链接时，页面会自动跳转并带上相应的筛选参数。例如，点击“住宅”可能跳转到.../list?houseType=住宅。
    • val.IsCurrent：这是一个布尔值，表示当前筛选选项是否已被选中。你可以利用这个属性为当前选中的选项添加CSS样式（如active类），从而在前端高亮显示，提升用户体验。

协同工作：archiveList与pagination

archiveFilters标签本身只负责生成筛选条件的链接，实际的数据过滤是由archiveList标签来完成的。当用户点击archiveFilters生成的链接后，URL中会带上相应的筛选参数。此时，页面上的archiveList标签（设置为type="page"模式）会自动识别这些URL参数，并向后端请求符合筛选条件的数据。

同时，pagination分页标签也会智能地根据当前的筛选状态，生成正确的分页链接，确保用户在筛选后的结果中也能正常翻页。

实战示例：构建房产筛选器

假设你已经按照前面提到的方式，在后台为“房产模型”定义了“房屋类型”和“户型”等自定义字段。现在，我们可以在前端模板中这样实现一个动态筛选器：

”`twig {# 假设这是房产列表页面，moduleId=“1”是房产模型的ID #} 

<h2>房产筛选</h2>
{% archiveFilters filters with moduleId="1" allText="不限" %}
    {% 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="{% if val.IsCurrent %}active{% endif %}">
                <a href="{{val.Link}}">{{val.Label}}</a>
            </li>
            {% endfor %}
        </ul>
    </div>
    {% endfor %}
{% endarchiveFilters %}

{# 文档列表代码：会根据URL中的筛选参数自动加载 #}

{% archiveList archives with moduleId=“1” type=“page” limit=“10” %}

{% for item in archives %}
<div class="property-item">
    <a href="{{item.Link}}">
        <img src="{{item.Thumb}}" alt="{{item.Title}}">
        <h3>{{item.Title}}</h3>
        <p>{{item.Description}}</p>
        {# 显示自定义字段，例如“房屋类型”和“户型” #}
        {% archiveParams params with id=item.Id %}
            {% for param in params %}
                {% if param.FieldName == "houseType" %}
                    <span>类型: {{param.Value}}</span>
                {% elseif param.FieldName == "houseLayout" %}
                    <span>户型: {{param.Value}}</span>
                {% endif %}
            {% endfor %}
        {% endarchiveParams %}
        <span>阅读量: {{item.Views}}</span>
    </a>
</div>
{% empty %}
<p>没有找到符合条件的房产信息。</p>
{% endfor %}

{% endarchiveList %}

{# 分页代码：会根据筛选结果自动调整分页链接 #} 

{% pagination pages with show="5" %}
    {# 首页 #}
    <a class="{% if pages.FirstPage.IsCurrent %}active{% endif %}" href="{{pages.FirstPage.Link}}">首页</a>
    {# 上