模板标签手册

引入公共模板

{include file="common/header" /}

pycms:include

引入当前主题目录下的模板片段，用于头部、页脚、文章卡片等复用区块。

模板语法

<!doctype html>
<html>
<head>
    {include file="common/header" /}
</head>
<body>
    {include file="common/footer" /}
</body>
</html>

说明：file 路径相对于当前主题目录，不带 .html 后缀；片段不存在时输出空字符串。

条件判断

{if $article.is_recommend == 1}...{else}...{/if}

pycms:if

根据当前模板变量做条件输出，可嵌套；变量来自控制器注入或标签循环变量。

模板语法

{if $category.id}
    <h1>{$category.name}</h1>
{else}
    <h1>全部内容</h1>
{/if}

{if $item.is_recommend == 1}
    <span class="badge">推荐</span>
{/if}

说明：支持 ==、!=、>、<、>=、<=，也支持 {if $list} 判断数组是否为空。

循环自定义数组

{pycms:volist name="$item.children" id="child"}...{/pycms:volist}

pycms:volist

遍历标签返回的数组字段，例如导航子菜单、留言字段；content / channel / nav / tags 成对标签本身已经循环，不需要再套 volist。

参数	说明	默认	取值 / 备注
`name`	数组变量	必填	如 $item.children、$message.fields
`id`	循环变量名	item	嵌套时需唯一，如 child、field

模板语法

{pycms:nav type="head" id="nav"}
    <a href="{$nav.href}">{$nav.title}</a>
    {if $nav.children}
        {pycms:volist name="$nav.children" id="child"}
            <a href="{$child.href}">{$child.title}</a>
        {/pycms:volist}
    {/if}
{/pycms:nav}

说明：同一个页面出现多个 volist 时，id 不要重复。

模板表达式

{:__('nav.search')}

pycms:php

输出函数返回值或语言包文案，常用于多语言、Hook 与格式化；表达式由模板引擎直接执行。

模板语法

<a href="{pycms:url path="/search" /}">{:__('nav.search')}</a>
<span>{:date('Y')}</span>

说明：模板内不要写复杂业务逻辑，复杂处理放到插件或控制器。

内容列表

{pycms:content catid="$category.id" num="8"}...{/pycms:content}

pycms:content

读取文章列表，支持栏目、推荐位、关键词、标签、排序、分页与片段模板；标签本身直接循环，默认变量为 $item、序号为 $i。

参数	说明	默认	取值 / 备注
`catid`	栏目 ID	当前栏目	如 $category.id；配合 with_children 包含子栏目
`num`	输出条数	8	最大 50；分页模式下表示每页条数
`page`	是否分页	0	填 1 开启分页，配合 contentpage 输出分页条
`order`	排序字段	置顶、发布时间倒序	支持 id / publish_time / views / is_top / sort
`flag`	推荐位	空	top、recommend、hot、headline，可逗号组合
`scope`	范围	空	hot 按浏览量、recommend 只取推荐
`keyword`	关键词	空	按标题、摘要、标签模糊匹配
`tag`	标签	空	按 tags 字段匹配
`exclude`	排除文章 ID	空	常用于详情页排除当前文章
`with_children`	包含子栏目	0	填 1 时连同下级栏目一起查询
`model_fields`	模型字段	0	填 1 时列表项注入 model_fields，供 field 标签调用
`template`	片段模板	空	每行用指定片段渲染，如 common/post-card
`empty`	空数据提示	空	无内容时输出的文案
`id`	循环变量名	item	改为 post 后使用 $post.title

可用字段 $item.id$item.title$item.href / url$item.thumb / image$item.summary / summary_text$item.publish_time / publish_time_text$item.views$item.category.id / title / name / slug / href$item.flags / flags_raw$item.is_top / is_recommend / is_hot / is_headline$item.model_fields

模板语法

<div class="news-list">
    {pycms:content catid="$category.id" num="8" order="publish_time desc" empty="暂无内容" id="post"}
        <a class="news-item" href="{$post.href}">
            {if $post.thumb}<img src="{$post.thumb}" alt="{$post.title}" loading="lazy">{/if}
            <h3>{$post.title}</h3>
            <p>{$post.summary_text}</p>
            <small>{$post.category.title} · {$post.publish_time_text}</small>
        </a>
    {/pycms:content}
</div>

说明：详情页读取相关文章时加 exclude="$article.id"；单标签写法 {pycms:content catid="1" num="6" /} 会输出内置文章列表 HTML。

栏目列表

{pycms:channel type="top"}...{/pycms:channel}

pycms:channel

读取栏目列表，支持一级、子级、同级与当前顶级栏目；标签本身直接循环，默认变量为 $item。

参数	说明	默认	取值 / 备注
`type`	范围	top	top 顶级 / son 子栏目 / peer 同级 / selftop 顶级（同 top）
`name`	栏目 ID	当前栏目	type 为 son、peer 时指定父栏目或参照栏目
`num`	输出条数	20	最大 50
`model`	模型 ID	空	只输出指定内容模型的栏目
`istotal`	统计内容数	0	填 1 时每项带 total
`currentstyle`	选中样式	active	当前栏目命中的 class 名
`id`	循环变量名	item	改为 nav 后使用 $nav.title

可用字段 $item.id$item.title / name$item.href / url$item.has_child$item.total$item.currentstyle$item.initial

模板语法

{pycms:channel type="son" name="$category.id" istotal="1" id="sub"}
    <a class="{$sub.currentstyle}" href="{$sub.href}">{$sub.title}（{$sub.total}）</a>
{/pycms:channel}

说明：栏目 URL 由 /list/{slug} 生成；顶部菜单请优先使用 nav 标签。

导航菜单

{pycms:nav type="head"}...{/pycms:nav}

pycms:nav

读取后台「导航管理」的菜单，自动附带二级子菜单与当前栏目标记；成对写法直接循环，默认变量为 $item。

参数	说明	默认	取值 / 备注
`type`	位置	head	head 顶部 / footer 页脚 / 后台自定义的导航类型
`id`	循环变量名	item	改为 nav 后使用 $nav.title

可用字段 $item.id$item.title$item.href / url$item.target_html$item.currentstyle$item.children

模板语法

{pycms:nav type="head" id="nav"}
    <a href="{$nav.href}"{$nav.target_html|raw} class="{$nav.currentstyle}">{$nav.title}</a>
    {if $nav.children}
        {pycms:volist name="$nav.children" id="child"}
            <a href="{$child.href}" class="{$child.currentstyle}">{$child.title}</a>
        {/pycms:volist}
    {/if}
{/pycms:nav}

说明：也可使用单标签 {pycms:nav type="head" /} 直接输出内置导航 HTML；导航为空时自动回退到一级栏目。

标签云

{pycms:tags num="20"}...{/pycms:tags}

pycms:tags

聚合文章 tags 字段生成标签云，按出现次数排序；成对写法直接循环，默认变量为 $item。

参数	说明	默认	取值 / 备注
`num`	输出条数	20	最大 80
`id`	循环变量名	item	改为 tag 后使用 $tag.title

可用字段 $item.title / name$item.href / url$item.count$item.currentstyle

模板语法

<div class="tag-cloud">
    {pycms:tags num="20" id="tag"}
        <a href="{$tag.href}" class="{$tag.currentstyle}">{$tag.title}<small>{$tag.count}</small></a>
    {/pycms:tags}
</div>

说明：也可使用单标签 {pycms:tags num="20" /} 输出内置标签列表；标签链接指向 /tag/{名称}。

分页条

{pycms:contentpage /}

pycms:contentpage

输出 content 标签 page="1" 产生的分页条，保留当前查询参数。

模板语法

{pycms:content catid="$category.id" page="1" num="12"}
    <article><a href="{$item.href}">{$item.title}</a></article>
{/pycms:content}

<div class="pager">{pycms:contentpage /}</div>

说明：必须与 page="1" 的内容标签配对使用，否则没有分页数据；pager 是兼容别名。

面包屑

{pycms:breadcrumb catid="$category.id" /}

pycms:breadcrumb

根据栏目或当前文章生成「首页 / 栏目 / 文章」路径。

参数	说明	默认	取值 / 备注
`catid`	栏目 ID	当前栏目或文章	指定则从该栏目向上追溯
`symbol`	分隔符	/	如 » 或 >
`title`	末尾标题	空	无当前文章时用于搜索页、标签页

模板语法

{pycms:breadcrumb catid="$category.id" symbol="»" /}

说明：详情页可直接不传 catid，标签会读取当前文章栏目；当前标签页、搜索页会自动输出末尾标题。

站点配置

{pycms:config name="site_description" /}

pycms:config

读取后台「平台设置」的键值，输出时已做 HTML 转义。

参数	说明	默认	取值 / 备注
`name`	配置键	必填	如 site_name、site_description、contact_email
`default`	默认值	空	配置不存在时输出

模板语法

<p>{pycms:config name="site_description" default="盘云CMS 内容管理系统" /}</p>
<a href="mailto:{pycms:config name="contact_email" /}">联系我们</a>

说明：配置键在后台「平台设置」中维护；输出已转义，不要用于输出富文本。

配置中的链接

{pycms:config_url name="site_logo" /}

pycms:config_url

读取配置值并按站内地址生成可访问 URL，适合 Logo、Banner、备案链接等。

参数	说明	默认	取值 / 备注
`name`	配置键	必填	存储相对路径或站内路径

模板语法

<img src="{pycms:config_url name="site_logo" /}" alt="{pycms:config name="site_name" /}">
<a href="{pycms:config_url name="beian_link" /}" target="_blank">{pycms:config name="beian_no" /}</a>

说明：输出会经过 py_url() 处理，自动带上部署子目录前缀。

站内链接

{pycms:url path="/about" /}

pycms:url

生成带部署子目录前缀的站内地址。

参数	说明	默认	取值 / 备注
`path`	相对路径	/	如 /list/news、/show/12.html、/tag/PHPer

模板语法

<a href="{pycms:url path="/" /}">首页</a>
<a href="{pycms:url path="/list/news" /}">新闻中心</a>
<a href="{pycms:url path="/show/12.html" /}">文章详情</a>

说明：不要直接写死 / 开头的链接，否则子目录部署会 404。

全局资源地址

{pycms:asset path="assets/site.css" /}

pycms:asset

输出核心 public 资源目录下的文件地址，自动带部署前缀。

参数	说明	默认	取值 / 备注
`path`	资源相对路径	必填	相对于 cms public 目录

模板语法

<link rel="stylesheet" href="{pycms:asset path="assets/site.css" /}">
<script src="{pycms:asset path="assets/site.js" /}"></script>

说明：主题自己的 CSS、JS 请使用 theme_asset，避免升级主题时资源混淆。

主题资源地址

{pycms:theme_asset path="style.css" /}

pycms:theme_asset

输出当前主题目录下的资源地址，并自动附带文件版本号，适合主题 CSS、JS 与图片。

参数	说明	默认	取值 / 备注
`path`	资源相对路径	必填	相对于当前主题目录，如 style.css、assets/home.js

模板语法

<link rel="stylesheet" href="{pycms:theme_asset path="style.css" /}">
<script src="{pycms:theme_asset path="assets/home.js" /}"></script>

说明：更换主题后会自动指向新主题资源，不需要修改模板中的域名。

日期格式化

{pycms:date name="$item.publish_time" format="Y-m-d" /}

pycms:date

把时间字符串或时间戳格式化为指定格式。

参数	说明	默认	取值 / 备注
`name`	时间变量	必填	如 $item.publish_time
`format`	格式	Y-m-d	PHP date 格式，如 Y年m月d日 H:i

模板语法

<time>{pycms:date name="$item.publish_time" format="Y年m月d日" /}</time>

说明：时间为空时输出空字符串；无法解析时原样返回。

模型字段

{pycms:field name="price" /}

pycms:field

输出当前文章或列表项的模型自定义字段；详情页默认读取当前文章，列表页需传 item 并开启 model_fields="1"。

参数	说明	默认	取值 / 备注
`name`	字段标识	必填	如 price、code、detail
`item`	列表项变量	当前文章	如 $item、$post
`format`	输出格式	text	html / raw 输出富文本或图片 HTML
`default`	默认值	空	字段为空时输出

模板语法

<div class="price">{pycms:field name="price" default="免费" /}</div>
<div class="detail">{pycms:field name="detail" format="html" /}</div>

{pycms:content catid="$category.id" num="6" model_fields="1"}
    <span>{pycms:field name="price" item="$item" default="免费" /}</span>
{/pycms:content}

说明：model_field 是兼容别名；字段需在后台「模型管理」中创建并绑定到栏目模型。

CMS 版本号

{pycms:app_version /}

pycms:app_version

输出当前 pycms 版本，适合页脚版权信息。

模板语法

<span>Powered by 盘云CMS v{pycms:app_version /}</span>

说明：版本来自 config/app.php 的 app.version。

PHP 版本

{pycms:php_version /}

pycms:php_version

输出当前 PHP 版本号，用于环境说明页或调试面板。

模板语法

<span>PHP {pycms:php_version /}</span>

说明：生产环境建议不要在前台展示。

当前年份

{pycms:year /}

pycms:year

模板语法

<div class="copyright">© {pycms:year /} 盘云CMS</div>

说明：随服务器时间自动变化。

插件钩子输出

{pycms:hook name="front.head" /}

pycms:hook

输出插件注册到指定钩子的 HTML，用于在模板中插入插件功能。

参数	说明	默认	取值 / 备注
`name`	钩子名称	必填	如 front.head、front.footer、front.body.end

模板语法

<head>
    {pycms:hook name="front.head" /}
</head>
<footer>
    {pycms:hook name="front.footer" /}
</footer>

说明：钩子需由插件在启动时通过 Hook::add 注册；默认主题已预置 front.head、front.footer、front.body.end。

数组计数

{pycms:count name="$list" /}

pycms:count

输出数组元素数量，常用于统计标签返回的数组。

参数	说明	默认	取值 / 备注
`name`	数组变量	必填	如 $list、$item.children

模板语法

<span>共 {pycms:count name="$list" /} 条</span>

说明：不是数组时输出 0。

文本截取

{pycms:excerpt text="$article.content" len="90" /}

pycms:excerpt

去除 HTML 标签后截取指定长度，超出加省略号。

参数	说明	默认	取值 / 备注
`text`	原始文本	必填	可传 $item.content
`len`	长度	90	按字符数计算

模板语法

<meta name="description" content="{pycms:excerpt text="$article.content" len="120" /}">

说明：输出已转义，可直接放入 meta 或摘要区。

换行转 br

{pycms:nl2br name="$item.summary" /}

pycms:nl2br

将文本中的换行转换为 HTML 换行并转义。

参数	说明	默认	取值 / 备注
`name`	文本变量	必填	如 $item.summary

模板语法

<div class="summary">{pycms:nl2br name="$item.summary" /}</div>

说明：富文本内容不要再次使用，避免重复转义。

CSRF 隐藏域

{pycms:csrf /}

pycms:csrf

输出表单令牌隐藏域，插件前台表单需要。

模板语法

<form method="post" action="{pycms:url path="/guestbook" /}">
    {pycms:csrf /}
    <input name="content" required>
    <button>提交</button>
</form>

说明：所有 POST 表单都必须带令牌，否则被 CSRF 中间件拦截。

留言表单

{pycms:guestbookform /}

pycms:guestbookform

渲染内置留言板表单，自动带上来源栏目、回跳地址与 CSRF 令牌。

参数	说明	默认	取值 / 备注
`catid`	来源栏目 ID	当前栏目/联系我们	指定留言归属栏目
`return`	提交后回跳	当前页面	仅允许站内地址

模板语法

<section class="guestbook">
    <h2>在线留言</h2>
    {pycms:guestbookform catid="$category.id" /}
</section>

说明：留言字段来自后台「模型管理 → 表单模型」；验证码由平台设置 captcha_guestbook 控制。

留言列表

{pycms:guestbook num="30" id="message"}...{/pycms:guestbook}

pycms:guestbook

读取已审核通过的留言，支持条数与空数据提示；标签本身直接循环。

参数	说明	默认	取值 / 备注
`num`	输出条数	30	最大 100
`id`	循环变量名	item	改为 message 后使用 $message.name
`empty`	空数据提示	空	无留言时输出的文案

可用字段 $message.id$message.name$message.email$message.content$message.create_time$message.category_name$message.fields

模板语法

{pycms:guestbook num="30" id="message" empty="还没有留言，来抢沙发吧。"}
    <div class="guestbook-item">
        <strong>{$message.name}</strong>
        <time>{pycms:date name="$message.create_time" format="Y-m-d H:i" /}</time>
        <p>{$message.content}</p>
        {pycms:volist name="$message.fields" id="field"}
            <span>{$field.display|raw}</span>
        {/pycms:volist}
    </div>
{/pycms:guestbook}

说明：只显示后台审核通过的留言；字段展示使用 $message.fields 循环。

在主题中调用

把示例代码复制到主题模板文件（如 themes/default/index/index.html）即可。标签统一以 {pycms:标签名 ...} 书写，成对标签需闭合；修改后到 cms 后台「系统工具 → 清理缓存」刷新模板编译缓存。

没有找到匹配的标签

模板语法

引入公共模板

条件判断

循环自定义数组

模板表达式

内容标签

内容列表

栏目标签

栏目列表

导航与标签云

导航菜单

标签云

分页与面包屑

分页条

面包屑

配置与链接

站点配置

配置中的链接

站内链接

全局资源地址

主题资源地址

日期与工具

日期格式化

模型字段

CMS 版本号

PHP 版本

当前年份

插件钩子输出

数组计数

文本截取

换行转 br

CSRF 隐藏域

插件扩展

留言表单

留言列表

在主题中调用