如何使用`archiveList`标签，在安企CMS中灵活构建各种文档列表和分页显示？
在安企CMS中管理和展示内容是核心操作，其中archiveList标签扮演着至关重要的角色。它不仅能帮助我们灵活地呈现文章、产品等各类文档列表，还能与分页功能无缝衔接，满足各种复杂的内容展示需求。
认识archiveList标签：内容展示的利器
archiveList标签是安企CMS模板中用于获取文档列表的核心工具。无论我们想在首页展示最新文章、在分类页显示特定产品，或者在文章详情页推荐相关内容，archiveList都能轻松应对。它的强大之处在于其丰富的参数，允许我们精确控制内容的筛选、排序和展示方式。
archiveList的核心能力与常用参数
使用archiveList的基本语法是{% archiveList 变量名称 with 参数 %}...{% endarchiveList %}。其中，“变量名称”是你为获取到的文档列表自定义的名字，在标签内部可以通过这个名字进行遍历。接下来，我们详细了解一下它的一些常用参数：
指定内容模型（
moduleId） 安企CMS支持灵活的内容模型，如文章、产品等。通过moduleId参数，你可以指定希望获取哪个模型下的文档。例如，moduleId="1"可能代表文章模型，而moduleId="2"可能代表产品模型。这让你可以轻松地在不同页面展示不同类型的内容。按分类筛选（
categoryId/excludeCategoryId） 如果你希望获取特定分类下的文档，可以使用categoryId参数，支持单个ID或多个ID用逗号分隔。比如，categoryId="1,2,3"会列出ID为1、2、3的分类下的文档。相反，excludeCategoryId则可以帮助你排除某些分类。如果页面本身就处于某个分类下，archiveList默认会读取当前分类ID，如果你不想这样，可以显式设置categoryId="0"。控制显示数量与偏移（
limit）limit参数用于控制每次调用显示多少条文档。如果你只想获取前10条最新内容，可以设置limit="10"。limit还支持“偏移模式”，比如limit="2,10"表示从第3条内容开始，获取10条数据（跳过前2条）。灵活的排序方式（
order） 内容的排序方式多种多样，order参数为你提供了多种选择：order="id desc"：按文档ID倒序，通常用于显示最新发布的文档。order="views desc"：按浏览量倒序，用于展示热门内容。order="sort desc"：按后台自定义排序字段倒序。默认情况下，如果不指定order，系统会采用自定义排序。
利用推荐属性（
flag/excludeFlag/showFlag） 安企CMS允许你为文档设置多种推荐属性，如头条[h]、推荐[c]、幻灯[f]等。flag="c"可以筛选出带有“推荐”属性的文档。excludeFlag则用于排除具有特定属性的文档。如果你想在列表项中显示文档的推荐属性，showFlag=true会帮你实现。定义列表类型（
type）type参数是archiveList的一个关键属性，它决定了标签的工作模式：type="list"：默认模式，只按照limit参数获取指定数量的文档。type="page"：分页模式，常用于列表页，与pagination标签配合使用，实现分页显示。type="related"：相关文档模式，在文档详情页使用，用于获取与当前文档相关的其他文档。它还可以结合like="keywords"（按关键词关联）或like="relation"（按后台手动设置的关联文档）进一步细化关联逻辑。
搜索关键词（
q） 当type="page"时，q参数可以用于实现文档搜索。你可以显式设置q="你的关键词"，或者更智能地，archiveList会自动读取URL中名为q的查询参数作为搜索关键词。自定义筛选参数 这是一个高级功能，如果你的内容模型定义了自定义字段并设置为可筛选，那么这些字段可以通过URL查询参数的形式作为筛选条件。例如，如果有一个自定义字段
sex，你可以通过url?sex=男来筛选性别为“男”的文档。这通常与archiveFilters标签一起使用，构建复杂的筛选界面。多站点数据调用（
siteId） 如果你在使用安企CMS的多站点管理功能，并且需要调用其他站点的数据，可以通过siteId参数指定目标站点ID。组合文档（
combineId/combineFromId） 这是一对非常有意思的参数，用于构建“组合文档”的列表。例如，在旅行网站中，可以组合“北京”和“上海”两篇文档，生成“从北京到上海的旅游线路”这样的标题和链接。combineId用于在当前文档后附加一个文档，combineFromId则用于在前置附加。
实际应用场景：灵活构建内容列表
了解了这些参数，我们来看看如何在实际项目中灵活运用archiveList。
场景一：展示普通文档列表
假设你希望在网站首页展示最新发布的5篇新闻资讯。
{% archiveList latestNews with moduleId="1" limit="5" order="id desc" %}
{% for item in latestNews %}
<div class="news-item">
<a href="{{ item.Link }}">{{ item.Title }}</a>
<span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
</div>
{% endfor %}
{% endarchiveList %}
这里，latestNews是我们的变量名，moduleId="1"假定新闻属于文章模型，limit="5"限制显示5条，order="id desc"确保是最新的。
场景二：构建带分页的文档列表
在分类页或搜索结果页，我们经常需要分页显示大量内容。这时type="page"和pagination标签是**搭档。
{% archiveList archives with type="page" moduleId="1" categoryId="10" limit="10" q=urlParams.q %}
{% for item in archives %}
<div class="article-summary">
<a href="{{ item.Link }}">
<h3>{{ item.Title }}</h3>
{% if item.Thumb %}<img src="{{ item.Thumb }}" alt="{{ item.Title }}">{% endif %}
<p>{{ item.Description|truncatechars:100 }}</p>
</a>
<small>发布于 {{ stampToDate(item.CreatedTime, "2006-01-02") }} | 浏览量：{{ item.Views }}</small>
</div>
{% empty %}
<p>抱歉，当前分类下没有找到任何内容。</p>
{% endfor %}
{# 分页代码 #}
<div class="pagination-container">
{% pagination pages with show="5" %}
<a class="first-page {% if pages.FirstPage.IsCurrent %}active{% endif %}" href="{{ pages.FirstPage.Link }}">首页</a>
{% if pages.PrevPage %}<a class="prev-page" href="{{ pages.PrevPage.Link }}">上一页</a>{% endif %}
{% for pageItem in pages.Pages %}
<a class="page-number {% if pageItem.IsCurrent %}active{% endif %}" href="{{ pageItem.Link }}">{{ pageItem.Name }}</a>
{% endfor %}
{% if pages.NextPage %}<a class="next-page" href="{{ pages.NextPage.Link }}">下一页</a>{% endif %}
<a class="last-page {% if pages.LastPage.IsCurrent %}active{% endif %}" href="{{ pages.LastPage.Link }}">尾页</a>
{% endpagination %}
</div>
{% endarchiveList %}
这个例子中，type="page"开启分页模式，categoryId="10"限定分类，limit="10"表示每页10条。q=urlParams.q则会自动读取URL中的搜索关键词。pagination标签紧随其后，利用pages变量（由archiveList在type="page"时自动提供）来构建完整的页码导航。show="5"表示最多显示5个中间页码按钮。
场景三：展示相关文档
在文章详情页，我们通常会推荐一些相关内容，提高用户粘性。
{% archiveList relatedArticles with type="related" limit="6" %}
{% if relatedArticles %}
<h4>相关推荐</h4>
<ul class="related-list">
{% for item in relatedArticles %}
<li><a href="{{ item.Link }}">{{ item.Title }}</a></li>
{% endfor %}
</ul>
{% endif %}
{% endarchiveList %}
这里type="related"让系统自动根据当前文档找到相关内容，limit="6"限制数量。如果需要更精细的控制，可以添加like="keywords"或like="relation"参数。
场景四：多分类、多模型混合展示
有时，你可能需要在同一页面循环多个分类，并在每个分类下显示其文档。
{% categoryList categories with moduleId="1" parentId="0" %}
{% for category in categories %}
<section>
<h2><a href="{{ category.Link }}">{{ category.Title }}</a></h2>
<ul>
{% archiveList articlesInCategory with type="list" categoryId=category.Id limit="5" %}
{% for article in articlesInCategory %}
<li><a href="{{ article.Link }}">{{ article.Title }}</a></li>
{% empty %}
<li>该分类暂无文章。</li>
{% endfor %}
{% endarchiveList %}
</ul>
</section>
{% endfor %}
{% endcategoryList %}
此例中，我们先用categoryList获取顶级分类，然后在循环中对每个分类使用archiveList来获取其下的文章。
archiveList返回的数据结构（item）
在archiveList标签内部，通过for item in 变量名称循环时，item对象包含了文档的丰富信息，你可以直接通过{{ item.字段名 }}的方式调用，例如：
item.Id：文档IDitem.Title：文档标题item.Link：文档链接item.Description：文档描述item.Thumb：文档缩略图地址item.CreatedTime：文档创建时间戳（需要用stampToDate过滤器格式化）item.Views：文档浏览量item.Flag：文档推荐属性（需showFlag=true）- 以及所有在后台内容模型中自定义的字段，例如
item.Author、item.Price等。
小结
archiveList标签是安企CMS内容运营和模板开发的基石之一。通过熟练掌握它的各项参数和灵活运用场景，你可以轻松构建出功能强大、用户体验良好的各类内容展示页面。结合pagination等辅助标签，无论是简单的列表还是复杂的筛选分页，都能高效实现。
常见问题 (FAQ)
Q1: archiveList和categoryList标签有什么区别？我该如何选择？
A1: archiveList主要用于获取文档（如文章、产品）的列表，它的结果是具体的文档项。而categoryList则用于获取分类的列表，它的结果是分类项。
选择的关键在于你想展示什么：
- 如果你想显示“最新文章”、“热门产品”或者“某个分类下的具体文章列表”，就使用
archiveList。 - 如果你想显示“所有产品分类”、“新闻分类列表”或者“带有子分类的导航菜单”，就使用
categoryList。 两者经常结合使用，例如在一个分类列表的循环中，嵌套一个archiveList来显示该分类下的文档，就像文章中的场景四示例。
Q2: 我在内容模型中自定义了一些字段，比如“作者（author）”和“来源（source）”，如何在archiveList中显示它们？
A2: 当你通过archiveList获取文档列表后，每个item对象都会自动包含你在内容模型中自定义的字段。你可以像调用内置字段一样直接使用它们。例如，如果你自定义了author字段，在循环中可以直接通过{{ item.Author }}来显示作者信息。
Q3: 我的archiveList设置了type="page"，但分页导航（pagination）没有显示或者显示不正确，可能是什么原因？
A3: 出现这种情况，通常有以下几个原因：
- 忘记调用
pagination标签：archiveList设置type="page"后，只会准备分页数据，你需要单独在{% endarchiveList %}之后调用{% pagination pages with show="5" %}...{% endpagination %}来渲染分页导航。 pages变量未正确传递： 确保pagination标签使用的变量名与archiveList（当type="page"时）内部自动生成的pages变量一致。- 列表内容不足一页：