如何在安企CMS模板中循环显示文档列表，并为每个文档输出其自定义参数？

AnQiCMS 提供了强大的模板定制能力，让我们可以根据网站的实际需求，灵活地展示各种内容。当我们不仅需要循环显示文档列表，还希望为每个文档输出其特有的自定义参数时，AnQiCMS 的模板标签能够很好地帮助我们实现这一点。这对于展示产品详情、房产信息、招聘岗位等拥有多样化属性的内容模型尤为重要。

第一步：掌握文档列表的循环显示

首先，我们需要使用 archiveList 标签来获取并循环显示文档列表。这个标签是 AnQiCMS 中用于内容列表展示的核心工具。

我们通常会在模板中使用 {% archiveList %} 标签来指定要获取的文档集合，并通过 {% for item in archives %} 这样的循环结构来遍历每个文档。

例如，如果我们想获取某个分类下的文章列表，可以这样编写代码：

{% archiveList archives with categoryId="1" type="list" limit="10" %}
    {% for item in archives %}
        <div class="document-item">
            <h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
            <p>发布时间：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</p>
            <p>浏览量：{{ item.Views }}</p>
            <p>{{ item.Description }}</p>
            {# 在这里我们将展示自定义参数 #}
        </div>
    {% empty %}
        <p>当前分类下没有文档。</p>
    {% endfor %}
{% endarchiveList %}

在这段代码中：

  • archives 是我们自定义的变量名，它会包含 archiveList 返回的文档数据集合。
  • categoryId="1" 指定了要获取分类 ID 为 1 的文档。您可以根据实际情况替换为需要展示的分类 ID。
  • type="list" 表示获取非分页列表，limit="10" 则限制了显示数量为 10 条。
  • item.Link、item.Title、item.CreatedTime、item.Views、item.Description 都是文档的内置字段，可以直接通过 item. 加上字段名来访问。stampToDate 过滤器则用于格式化时间戳。

第二步：为每个文档输出自定义参数

安企CMS 允许用户在后台自定义内容模型字段（如在“内容管理” -> “内容模型”中添加“作者”、“来源”、“价格”等字段）。这些自定义字段在模板中可以通过两种主要方式来访问：

方式一：直接访问已知名称的自定义参数

如果您知道自定义参数的“调用字段”名称（在后台定义内容模型时设置的英文小写字段名，例如 author、price），可以直接通过 item.自定义字段名 的形式在 archiveList 的循环中访问它们。这是最简洁高效的方式。

假设您在后台为文章模型添加了一个名为“文章作者”，调用字段为 author 的自定义参数，以及一个名为“文章来源”，调用字段为 source 的自定义参数。

{% archiveList archives with categoryId="1" type="list" limit="10" %}
    {% for item in archives %}
        <div class="document-item">
            <h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
            <p>发布时间：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</p>
            <p>浏览量：{{ item.Views }}</p>
            <p>{{ item.Description }}</p>
            {% if item.author %}
                <p>作者：{{ item.author }}</p>
            {% endif %}
            {% if item.source %}
                <p>来源：{{ item.source }}</p>
            {% endif %}
        </div>
    {% endfor %}
{% endarchiveList %}

这种方式直观且易于维护，适用于您明确知道要显示哪些自定义参数的场景。

方式二：循环展示文档的所有自定义参数

当您需要展示某个文档的所有自定义参数，或者自定义参数名称不固定（例如，希望一个模板能适应不同内容模型下的自定义参数展示）时，可以使用 archiveParams 标签。这个标签能够获取指定文档的所有自定义参数，并允许您循环遍历它们。

archiveParams 标签需要一个 id 参数来指定要获取哪个文档的自定义参数。在 archiveList 的循环中，这个 ID 就是当前循环文档的 item.Id。

{% archiveList archives with categoryId="1" type="list" limit="10" %}
    {% for item in archives %}
        <div class="document-item">
            <h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
            <p>发布时间：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</p>
            <p>浏览量：{{ item.Views }}</p>
            <p>{{ item.Description }}</p>

            <div class="custom-params">
                <h3>自定义属性：</h3>
                {% archiveParams params with id=item.Id %}
                    {% for param in params %}
                        <p>{{ param.Name }}：{{ param.Value | safe }}</p>
                    {% endfor %}
                {% endarchiveParams %}
            </div>
        </div>
    {% empty %}
        <p>当前分类下没有文档。</p>
    {% endfor %}
{% endarchiveList %}

在这段代码中：

  • {% archiveParams params with id=item.Id %} 获取了当前循环文档 (item) 的所有自定义参数，并将其存储在 params 变量中。
  • {% for param in params %} 循环遍历了这些自定义参数。
  • param.Name 显示自定义参数的中文名称（如“文章作者”）。
  • param.Value 显示自定义参数的具体值。
  • | safe 过滤器在这里非常重要。如果您的自定义参数中可能包含 HTML 内容（例如，在后台使用了富文本编辑器填写），safe 过滤器会阻止模板引擎对这些 HTML 代码进行转义，从而让其正常渲染。

选择哪种方式取决于您的具体需求。如果您需要精确控制哪些自定义参数显示，并且知道它们的名称，直接访问方式会更简洁。如果您需要通用地显示所有自定义参数，或者自定义参数集合经常变化，循环遍历方式则更具灵活性。

实用技巧与注意事项

  • 条件判断：在显示自定义参数时，最好使用 {% if item.自定义字段名 %} 或 {% if param.Value %} 进行判断，以避免在某些文档没有填写该参数时出现空白或不必要的标签。
  • 数据类型处理：AnQiCMS 的自定义参数可以设置为多种类型（单行文本、多行文本、数字、单选、多选等）。在模板中，param.Value 或 item.自定义字段名 会直接输出其内容。对于特殊类型，例如图片或文件，其值通常是资源的 URL，您可以直接将其作为 <img> 标签的 src 属性或 <a> 标签的 href 属性来使用。
  • CSS 样式：自定义参数的展示效果完全取决于您在模板中应用的 CSS 样式，您可以根据设计需求灵活调整。
  • 自定义参数的图片和文件：如果自定义参数是一个图片字段，item.图片自定义字段名 或 param.Value 会直接输出图片 URL。您可以使用 <img> 标签来显示它，例如 <img src="{{ item.image_field }}" alt="{{ item.Title }}" />。

通过上述方法，您可以灵活地在 AnQiCMS 模板中循环显示文档列表，并为每个文档输出其特定的自定义参数，从而构建出功能丰富、内容多样的网站页面。

常见问题解答 (FAQ)

Q1: 我如何在文档列表页面根据自定义参数的值进行筛选？ A1: AnQiCMS 提供了 archiveFilters 标签，专门用于根据文档的各项自定义参数进行筛选。您可以在列表页面的顶部使用此标签来生成筛选条件，例如房屋类型、价格范围等。配合 archiveList 标签的 type="page" 和适当的 moduleId，页面便能动态地根据用户选择的自定义参数值来显示匹配的文档列表。

Q2: 如果某个文档没有填写某个自定义参数，模板会报错吗？如何处理？ A2: 如果文档未填写某个自定义参数，直接访问 {{ item.自定义字段名 }} 或 {{ param.Value }} 通常不会导致模板报错，但可能会输出空值。为了更好地用户体验，建议在使用前添加条件判断。例如，使用 `{% if item.author %}

作者：{{ item.author