作为一名长期深耕于安企CMS内容运营领域的专家，我深知一套灵活且高效的模板标签对于网站内容展示的重要性。其中，archiveList 标签无疑是安企CMS模板中调用文档列表的核心利器。它不仅能帮助我们精准地筛选和展示各类文档内容，还能结合多种参数，满足千变万化的内容呈现需求，从而为读者提供优质的浏览体验。
archiveList 标签的用途与基本结构
archiveList 标签在安企CMS中用于获取文档列表，无论是常规文档列表、相关文档列表，还是带有分页功能的文档列表，它都能胜任。其基本使用方法涉及定义一个变量来存储获取到的文档数据，并配合 for 循环遍历这些数据。
一个典型的archiveList标签结构如下：
{% archiveList archives with type="list" limit="10" %}
{% for item in archives %}
{# 在这里展示文档内容 #}
<h3><a href="{{item.Link}}">{{item.Title}}</a></h3>
<p>{{item.Description}}</p>
<p>发布时间: {{stampToDate(item.CreatedTime, "2006-01-02")}}</p>
{% empty %}
<p>抱歉，没有找到任何文档。</p>
{% endfor %}
{% endarchiveList %}
在这个例子中，archives 是我们定义的变量名，用于存储archiveList获取到的文档集合。{% for item in archives %} 用于遍历这个集合，item则代表集合中的每一个文档对象。当没有文档数据时，{% empty %} 区域的内容将被展示。
精准控制：archiveList 参数详解
archiveList 标签的强大之处在于其丰富的参数，通过这些参数，我们可以对调用的文档列表进行细致的筛选和排序。
模型 ID (moduleId)
这个参数用于指定要获取哪个内容模型下的文档列表。例如，如果您想获取“文章模型”下的文档，可以设置 moduleId="1"；如果想获取“产品模型”下的文档，则可能设置为 moduleId="2"。在安企CMS的后台内容管理中，每个内容模型都有其对应的ID。
分类 ID (categoryId)
categoryId 参数允许您获取指定分类下的文档列表。您可以传入单个分类ID，如 categoryId="5"，也可以传入多个分类ID，用逗号分隔，如 categoryId="1,2,3"。如果未指定此参数，archiveList 会尝试读取当前页面的分类ID。如果您希望在非分类页面上调用文档但又不想自动读取当前分类，或者明确不希望按当前分类筛选，可以显式设置 categoryId="0"。
排除分类 ID (excludeCategoryId)
与 categoryId 相反，excludeCategoryId 用于排除特定分类下的文档。这在您需要展示大部分文档但想跳过某些特定分类时非常有用，例如 excludeCategoryId="10" 将排除ID为10的分类下的所有文档。
用户 ID (userId)
如果您需要展示某个特定用户发布的文档，可以使用 userId 参数。例如，userId="1" 将只显示ID为1的用户所发布的文档。
上级文档 ID (parentId)
此参数用于获取指定上级文档的子文档。如果您的内容结构存在层级关系（例如产品详情页下的附件列表），parentId="某个文档ID" 就能派上用场。
推荐属性 (flag)
安企CMS允许为文档设置多种推荐属性，如“头条”、“推荐”、“幻灯”等。flag 参数可以帮助您根据这些属性来筛选文档，例如 flag="c" 将只显示标记为“推荐”的文档。多个属性值可以通过组合字母来设置。
排除推荐属性 (excludeFlag)
此参数用于排除具有特定推荐属性的文档，例如 excludeFlag="s" 将不会显示标记为“滚动”的文档。
是否列出文档的 flag (showFlag)
当您希望在文档列表中直接显示每个文档的推荐属性标记时，需要将 showFlag 设置为 true，默认值为 false。
是否显示子分类内容 (child)
默认情况下，当您指定 categoryId 时，archiveList 会同时包含该分类及其所有子分类下的文档（child=true）。如果您只想显示指定分类本身的文档，而不包括其子分类的文档，可以设置 child=false。
排序方式 (order)
order 参数决定了文档的显示顺序。常见的排序方式包括：
- 按最新发布排序：
order="id desc" - 按浏览量最多排序：
order="views desc" - 按后台自定义排序：
order="sort desc"（此为默认排序方式，可不填）
显示数量 (limit)
limit 参数用于控制返回的文档数量。例如，limit="10" 将只显示10条文档。当您不需要分页功能时，limit 还支持 offset 模式，例如 limit="2,10" 表示从第2条文档开始，获取10条数据。
列表类型 (type)
这是一个非常关键的参数，它决定了archiveList标签的行为模式：
type="list"(默认值)：以普通列表形式显示文档，受limit参数控制，不提供分页。type="page"：用于带有分页功能的文档列表。当使用此类型时，通常需要结合pagination标签来生成分页导航。type="related"：用于获取相关文档。在这种模式下，archiveList会尝试获取与当前文档最相关的其他文档。它还可以结合like参数进一步细化相关性判断，例如like="keywords"（按关键词相关）或like="relation"（按后台手动设置的相关文档）。
搜索关键词 (q)
当 type="page" 时，q 参数可以用于指定搜索关键词。如果您在URL中包含 q=关键词 的查询参数，archiveList 会自动读取并用于搜索标题中包含该关键词的文档。您也可以在标签中直接指定 q="您的关键词"。
筛选参数 (自定义)
在 type="page" 模式下，如果您的内容模型配置了可筛选的自定义字段（例如“房屋类型”、“价格区间”），您可以将这些字段作为URL的查询参数传递，archiveList 会根据这些参数进行高级筛选。例如，如果自定义字段为 sex，其值为 男，则可以通过URL查询参数 sex=男 来筛选。
站点 ID (siteId)
当您使用安企CMS的多站点管理功能时，如果需要调用其他站点的数据，可以通过 siteId 参数指定目标站点的ID。
组合文档 ID (combineId) 与 前置组合文档 ID (combineFromId)
这两个是高级参数，用于创建文档的组合对比页面。例如，如果您想比较两款产品A和B，可以将产品A作为主文档，产品B作为组合文档。combineId 将在主文档的URL中添加一个组合ID，例如 /tour/1/c-2.html，其中 1 是主文档ID，2 是组合文档ID。combineFromId 类似，但组合文档在前，例如 /tour/2/c-1.html。在 for 循环中，可以通过 {{combine.文档字段}} 或 {{combineArchive.文档字段}} 来访问组合文档的信息。
for 循环中可用的文档字段
在archiveList的for循环中，item变量代表每个文档对象，它包含了一系列可直接访问的字段，方便您在模板中展示。以下是一些常用的字段：
{{item.Id}}: 文档的唯一ID。{{item.Title}}: 文档标题。{{item.Link}}: 文档详情页的URL链接。{{item.Description}}: 文档简介或摘要。{{item.Keywords}}: 文档关键词。{{item.CategoryId}}: 文档所属分类的ID。{{item.Views}}: 文档的浏览量。{{item.Logo}}: 文档封面首图的URL（大图）。{{item.Thumb}}: 文档封面缩略图的URL。{{item.Images}}: 文档的多张封面图片数组，需要通过嵌套循环遍历。{{item.CreatedTime}}: 文档的创建时间（Unix时间戳），通常需要结合stampToDate过滤器格式化。{{item.UpdatedTime}}: 文档的更新时间（Unix时间戳）。{{item.Flag}}: 文档的推荐属性标记。{{item.CommentCount}}: 文档的评论数量。- 文档模型自定义字段: 如果您在后台为文档模型定义了额外的自定义字段，例如
author或price，它们也可以通过{{item.自定义字段名}}的形式直接访问。
实际应用场景与代码示例
让我们通过几个具体的场景来演示archiveList标签的强大功能。
场景一：显示最新发布的10篇文章
在网站首页或侧边栏，我们经常需要展示最新发布的内容。
<div class="latest-articles">
<h2>最新文章</h2>
<ul>
{% archiveList latestArchives with moduleId="1" order="id desc" type="list" limit="10" %}
{% for article in latestArchives %}
<li>
<a href="{{article.Link}}" title="{{article.Title}}">
<img src="{{article.Thumb}}" alt="{{article.Title}}" onerror="this.style.display='none';">
<span class="title">{{article.Title}}</span>
<span class="date">{{stampToDate(article.CreatedTime, "2006-01-02")}}</span>
</a>
</li>
{% empty %}
<li>暂无最新文章。</li>
{% endfor %}
{% endarchiveList %}
</ul>
</div>
此示例中，moduleId="1" 指定了文章模型，order="id desc" 确保按最新发布排序，type="list" 和 limit="10" 则控制了列表形式和数量。
场景二：带有分页的文章列表页
在一个分类列表页，通常需要展示该分类下的所有文章，并提供分页导航。
<div class="category-articles">
<h1>{{category.Title}}</h1> {# 假设当前页面是分类页，category变量已存在 #}
<div class="article-list">
{% archiveList articles with type="page" limit="15" %} {# 默认会获取当前分类的文档 #}
{% for article in articles %}
<div class="article-item">
<h2><a href="{{article.Link}}">{{article.Title}}</a></h2>
<p class="meta">
<span>发布于: {{stampToDate(article.CreatedTime, "2006-01-02")}}</span>
<span>分类: <a href="{% categoryDetail with name='Link' id=article.CategoryId %}">{% categoryDetail with name='Title' id=article.CategoryId %}</a></span>
<span>浏览量: {{article.Views}}</span>
</p>
<div class="description">{{article.Description}}</div>
<a href="{{article.Link}}" class="read-more">阅读更多</a>
</div>
{% empty %}
<p>该分类下暂无文章。</p>
{% endfor %}
{% endarchiveList %}
</div>
<div class="pagination-nav">
{% pagination pages with show="7" %}
<ul>
{% if pages.PrevPage %}
<li><a href="{{pages.PrevPage.Link}}">上一页</a></li>
{% endif %}
{% for p in pages.Pages %}
<li {% if p.IsCurrent %}class="active"{% endif %}><a href="{{p.Link}}">{{p.Name}}</a></li>
{% endfor %}
{% if pages.NextPage %}
<li><a href="{{pages.NextPage.Link}}">下一页</a></li>
{% endif %}
</ul>
{% endpagination %}
</div>
</div>
这里我们使用了 type="page" 和 limit="15" 来实现分页，并结合了 pagination 标签生成了分页链接。categoryDetail 标签则用于获取文章所属分类的详细信息。
场景三：在产品详情页显示相关产品
为了提升用户体验和站内流量，我们可以在产品详情页底部展示与当前产品相关的产品。
<div class="related-products">
<h3>相关产品推荐</h3>
<ul>
{% archiveList relatedProducts with type="related" like="keywords" limit="5" %}
{% for product in relatedProducts %}
<li>
<a href="{{product.Link}}" title="{{product.Title}}">
<img src="{{product.Thumb}}" alt="{{product.Title}}">
<span class="title">{{product.Title}}</span>
</a>
</li>
{% empty %}
<li>暂无相关产品。</li>
{% endfor %}
{% endarchiveList %}
</ul>
</div>
type="related" 模式下，archiveList 会智能地寻找相关文档。这里 like="keywords" 进一步指示系统根据关键词匹配相关性