如何使用`archiveFilters`标签在前台实现多条件组合筛选功能？

AnQiCMS 提供了灵活强大的内容管理能力，其中一项非常实用的功能就是利用 archiveFilters 标签在前台实现多条件组合筛选。这对于内容丰富、需要用户根据不同维度查找信息的网站来说，例如产品展示、房产租赁、招聘信息等，无疑大大提升了用户体验和内容的可发现性。

让我们深入了解如何使用 archiveFilters 标签，为您的网站构建一个直观高效的筛选系统。

构建筛选功能的基础：自定义内容模型字段

在您能够使用 archiveFilters 标签进行筛选之前，首先需要确保您的内容模型中已经设置了可用于筛选的自定义字段。安企CMS 允许您根据业务需求灵活地定义内容模型。

例如，如果您正在创建一个房产网站，可能会有以下筛选条件：

  • 房屋类型：住宅、商铺、公寓等（单项选择或下拉选择）
  • 户型：一室、两室、三室等（单项选择或下拉选择）
  • 装修情况：精装修、毛坯、简装修（单项选择或下拉选择）
  • 面积范围：例如 50-70 平米、70-90 平米（数字范围，这需要后端逻辑来处理，但前端展示可以是预设选项）

这些筛选条件在安企CMS 后台的“内容管理”->“内容模型”中进行定义。当您编辑或创建模型时，可以为模型添加自定义字段，并选择合适的字段类型，如“单项选择”或“下拉选择”。这些字段的“默认值”将作为前端筛选的具体选项。安企CMS 会自动识别这些定义为可筛选的参数。

认识 archiveFilters 标签

archiveFilters 标签的主要作用是根据您内容模型中定义的筛选字段，自动生成前端筛选条件的 HTML 结构和对应的链接。这些链接会巧妙地携带查询参数，供内容列表标签 archiveList 识别并进行数据筛选。

它的基本用法是这样：

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

这里我们定义了一个名为 filters 的变量来接收标签输出的数据。

标签接受几个重要参数：

  • moduleId：指定要筛选的内容模型 ID。这是必不可少的，因为它告诉系统您要针对哪个模型（例如，文章模型 ID 是 1，产品模型 ID 是 2）来生成筛选条件。
  • allText：用于设置“全部”或“不限”这类默认选项的显示文本。如果您不希望显示“全部”选项，可以设置为 allText=false。

filters 变量会返回一个数组对象，数组中的每个 item 代表一个可筛选的字段（比如“房屋类型”、“户型”）。每个 item 自身又包含一个 Items 数组，这个数组里就是该字段下所有可供选择的筛选值（比如“住宅”、“商铺”）。

每个筛选值 (val) 都包含了以下信息：

  • Label：筛选值的显示文本，如“住宅”。
  • Link：点击该筛选值后跳转的 URL，这个 URL 会自动包含筛选参数。
  • IsCurrent：一个布尔值，指示当前筛选值是否已被选中，可以用来添加 active 样式。

将筛选条件与内容列表结合：archiveList 和 pagination

archiveFilters 标签本身只生成筛选选项的 UI 和链接，它需要与 archiveList 和 pagination 标签协同工作，才能实现完整的筛选和分页功能。

关键在于，archiveList 标签在 type="page" 模式下，会自动读取 URL 中的查询参数，并根据这些参数对文档进行筛选。archiveFilters 生成的链接正是利用了这一点。

让我们看一个完整的示例，假设我们有一个模型 ID 为 1 的“房产”模型，并且已经为它定义了“房屋类型”和“户型”等自定义筛选字段。

<div class="filter-area">
    <h3>房产筛选</h3>
    {% archiveFilters filters with moduleId="1" allText="不限" %}
        {% for item in filters %}
        <ul class="filter-group">
            <li class="filter-name">{{ item.Name }}: </li>
            {% for val in item.Items %}
            <li class="filter-option {% if val.IsCurrent %}active{% endif %}">
                <a href="{{ val.Link }}">{{ val.Label }}</a>
            </li>
            {% endfor %}
        </ul>
        {% endfor %}
    {% endarchiveFilters %}
</div>

<div class="content-list">
    {% archiveList archives with moduleId="1" type="page" limit="10" %}
        {% for item in archives %}
        <div class="article-card">
            <a href="{{ item.Link }}">
                <h4>{{ item.Title }}</h4>
                <p>{{ item.Description|truncatechars:100 }}</p>
                <div class="meta-info">
                    <span>发布于：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                    <span>阅读量：{{ item.Views }}</span>
                    {# 如果有自定义字段，例如“户型”，可以直接调用 #}
                    <span>户型：{% archiveDetail with name="户型" id=item.Id %}</span>
                </div>
            </a>
            {% if item.Thumb %}
            <a href="{{ item.Link }}" class="thumb">
                <img alt="{{ item.Title }}" src="{{ item.Thumb }}">
            </a>
            {% endif %}
        </div>
        {% empty %}
        <p class="no-content">很抱歉，当前筛选条件下没有找到相关内容。</p>
        {% endfor %}
    {% endarchiveList %}

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

在这个示例中：

  1. archiveFilters 生成了“房屋类型”、“户型”等筛选选项，每个选项的 Link 会自动添加相应的查询参数（例如 ?房屋类型=住宅&户型=三室）。
  2. archiveList 使用 moduleId="1" 和 type="page"，它会检查当前 URL 中的查询参数，并根据这些参数筛选出对应的房产文档。
  3. pagination 标签则确保了筛选结果在多页时能够正确地进行翻页，并且翻页链接也会保留当前的筛选条件。

实践中的小贴士

  • 样式美化是关键：筛选功能的用户界面（UI）至关重要。您需要为 .filter-group、.filter-option 和 .active 类添加合适的 CSS 样式，让筛选条件清晰可见，选中状态一目了然。
  • 自定义筛选参数的命名：在后台定义自定义字段时，建议使用简洁且有意义的英文名称作为“调用字段”（FieldName），这会体现在 URL 查询参数中。虽然系统支持中文，但英文参数更通用。
  • 确保 archiveList 设置正确：一定要在 archiveList 中设置 type="page"，否则筛选和分页功能将无法正常工作。
  • 筛选参数与 URL：当用户点击筛选条件时，您会在浏览器地址栏中看到类似于 yourdomain.com/module/list.html?户型=三室&房屋类型=住宅 这样的 URL。安企CMS 会自动解析这些参数并进行筛选。

通过这种方式，您可以在 AnQiCMS 中轻松实现强大的多条件组合筛选功能，极大地提升网站内容的互动性和用户满意度。

常见问题 (FAQ)

1. 我的自定义字段在 archiveFilters 中没有显示，或者显示了但无法筛选，这是为什么？

这通常是因为您的自定义字段没有正确配置为可筛选类型。请确保在后台“内容管理”->“内容模型”中，编辑您正在使用的模型，为该模型添加的自定义字段