模板标签与 API 的通用参数
校对日期:2026-11-16。适用于社区版及全部商业版。
取数据的模板标签(ArticleList、ChannelList 等)和对应的公开接口(GET / 等)用的是同一套参数: 条数 limit / offset、分页 page / pageSize、排序 orderBy。本文说明这几个通用参数的写法、默认值和上限, 以及分页标签返回的分页对象、生成链接的 [@A] 标签。各标签自己的筛选参数见文档站的“API 和标签”部分, 标签的基本写法见模板编写的“使用 CMS 指令取数”一节。
一、列表标签与分页标签
同一种数据通常有两个标签,区别在于取多少条、返回什么:
| 列表 | 分页 | |
|---|---|---|
| 标签 | 名称以 List 结尾,如 ArticleList、ChannelList、TagList | 名称以 Page 结尾,如 ArticlePage、TagPage |
| 接口 | GET / | GET / |
| 控制条数的参数 | limit、offset | page、pageSize |
| 返回 | 列表 | 分页对象(见“分页对象”一节) |
两组参数不能混用:给分页标签写 limit、给列表标签写 pageSize 都不起作用。
标签的参数值写成字符串或数字都可以,limit='5' 与 limit=5 等价;接口的参数放在地址里。
二、条数:limit 与 offset
| 参数 | 含义 | 不给时 | 取值 |
|---|---|---|---|
limit | 最多取多少条 | 标签:1000 条。接口:GET / 为 20 条,其它列表接口一般为 1000 条,个别接口另有默认值 | 1 到 1000。小于 1 或大于 1000 都按 1000 处理 |
offset | 跳过前面多少条,从 0 算起 | 0 | 负数按 0 处理 |
标签不写 limit 时最多会取出 1000 条,所以列表标签都应当写上 limit。
取新闻栏目的第 4 到第 8 篇文章:
[#escape x as (x)!?html]
[@ArticleList channel='news' offset='3' limit='5' orderBy='publishDate_desc,id_desc'; list]
[#list list as bean]
<a href="${bean.url}">${bean.title}</a>
[/#list]
[/@ArticleList]
[/#escape]对应的接口地址:
/api/article?channel=news&offset=3&limit=5&orderBy=publishDate_desc,id_desc三、分页:page 与 pageSize
| 参数 | 含义 | 不给时 | 取值 |
|---|---|---|---|
page | 第几页,从 1 算起 | 标签:当前页面的页码。接口:1 | 小于 1 按 1 处理;超过总页数时返回空的一页 |
pageSize | 每页多少条 | 标签:当前页面的每页条数,见下表。接口:一般为 10 | 最大 1000,超过按 1000 处理;小于 1 按 10 处理 |
分页标签通常两个参数都不写,由所在的页面决定:
| 页面 | 页码从哪里来 | 每页条数从哪里来 |
|---|---|---|
| 栏目页 | 地址里的页码,如 /channel/news/2 | 内容 → 栏目管理 中该栏目的 分页条数 |
| 专题页(标准版起) | 地址里的页码,如 /topic/{别名}/2 | 该专题的 分页条数 |
| 首页 | 地址参数 ?page=2 | 配置 → 站点设置 → 基础设置 的 每页条数 |
| 搜索、标签等其它页面 | 地址参数 ?page=2 | 10 |
模板里的全局变量 page 就是当前页码(从 1 算起),在标签外面也能用。
四、分页对象
分页标签把一个分页对象交给循环变量,默认主题统一命名为 pagedList:
| 属性 / 方法 | 类型 | 说明 |
|---|---|---|
content | 列表 | 当前页的数据,用 [#list pagedList. 遍历 |
totalElements | 整数 | 符合条件的总条数 |
totalPages | 整数 | 总页数 |
number | 整数 | 当前页的序号,从 0 算起(第 1 页是 0)。显示页码请用全局变量 page |
size | 整数 | 每页条数 |
numberOfElements | 整数 | 当前页实际有多少条,等于 content?size |
first、last | 布尔 | 是否第一页、是否最后一页 |
empty | 布尔 | 当前页是否没有数据 |
hasPrevious()、hasNext() | 布尔 | 有没有上一页、下一页。这两个是方法,要带括号 |
翻页链接用 paging(页码) 函数生成,它会按当前页面的地址规则给出第 N 页的地址:栏目页是 /channel/news/2, 搜索页这类带参数的页面是在原有参数后加 page=2,开启了静态化的页面则是静态页地址。
一个完整的分页列表:
[#escape x as (x)!?html]
[@ArticlePage channel='news' orderBy='publishDate_desc,id_desc'; pagedList]
<p>共 ${pagedList.totalElements} 篇,第 ${page} / ${pagedList.totalPages} 页</p>
<ul>
[#list pagedList.content as bean]
<li><a href="${bean.url}">${bean.title}</a></li>
[/#list]
</ul>
[#if pagedList.totalPages gt 1]
<nav>
[#if pagedList.hasPrevious()]<a href="${paging(page - 1)}">上一页</a>[/#if]
[#list 1..pagedList.totalPages as p]
[#if p == page]<span>${p}</span>[#else]<a href="${paging(p)}">${p}</a>[/#if]
[/#list]
[#if pagedList.hasNext()]<a href="${paging(page + 1)}">下一页</a>[/#if]
</nav>
[/#if]
[/@ArticlePage]
[/#escape]默认主题把翻页部分做成了片段 snippets/(首页、上一页、5 个页码、下一页、末页),在分页标签内部 [#include '. 即可,前提是循环变量名为 pagedList。
接口返回的 JSON 与模板里的对象结构不同:只有 content 和 page 两项,页码信息在 page 下,数值以字符串给出, 其中 number 同样从 0 算起:
{"content": [...], "page": {"size": "10", "number": "0", "totalElements": "47", "totalPages": "5"}}五、排序:orderBy
orderBy 的值是一个或多个“字段 + 方向”,用逗号分隔,排在前面的优先:
orderBy='sticky_desc,order_desc'- 字段写属性名(驼峰写法),如
publishDate、id。 - 方向是后缀
_desc(从大到小)或_asc(从小到大),必须小写;不写就是从小到大。 - 逗号后面可以有空格。
- 关联表的字段写成
@表名-字段。文章的浏览量、下载量等统计数字保存在文章扩展表里,要写@articleExt-views_, 直接写desc views_desc会报错。
文章常用的排序字段:
| 写法 | 含义 |
|---|---|
publishDate_ | 发布日期,新的在前 |
order_desc | 排列顺序:默认按新增的先后,后加的在前;在文章管理里拖动调整的就是它 |
sticky_desc | 置顶值,大的在前。一般写成 sticky_,让置顶文章排在最前面 |
id_desc | 文章 ID。常放在最后,避免发布日期相同的文章顺序不固定 |
@articleExt-views_ | 总浏览量。日、周、月、季、年浏览量分别是 dayViews、weekViews、monthViews、quarterViews、yearViews |
@articleExt-downloads_ | 下载次数。评论数、收藏数、顶、踩分别是 comments、favorites、ups、downs |
不写 orderBy 时各标签有自己的默认顺序:ArticleList / ArticlePage 是 order_desc,ChannelList 是 order,id (栏目管理里的顺序),TagList / TagPage 是 refers_(被引用多的在前)。
标签与接口的写法相同:
[#escape x as (x)!?html]
[@ArticleList channel='news' orderBy='@articleExt-yearViews_desc' limit='10'; list]
[#list list as bean]
<a href="${bean.url}">${bean.title}</a>
[/#list]
[/@ArticleList]
[/#escape]/api/article?channel=news&orderBy=@articleExt-yearViews_desc&limit=10两点限制:
- 接口不允许按敏感内容排序。 关联用户、组织、角色、用户组等表的写法,以及 IP、手机号、邮箱、密码一类的字段、文章正文, 接口会返回 400(
Query not allowed)。模板标签由主题作者编写,不受这条限制。 - 全文检索不走这套规则。
EsArticleList、EsArticlePage和接口/api/article/es不写orderBy时按相关度排序, 上面的关联表写法对它们无效。
六、[@A] 标签
[@A] 根据一个对象生成 <a> 链接,省去手写地址、标题和“新窗口打开”的判断:
[@A bean=article length=10 class='cm-link'/]输出:
<a href="/article/405429838002714626-8-02" title="最后一跳8米02 本土小将逆转夺得跳远金牌" target="_blank" class="cm-link">最后一跳8米02 本土...</a>| 参数 | 说明 |
|---|---|
bean | 要链接的对象:站点、栏目、文章、专题、区块项、链接组里的链接、全文检索结果都可以。不写这个参数时标签什么也不输出 |
target | 链接的 target。不写时,对象(栏目、文章、区块项、链接)勾选了 新窗口打开 就输出 target="_blank",否则不输出 |
title | 链接的 title 属性。不写或为空时用对象的名称(文章是标题) |
length | 链接文字的最大长度,按中文字数计,两个英文字母或数字算一个字。超过时截断;不写则不截断 |
append | 截断后追加的文字,默认 ...。写 append='' 表示不追加 |
| 其它参数 | 原样输出为 <a> 的属性,如 class、style、rel |
标签有内容时,内容作为链接文字,length 与 append 不再起作用:
[#escape x as (x)!?html]
[@A bean=article class='cm-link']<strong>${article.title}</strong>[/@A]
[/#escape]地址、标题和链接文字由标签自己做 HTML 转义,不需要再处理。bean 必须是一个存在的对象:变量可能为空时, 先用 [#if article??] 判断,写成 bean=article! 会报错。
只需要地址时不必用这个标签,直接写 <a href= 即可。
七、按自定义字段筛选文章
自定义字段作查询条件,写成 操作符_,放进 Q_ 参数:
[@ArticleList channel='camera' Q_={'EQ_@articleExt-mainsJson$typeKey': '2', 'GT_@articleExt-mainsJson$price_Int': '8000'} limit='10'; list]
…
[/@ArticleList]/api/article?Q_EQ_@articleExt-mainsJson$typeKey=2&Q_GT_@articleExt-mainsJson$price_Int=8000- 多个条件同时满足。操作符:
EQ、NE、GT、GE、LT、LE、In(值用逗号分隔)、Contains。 - 绑定字典的字段,
字段代码下是名称,字段代码Key下是键值,按键值查更稳妥。 - 多选字段用
ArrayEQ(包含该值)或ArrayIn(包含其中任一),用EQ查不到。 - 数字字段(计数器、滑块)比较大小要加类型后缀
_Int,不加会按文字比较,结果不对。 - 也可排序:
orderBy=。'@articleExt-mainsJson$price_ desc' - 开启了 大字段 的字段不能用于筛选,接口返回 400。
- 完整的筛选页见默认主题
templates/。channel_ product. html
八、常见问题
分页标签写了 limit='10',每页条数没有变。 分页标签只认 pageSize。不写时用所在页面的每页条数(见“分页:page 与 pageSize”一节)。
pagedList. 比实际页码小 1。 它从 0 算起。显示页码、拼翻页链接都用全局变量 page。
接口 /api/article 只返回 20 条。 这是该接口不带 limit 时的默认条数,需要更多就写 limit,最多 1000;数据更多时用 /api/ 翻页。
加了 orderBy 后页面或接口报错。 字段名写错、把扩展表的字段当成了主表字段(如 views_desc),或者方向写成了大写。大写的 _DESC 不报错,但不会按倒序排。 接口返回 400 且提示 Query not allowed 时,是用了不允许的字段,见“排序:orderBy”一节。