在安企CMS的模板设计中，我们经常会遇到需要定义并遍历一些固定或小型的数组数据的情况。虽然大多数动态内容会通过内置的标签如archiveList、categoryList等获取，但对于一些本地化配置、自定义选项或静态列表，直接在模板中处理数组会更加便捷。安企CMS提供了list过滤器，配合for循环标签，就能轻松实现这一需求。

认识list过滤器：模板中的数组构造器

list过滤器是安企CMS模板引擎中一个实用的工具，它允许我们将一个字符串形式的数组字面量直接转换为可遍历的数组对象。这对于在模板中定义一些固定的选项集合、导航项标识符或是其他简短的数据列表非常有用。

它的基本用法是，将一个符合JSON数组格式的字符串传递给它，然后通过|list过滤器进行转换。通常，我们会结合set标签将转换后的数组赋值给一个变量，以便后续使用。

例如，如果我们想在模板中定义一个包含几个关键词的数组：

{% set myKeywords = '["安企CMS","模板","内容管理","GoLang"]'|list %}

在这段代码中，'["安企CMS","模板","内容管理","GoLang"]'是一个字符串，而|list过滤器则负责将这个字符串解析成一个真正的数组对象，并赋值给名为myKeywords的变量。值得注意的是，即使数组中包含看起来像数字的值（例如'["item", 123, "another"]'），list过滤器在解析时也会将其内部元素都视为字符串类型。

使用for循环：遍历数组的通用方法

一旦我们通过list过滤器成功定义了一个数组变量，就可以利用模板引擎内置的for循环标签来遍历它的每一个元素。for循环在安企CMS模板中扮演着核心的角色，它能迭代任何可遍历的对象，包括我们刚刚创建的数组。

一个典型的for循环结构如下：

{% for item in myKeywords %}
    <!-- 在这里处理每一个 item -->
{% endfor %}

在每次循环中，item变量会依次持有数组中的一个元素。你可以直接使用{{ item }}来输出当前元素的值。

为了更好地控制和显示遍历过程，for循环还提供了一些实用的辅助变量：

  • forloop.Counter: 当前循环的序号，从1开始计数。
  • forloop.Revcounter: 剩余未循环的元素数量。

此外，当数组可能为空时，for循环还有一个优雅的empty子句，用于在数组没有元素时显示特定的内容，避免页面空白或报错：

{% for item in myKeywords %}
    <li class="keyword-item">第{{ forloop.Counter }}个关键词：{{ item }}</li>
{% empty %}
    <li>当前没有关键词可显示。</li>
{% endfor %}

结合实际场景：让模板更灵活

了解了list过滤器和for循环的基本使用后，我们可以在多种实际场景中应用它们，让模板的灵活性和可维护性得到提升。

例如，在一个产品详情页，你可能需要展示一些固定的产品特性列表，这些特性在不同产品模型中略有差异，但不适合通过后台的自定义字段来管理（因为它们是固定的选项，而不是输入值）。这时，你可以在模板中定义一个特性数组：

{% set productFeatures = '["防水防尘", "超长续航", "高清显示屏"]'|list %}
<div class="product-features">
    <h3>核心功能</h3>
    <ul>
        {% for feature in productFeatures %}
            <li><i class="icon-check"></i> {{ feature }}</li>
        {% empty %}
            <li>暂无核心功能介绍。</li>
        {% endfor %}
    </ul>
</div>

另一个常见的场景是在网页的页脚或侧边栏展示社交媒体链接图标。如果你希望这些图标的顺序和种类是固定的，并且可以轻松地在模板中调整，list过滤器就非常适合：

{% set socialIcons = '["facebook", "twitter", "linkedin", "youtube"]'|list %}
<div class="social-media">
    {% for platform in socialIcons %}
        <a href="/{{ platform }}" target="_blank" title="访问我们的{{ platform }}主页">
            <i class="fab fa-{{ platform }}"></i>
        </a>
    {% endfor %}
</div>

通过这种方式，我们可以将一些轻量级、静态的数据直接嵌入到模板中，提高了模板的自给自足能力，减少了对后端动态数据请求的依赖。

小贴士

  • 数据类型统一： 如前所述，list过滤器会将所有元素解析为字符串。如果你需要对数组中的“数字”进行数学运算，需要先使用|integer或|float过滤器进行类型转换。
  • 适用范围： list过滤器最适合定义那些内容相对固定、数量不大的列表数据。对于大量或频繁变动的数据，仍然推荐通过安企CMS的后台内容管理功能来发布和管理，并使用相应的标签（如archiveList）来获取。
  • 调试技巧： 在开发过程中，如果你不确定list过滤器是否正确地将字符串转换为了数组，或者想查看数组的实际内容，可以使用|stringformat:"%#v"或|dump过滤器来打印变量的详细信息，例如：{{ myKeywords|stringformat:"%#v" }}，这会输出数组在Go语言内部的详细结构，帮助你调试。

掌握list过滤器和for循环的结合使用，能够帮助我们更高效、更灵活地构建安企CMS模板，处理各种简单的列表数据展示需求。

常见问题（FAQ）

  1. 问：通过list过滤器定义的数组，如果元素是数字，可以直接进行数学运算吗？ 答： 不可以。list过滤器会将所有数组元素都视为字符串类型。即使你定义如'["10", "20"]'|list，数组中的”10”和”20”仍然是字符串。如果你需要在循环中对这些元素执行数学运算（例如求和或比较大小），你需要先使用|integer或|float过滤器将它们显式地转换为数字类型，例如{{ item|integer }}。

  2. 问：list过滤器可以用来定义嵌套数组或更复杂的对象结构吗？ 答： list过滤器目前主要用于将简单的字符串数组字面量转换为字符串类型的数组（即[]string{}）。它不支持直接定义嵌套数组（如[['a','b'],['c','d']]）或包含键值对的复杂对象结构。对于需要处理更复杂数据结构的场景，通常建议通过控制器（后端）将数据处理成相应的对象或数组形式，然后作为模板上下文变量传递给模板进行渲染。

  3. 问：如果通过list过滤器定义的数组最终是空的，页面会报错吗？如何优雅地处理？ 答： 如果通过list过滤器定义了一个空数组（例如'[]'|list），并使用for循环遍历，页面不会报错。为了提供更好的用户体验，for循环标签提供了一个{% empty %}子句。当for循环遍历的数组为空时，{% empty %}和{% endfor %}之间的内容就会被渲染出来，你可以利用它来显示“暂无数据”或“列表为空”等提示信息。