如何利用`archiveFilters`标签，为安企CMS的文档列表添加高级筛选功能？

在安企CMS中管理内容，特别是当网站内容日益丰富时，如何帮助访客快速找到他们需要的信息，就成了提升用户体验的关键。如果您的网站提供了多样化的产品或服务，或者包含大量不同属性的文章，那么一个高效的筛选功能将是必不可少的。今天，我们就来深入了解安企CMS中一个非常实用的标签——archiveFilters，它能帮助我们为文档列表轻松添加高级筛选功能。

灵活内容模型的基石：自定义筛选字段

在深入archiveFilters标签之前，我们首先需要理解安企CMS的“灵活内容模型”这一核心优势。安企CMS允许我们根据业务需求自定义内容模型，这意味着您可以为文章、产品等不同类型的内容添加专属的字段。

例如，如果您运营一个房产网站，除了基本的标题、内容外，您可能还需要“房屋类型”（如住宅、商铺）、“面积范围”、“所在区域”等属性。这些自定义字段正是我们实现高级筛选的基础。

在后台创建或编辑内容模型时，您可以根据需要添加这些自定义字段。对于筛选功能而言，最常用的字段类型是单选、多选或下拉选择。当您设置好这些字段并为文档填写了相应的值后，它们就为archiveFilters提供了丰富的数据源。安企CMS会自动识别这些可用于筛选的自定义字段，以便在前端进行展示和交互。

archiveFilters标签：筛选功能的智能向导

archiveFilters标签的作用，就是根据您在内容模型中定义的筛选字段，自动生成一系列可点击的筛选选项。它就像一个智能向导，能够理解您的内容结构，并为访客呈现出清晰、实用的筛选界面。

这个标签通常用在文档列表页或分类页的模板中，与archiveList标签配合使用，共同完成筛选和内容展示。

使用archiveFilters标签非常直观，它的基本结构是这样的：

{% archiveFilters filters with moduleId="1" allText="全部" %}
    {# 在这里循环输出筛选条件 #}
{% endarchiveFilters %}

这里面有几个关键参数：

• filters：您可以为这个标签的输出结果定义一个变量名，例如这里是filters。这个变量将包含所有可用的筛选条件数据，您需要通过循环来展示它们。
• moduleId：这个参数非常重要，它告诉archiveFilters您希望为哪个内容模型（如文章模型、产品模型或您自定义的模型）生成筛选条件。例如，moduleId="1"通常代表文章模型，moduleId="2"代表产品模型。 通过指定模型ID，您可以确保只显示与当前列表内容相关的筛选选项。
• allText：这个参数用于设置“全部”选项的显示文本，例如“全部”、“不限”等。如果您不希望显示“全部”选项，可以将其设置为false。

深入filters变量的结构

当您通过{% archiveFilters filters ... %}获取到数据后，filters变量实际上是一个数组，其中包含了多个筛选组。每个筛选组都代表您内容模型中的一个可筛选字段，例如“房屋类型”就是一个筛选组。

让我们看看filters变量内部的结构：

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

在上面的代码片段中：

• item.Name：这是筛选组的显示名称，比如“房屋类型”、“面积范围”。
• item.FieldName：这是该筛选组对应在内容模型中的字段名，例如您可能在后台设置为house_type或area_range。
• item.Items：这是该筛选组下所有可用的筛选选项，它本身也是一个数组。

而item.Items数组中的每个val对象，则包含了具体的筛选选项信息：

• val.Label：这是筛选选项的显示文本，例如“住宅”、“商铺”、“50-100平米”。
• val.Link：这是点击该筛选选项后跳转的URL。这个URL会包含相应的查询参数，例如/list.html?house_type=住宅。这是archiveFilters标签实现筛选功能的核心机制。
• val.IsCurrent：这是一个布尔值，用于判断当前选项是否已被选中。您可以利用这个属性为选中的选项添加active样式，给用户清晰的视觉反馈。

联动archiveList：完成筛选逻辑

archiveFilters标签生成了筛选链接，但真正执行内容筛选并显示结果的，是archiveList标签。这两个标签是紧密配合的。当用户点击archiveFilters生成的筛选链接时，页面URL会发生变化，携带上新的筛选参数。此时，页面中的archiveList标签会自动读取URL中的这些参数，并根据它们重新查询并显示符合条件的文档。

确保您的archiveList标签设置了type="page"，以便它能够正确地处理分页和URL中的筛选参数。

下面，我们通过一个房产网站的例子，来展示archiveFilters、archiveList和pagination这三个标签是如何协同工作的：

”`twig {# 假设这是房产列表页的模板 #}

<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="filter-item {% if val.IsCurrent %}active{% endif %}">
                <a href="{{val.Link}}">{{val.Label}}</a>
            </li>
            {% endfor %}
        </ul>
    </div>
    {% endfor %}
{% endarchiveFilters %}

<h2>房产列表</h2>
{# 文档列表代码：注意 type="page"，它会自动处理URL中的筛选参数 #}
{% archiveList archives with moduleId="1" type="page" limit="10" %}
    {% for item in archives %}
    <div class="archive-item">
        <a href="{{item.Link}}">
            <h3>{{item.Title}}</h3>
            <p>{{item.Description}}</p>
            <div class="meta-info">
                <span>所在分类：{% categoryDetail with name="Title" id=item.CategoryId %}</span>
                <span>发布时间：{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
                <span>浏览量：{{item.Views}} 阅读</span>
            </div>
        </a>
        {% if item.Thumb %}
        <a href="{{item.Link}}">
            <img alt="{{item.Title}}" src="{{item.Thumb}}">
        </a>
        {% endif %}
    </div>
    {% empty %}
    <p>抱歉，没有找到符合条件的房产信息。</p>
    {% endfor %}
{% endarchiveList %}

{# 分页代码，同样会自动根据筛选条件生成正确的页码链接 #}
<div class="pagination-area">
    {% pagination pages with show="5" %}
        <a class="pagination-link {% if pages.FirstPage.IsCurrent %}active{% endif %}" href="{{pages.FirstPage.Link}}">首页</a>
        {% if pages.PrevPage %}
        <a class="pagination-link" href="{{pages.PrevPage.Link}}">上一页</a>
        {% endif %}
        {% for item in pages.Pages %}
        <a class="pagination-link {% if item.IsCurrent %}active{% endif %}" href="{{item.Link}}">{{item.Name}}</a>
        {% endfor %}
        {% if pages.NextPage %}
        <a class="pagination-link" href="{{pages.NextPage.Link}}">下一页</a>