核心模板标签参考

更新时间：2026-05-07

本文记录 TanzCMS 当前核心模板标签的常用参数、别名和推荐写法。后台“插件管理 → 模板标签生成器”应与本文保持一致。

零、完整场景片段

后台“模板标签生成器”新增“完整场景”分组，优先给站长生成可直接复制进主题模板的片段。当前第一批场景只使用已经稳定支持的核心标签和已启用插件标签：

• 首页完整场景：头尾模板、顶部栏目导航、最新内容、推荐内容。
• 栏目列表页完整场景：面包屑、栏目标题描述、子栏目导航、分页内容列表。
• 详情页完整场景：面包屑、标题、发布时间、浏览量、正文、内容购买按钮、相关内容。
• 搜索页完整场景：搜索表单、排序链接、分页搜索结果。
• 会员登录状态：已登录显示会员中心、资料、订单和退出；未登录显示登录、注册和游客查单。
• 订单购买按钮：调用订单模块 {member_order} 输出价格和购买入口。

说明：上一篇/下一篇、面包屑、相关文章、会员状态 已作为核心前台业务标签落地；订单购买由订单模块的 {member_order} / {order_buy} 提供。

一、内容列表：content

{content} 是内容列表主标签，{module} 只作为兼容别名保留。新模板和标签生成器优先使用 {content}。

常用参数：

• module / model：内容模型代码，例如 article。
• catid / category_id：栏目 ID，可写数字或变量 $catid。
• category：栏目 slug。
• child=1：包含子栏目内容。
• num / limit：调用条数。
• pagesize：分页每页数量。
• page：页码，常用 $page。
• order / sort：排序，例如 new、updatetime、hits、top、id_asc、id_desc、rand。
• return：循环变量名，默认 t。
• cache：标签缓存秒数，需模板标签缓存开启后生效。

基础写法：

{content model=article catid=$catid num=10 order=updatetime}
  <a href="{$t.url}">{$t.title}</a>
{empty}
  <p>暂无内容</p>
{/empty}
{/content}

分页写法：

{content model=article catid=$catid page=$page pagesize=20 order=id_desc}
  <h2><a href="{$t.url}">{$t.title}</a></h2>
{/content}
<div class="pages">{$pages}</div>

条件筛选写法：

{content model=article LIKE_title="关键词" num=10}
  <a href="{$t.url}">{$t.title}</a>
{/content}

支持的条件格式：

• 字段=值
• LIKE_字段=关键词
• IN_字段=1,2,3
• BETWEEN_字段=1,10
• 字段>10
• 字段>=10
• 字段<10
• 字段<=10
• 字段!=10

二、栏目列表：category

常用参数：

• module：内容模型代码。
• parent / pid：父栏目 ID，0 表示顶级栏目。
• num / limit：调用数量。
• order / sort：排序，例如 sort_asc,id_asc、id_desc、rand。
• return：循环变量名，默认 t。
• current：当前栏目 ID、slug 或 URL，用于给循环项生成 active。

{category module=article parent=0 num=20 order=sort_asc,id_asc current=$catid return=c}
  <a class="{$c.active}" href="{$c.url}">{$c.name}</a>
{empty}
  <p>暂无栏目</p>
{/empty}
{/category}

三、搜索列表：search

常用参数：

• module：内容模型代码。
• catid / category_id：栏目 ID。
• category：栏目 slug。
• keyword：搜索关键词。
• fields：搜索字段，多个字段逗号分隔。
• page：页码。
• pagesize / num：每页数量。
• order / sort：排序，例如 new、hits、updatetime。
• return：循环变量名，默认 rs。

{search module=article keyword=$keyword page=$page pagesize=20 order=new return=rs}
  <h2><a href="{$rs.url}">{$rs.title}</a></h2>
  <p>{$rs.description}</p>
{empty}
  <p>没有找到相关内容</p>
{/empty}
{/search}
<div class="pages">{$pages_rs}</div>

搜索地址和排序链接：

<a href="{search_url keyword=$keyword module=article}">搜索</a>
{sort_link value=new text="最新" class=sort-item}
{sort_link value=hits text="热门" class=sort-item}

四、URL 地址标签

前端主题使用一套 URL 标签体系，但按用途提供清晰标签名。这样模板里一眼能看出链接类型，也不会变成后台一套、会员一套、插件一套。

栏目、单页和内容地址：

<a href="{category_url slug=news}">新闻栏目</a>
<a href="{page_url slug=contact}">联系我们</a>
<a href="{content_url slug=hello-world}">内容详情</a>

{content model=article num=10}
  <a href="{$t.url}">{$t.title}</a>
{/content}

需要在通用片段里显式生成时，可以传入当前循环项：

{content model=article num=10}
  <a href="{content_url item=$t}">{$t.title}</a>
{/content}

会员、模块和插件前台地址：

<a href="{member_url path=login}">会员登录</a>
<a href="{member_url path=orders type=sold}">我的订单</a>
<a href="{member_url path=orders id=$order.order_no}">订单详情</a>
<a href="{module_url code=order path=query}">游客查单</a>
<a href="{plugin_url code=qq_login scope=member path=qq-login}">QQ 登录</a>

说明：

• {category_url} 默认生成 /category/{slug或id}。
• {page_url} 用于单页栏目，传入 slug 时生成 /{slug}。
• {content_url} 用于内容详情地址，{article_url} 只作为兼容别名保留。
• {member_url} 默认以 /member 为前缀。
• {module_url} 用于完整业务模块页面，例如 order 模块生成 /order/...。
• {plugin_url} 用于增强型插件页面，例如 qq_login 写 scope=member 时走 /member/...。
• id、key、no、order_no、recharge_no、withdraw_no、field 会追加为路径段；其他参数会作为 query string 输出。
• {url to=...} 作为兼容写法保留，但新模板优先使用上面这些更直观的专用 URL 标签。

媒体 URL 推荐使用函数式写法：

{if $t.thumb}
  <img src="{thumb_url($t.thumb, 200, 200)}" alt="{$t.title}">
  <a href="{file_url($t.thumb)}">原图</a>
{else}
  <span>没有缩略图</span>
{/if}

说明：

• {thumb_url($t.thumb, 200, 200)} 返回内容缩略图 URL。
• {image_url($image, 200, 200)} 返回普通图片字段缩略图 URL。
• {file_url($value)} 返回原图或附件公开 URL。
• 第 4 个参数可传 "crop"，例如 {thumb_url($t.thumb, 200, 200, "crop")}。
• 旧的属性式 {thumb_url url=$thumb width=200 height=200} 仍保留兼容。

五、表数据：table

{table} 只允许读取系统白名单里的表，当前白名单见 config/tanzcms_templates.php。

{table name=content_categories LIKE_name="新闻" num=10 order=id_desc return=row}
  <a href="{$row.slug}">{$row.name}</a>
{empty}
  <p>暂无数据</p>
{/empty}
{/table}

六、字段选项：field_options

用于输出单选、多选、联动菜单等字段的可选项。

{field_options module=article field=status current=$status return=o}
  <option value="{$o.value}" class="{$o.active}">{$o.label}</option>
{empty}
  <option value="">暂无选项</option>
{/empty}
{/field_options}

筛选链接的默认模式是“单字段单选替换，跨字段保留组合”。例如购买类型、引擎类型、版本类型三行筛选时，点击其中一行只替换本字段，其它字段参数必须继续传入链接，形成任意组合筛选。

  <a class="filter-btn {$o.active}" href="{$o.url}">{$o.label}</a>
{/field_options}

同字段多选是独立能力，必须显式声明 mode=multiple 或 multiple=1。多选模式用于同一个字段内追加/移除多个值，并且同样要保留其它筛选字段；普通主题不能把“跨字段组合”误写成同字段多选。

七、字段输出

详情页：

{$fields.price.text}
{image_img url=$thumb width=300 height=200 alt=$title}
{file_link url=$file text="下载附件"}

列表循环内：

{content model=article num=10}
  {$t.fields.price.text}
{/content}

八、注意事项

• 数据标签内部可以使用 {if}、{loop}、图片/附件/资源路径标签。
• return 用于避免多个标签循环变量互相覆盖。
• 分页变量会生成通用变量 {$pages}，也会按 return 生成 {$pages_变量名}。
• 条件筛选字段必须是系统允许的字段或当前模型已定义字段。
• 插件新增标签应通过插件服务提供者注册，不写进核心控制器。

九、业务标签

这些标签属于前台模板通用能力，不绑定某个主题，也不替代模块或插件自己的业务标签。

面包屑：breadcrumb/position

{breadcrumb article=1 return=nav}
  <a class="{$nav.active}" href="{$nav.url}">{$nav.name}</a>
{empty}
  <a href="/">首页</a>
{/empty}
{/breadcrumb}

常用参数：

• catid / category_id：指定栏目，不写时优先取当前栏目或当前内容所属栏目。
• article=1：详情页面包屑包含当前内容标题。
• home=0：不输出首页节点。
• return：循环变量名，默认 nav。

上一篇/下一篇：prev_next/content_nav

{prev_next return=nav}
  {if $nav.has_prev}<a href="{$nav.prev.url}">上一篇：{$nav.prev.title}</a>{/if}
  {if $nav.has_next}<a href="{$nav.next.url}">下一篇：{$nav.next.title}</a>{/if}
{empty}
  <p>没有上一篇或下一篇</p>
{/empty}
{/prev_next}

默认按当前内容的发布时间和 ID 查找，并限制在同栏目；需要跨栏目时可写 same_category=0。

相关文章：related

{related module=article num=6 order=new return=t}
  <a href="{$t.url}">{$t.title}</a>
{empty}
  <p>暂无相关文章</p>
{/empty}
{/related}

默认取当前内容同栏目的内容，并自动排除当前内容。支持 catid、category、module、num、order、return 等常见内容列表参数。

会员状态：member_status

{member_status return=m}
  <a href="{$m.center_url}">{$m.nickname}</a>
  <a href="{$m.orders_url}">订单</a>
{empty}
  <a href="{$m.login_url}">登录</a>
  <a href="{$m.register_url}">注册</a>
{/empty}
{/member_status}

member_status 只负责判断会员登录状态和输出会员中心常用地址；订单购买使用订单模块提供的 {member_order} / {order_buy}。

十、插件标签生成声明

启用插件可以在自己的 plugin.json 中声明 template_tags，标签生成器会自动读取并归到“插件标签”分组。插件禁用后，对应生成项自动隐藏。

{
  "template_tags": [
    {
      "value": "order_button",
      "label": "订单购买按钮",
      "snippet": "{member_order item={{item}} return={{return}}}...{/member_order}",
      "defaults": {
        "item": "$article",
        "return": "order"
      }
    }
  ]
}

这只是生成器 schema，不负责注册运行时标签；真正的模板标签仍由插件 ServiceProvider 注册。