xiis内容列表标签的参数与字段用法

xiis 内容列表标签是模板中使用频率最高的循环标签，承担文章、产品、案例等列表型页面的渲染。参数覆盖数量、栏目、排序、分页、文字属性与摘要截取，字段标签提供标题、链接、摘要、封面与统计信息的取值入口，两块内容配合即可完成列表页的全部输出。

核心参数的分组理解

内容列表的参数可以按功能分为四组：范围类参数确定取哪一批数据，排序类参数确定顺序，展示类参数确定输出形态，分页类参数开启翻页。范围类包括栏目、标签id、关键词、状态与包含子栏目；排序类包括排列方式与排序方向；展示类包括数量、起始、标题字数、摘要字数与时间格式；分页类只有启用分页一个开关。

范围类参数

栏目参数按栏目过滤内容，不传时页面自动感知当前栏目；标签id参数在标签详情页自动从上下文获取，通常不需要显式传入；关键词参数开启搜索过滤，与搜索页的上下文联动。包含子栏目参数有三个取值：强制包含、强制不包含与智能默认。智能默认只对顶级栏目生效——顶级栏目自身没有已发布内容且存在子栏目时自动包含子栏目，其余场景只查自身，性能上不产生额外查询。

排序类与展示类参数

排列方式支持编号、发布时间、更新时间、点击量、评论量、点赞量、收藏量、分享量、下载量与随机等取值，全部走排序白名单，非法字段回退为默认排序；排序方向写升序或降序，也可以写 asc 或 desc。展示类参数中，标题字数与摘要字数按字符数截取，时间格式设置列表级时间格式，字段级格式的优先级高于列表级。

分页与自增字段

启用分页参数打开分页上下文，配合栏目分页标签输出翻页控件，两者需要同时出现，否则分页控件拿不到总数与页码数据。所有循环标签还内置自增字段：自增id 从 1 开始、索引0 从 0 开始、总数返回循环条数，常用于输出序号或把总数写进元素的数据属性。

字段标签的取值清单

内容列表内部可用的字段标签覆盖内容主表与关联信息：标题、摘要、封面图、正文、作者名称与头像、发布时间、各类计数、分类名称与分类链接、标签列表与标签列表智能链接，以及内容链接、别名链接、智能链接三个链接字段。链接字段优先使用智能链接，它会按链接配置自动选择 ID 形态或别名形态，模板无需关心站点启用的 URL 策略。

与搜索页的联动

搜索页沿用同一个内容列表标签：启用分页并开启搜索上下文后，关键词过滤与总数统计自动接入搜索请求，搜索分页标签输出带关键词的翻页链接。搜索结果为空时列表输出为空，页面其余部分正常渲染，不需要为无结果场景单独编写模板分支。

分页启用后，内容列表标签与栏目分页标签构成一对固定组合。分页控件支持页码数量、显示项、信息文字与样式类等参数，可以按站点风格定制外观；在标签详情页中控件会自动识别页面类型，输出指向当前标签的分页地址。

使用要点

• 列表页不传栏目参数时自动感知当前栏目，同一模板可在多个栏目复用
• 排序字段必须在白名单内，非法值回退为默认排序而不是报错
• 摘要字数按字符截取，输出的截断结果不破坏 HTML 结构
• 分页与总数统计口径一致，启用分页后总数由分页上下文提供

内容列表标签的参数设计围绕范围、顺序、展示、分页四个维度展开，字段标签以内容主表与关联信息为边界。把参数写全、把字段选对、把分页配对，列表页模板就能稳定覆盖栏目、标签与搜索三类页面。