`archiveFilters` 标签如何构建复杂的文档参数筛选界面，如房产、产品筛选？

在网站运营中，为用户提供高效、精准的内容筛选功能是提升用户体验和内容可发现性的关键。无论是复杂的房产信息、海量的商品SKU，还是专业的行业文档，一个设计良好的筛选界面都能让用户快速定位所需信息。在安企CMS中，archiveFilters 标签正是构建这类复杂筛选界面的强大工具。

理解筛选界面的核心：内容模型与自定义参数

要构建灵活的筛选功能，首先需要理解安企CMS中“内容模型”的概念。安企CMS允许我们根据业务需求自定义内容模型，比如为“房产”创建一个模型，为“产品”创建另一个模型。在这些模型中，我们可以添加各种自定义字段来描述内容的不同属性。

例如，对于一个房产网站，我们可能会在房产模型中定义如下自定义字段：

  • 房屋类型（单项选择：住宅、公寓、别墅、商铺）
  • 户型（单项选择：一室一厅、两室一厅、三室两厅）
  • 面积（数字范围）
  • 装修程度（单项选择：毛坯、简装、精装、豪装）
  • 区域（下拉选择：北京、上海、广州、深圳）

这些在内容模型中定义的、类型为单项选择、多项选择或下拉选择的字段，正是 archiveFilters 标签能够识别并用于构建筛选条件的“参数”。它们为用户提供了结构化的选择项，方便我们动态生成筛选链接。

archiveFilters：动态构建筛选条件的利器

archiveFilters 标签专门用于生成基于内容模型自定义参数的筛选条件列表。它会在模板中输出一个可供循环遍历的数组，数组的每个元素都代表一个可筛选的参数（比如“房屋类型”、“户型”）。每个参数又包含其所有可选值以及对应的筛选链接。

它的基本用法是这样：

{% archiveFilters filters with moduleId="1" allText="全部" %}
    {# 循环遍历筛选参数 #}
{% endarchiveFilters %}

这里，filters 是我们自定义的变量名，用于接收 archiveFilters 标签输出的数据。

  • moduleId：指定要筛选哪个内容模型下的文档。例如，moduleId="1" 可能代表文章模型，moduleId="2" 可能代表产品模型。这个ID需要与你在后台创建内容模型时分配的ID相对应。
  • allText：为每个筛选参数提供一个“全部”或“不限”的选项文本。如果设置为 false，则不显示这个选项。

filters 变量本身是一个数组，其中包含多个筛选参数对象。在模板中，我们会通过 for 循环来逐一展现这些参数：

{% for item in filters %}
    {# item 代表一个筛选参数，例如“房屋类型” #}
    <div class="filter-group">
        <span class="filter-name">{{ item.Name }}:</span> {# 显示参数名称，如“房屋类型” #}
        <ul class="filter-options">
            {% for val in item.Items %}
                {# val 代表参数的一个可选值，例如“住宅” #}
                <li class="{% if val.IsCurrent %}active{% endif %}">
                    <a href="{{ val.Link }}">{{ val.Label }}</a> {# 显示选项名称和对应的筛选链接 #}
                </li>
            {% endfor %}
        </ul>
    </div>
{% endfor %}

在这段代码中：

  • item.Name 会显示我们后台定义的参数名，如“房屋类型”、“户型”。
  • item.Items 是一个包含所有可选值的小数组。
  • val.Label 会显示每个选项的文本，如“住宅”、“公寓”。
  • val.Link 是最关键的部分，它包含了点击该选项后跳转到的筛选URL。安企CMS会自动根据当前页面的URL和用户选择的筛选条件，生成一个带有相应查询参数的新URL。
  • val.IsCurrent 是一个布尔值，表示当前选项是否被选中，这对于为选中项添加 active 类，实现高亮显示非常有用。

筛选结果的展示与联动

archiveFilters 标签生成的筛选链接会自动携带参数（例如 ?房屋类型=住宅&户型=两室一厅）到当前列表页。而安企CMS的 archiveList 标签在以 type="page" 模式调用时，会自动解析这些URL中的查询参数，并根据这些参数来筛选并展示相应的文档。这意味着，你无需手动编写复杂的查询逻辑，只需在 archiveList 中配置好 moduleId，它就能与 archiveFilters 无缝联动。

同时，结合 pagination 标签，筛选后的文档列表也能够正常进行分页显示，为用户提供完整的浏览体验。

下面是一个综合示例，展示了如何在安企CMS模板中构建一个房产筛选界面：

{# 假设当前模板是房产列表页，并已定义好房产内容模型，moduleId="2" #}

<div class="filter-area">
    <h3>房产筛选</h3>
    {% archiveFilters filters with moduleId="2" allText="不限" %}
        {% for item in filters %}
        <div class="filter-group">
            <span class="filter-label">{{ 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 %}
</div>

<div class="house-list-area">
    <h3>房源列表</h3>
    {% archiveList archives with moduleId="2" type="page" limit="10" %}
        {% for item in archives %}
        <div class="house-card">
            <a href="{{ item.Link }}">
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="house-thumb">
                <h4>{{ item.Title }}</h4>
                <p><strong>房屋类型:</strong> {% archiveDetail with name="房屋类型" id=item.Id %}</p>
                <p><strong>户型:</strong> {% archiveDetail with name="户型" id=item.Id %}</p>
                <p><strong>面积:</strong> {% archiveDetail with name="面积" id=item.Id %}平米</p>
                {# 更多房产参数 #}
            </a>
        </div>
        {% empty %}
        <p>抱歉，没有找到符合条件的房源。</p>
        {% endfor %}
    {% endarchiveList %}

    {# 分页导航 #}
    <div class="pagination-area">
        {% pagination pages with show="5" %}
            <ul>
                <li class="{% if pages.FirstPage.IsCurrent %}active{% endif %}"><a href="{{pages.FirstPage.Link}}">首页</a></li>
                {% if pages.PrevPage %}
                <li><a href="{{pages.PrevPage.Link}}">上一页</a></li>
                {% endif %}
                {% for item in pages.Pages %}
                <li class="{% if item.IsCurrent %}active{% endif %}"><a href="{{item.Link}}">{{item.Name}}</a></li>
                {% endfor %}
                {% if pages.NextPage %}
                <li><a href="{{pages.NextPage.Link}}">下一页</a></li>
                {% endif %}
                <li class="{% if pages.LastPage.IsCurrent %}active{% endif %}"><a href="{{pages.LastPage.Link}}">尾页</a></li>
            </ul>
        {% endpagination %}
    </div>
</div>

通过上述示例，我们可以看到 archiveFilters 标签如何配合内容模型、archiveList 和 pagination，共同构建出一个功能完备、高度动态化的筛选界面。它极大地简化了开发流程，将复杂的逻辑交由CMS内部处理，让内容运营者和模板开发者能够专注于内容和用户体验。

常见问题 (FAQ)

  1. 问：archiveFilters 标签只能筛选内容模型中的自定义字段吗？ 答：是的，archiveFilters 标签主要用于筛选内容模型中定义的自定义参数字段。这些字段通常是你在后台创建内容模型时，特意设置为“单项选择”、“多项选择”或“下拉选择”等类型，以便提供固定的选项供用户筛选。系统默认的字段（如标题、描述等）不会通过此标签自动生成筛选条件，但可以通过 archiveList 标签的 q 参数进行关键词搜索。

  2. 问：如何在筛选界面中添加价格区间或面积范围这样的数字筛选？ 答：archiveFilters 标签本身主要用于处理预设选项的分类筛选。对于价格区间或面积范围这类数值型筛选，通常需要结合自定义的表单元素（如输入框、滑块）和前端JavaScript来实现。当用户选择或输入范围后，通过JavaScript动态构建URL查询参数（例如 ?min_price=1000&max_price=5000），然后 archiveList 标签能够通过