标签使用
biaoqian
TSCMS 模板标签使用教程
一、标签规则
1.1 标签结构
所有标签遵循统一的 {ts}{loop} ... {/loop}{/ts} 结构：
{ts module="content" action="lists" catid="1" num="10" return="data"}
{loop data="$data" return="r"}
{$r.title}
{/loop}
{/ts}执行过程：
{ts ...}调用对应模块和方法，将结果赋值给 return 指定的变量（默认$data）{loop data="$data" return="r"}循环遍历该数组，每次循环将当前元素赋值给 return/id 指定的变量（默认$item）{/ts}结束标签
💡 return 参数说明：{ts} 的 return 控制"数据来源变量名"；{loop} 的 return 控制"循环内单条数据变量名"。两者互不影响。
1.2 内容模块（module="content"，可省略）
// 写法一（推荐，省略 module，因为默认就是 content）
{ts action="lists" catid="1" num="10" return="data"}
{loop data="$data" return="r"}
{$r.title}
{/loop}
{/ts}
// 写法二（完整写法）
{ts module="content" action="lists" catid="1" num="10" return="data"}
{loop data="$data" return="r"}
{$r.title}
{/loop}
{/ts}1.3 非内容模块（必须指定 module）
{ts module="ad" action="lists" typeid="1" num="5" return="data"}
{loop data="$data" return="r"}
{$r.title}
{/loop}
{/ts}1.4 单条数据（不需要 loop）
当 {ts} 返回的是单条数据（关联数组）时，不需要 loop，直接使用变量即可：
{ts action="show" id="1" catid="1" return="vo"}
{$vo.title}
{$vo.content}
{/ts}1.5 ts 主标签全部参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| module | content | 模块名。content 可省略，其他模块必须指定 |
| action | - | 要执行的方法名（必填） |
| cache | 0 | 缓存秒数，0=不缓存 |
| return | data | 数据来源变量名（{loop} 用 data 参数引用此名） |
| page | 0 | 分页页码，设置后自动输出 $pages |
1.6 loop 循环标签全部参数
{loop data="$data" return="r" key="k" i="i" start="0" empty="暂无数据"}| 参数 | 默认值 | 说明 |
|---|---|---|
| data / name | - | 必填。要循环的数据变量，可以是数组也可以是逗号分隔的字符串 |
| return / id | item | 循环内单条数据的变量名（如 $r） |
| key | key | 循环键名（如 $k） |
| i | i | 索引变量（从 start 开始递增，如 $i） |
| start | 0 | 索引起始值 |
| split | , | 当 data 是字符串时，按此分隔符分割为数组 |
| empty | - | 空数组时显示的替代文字 |
1.7 完美范例（分页 + 索引）
{ts action="lists" catid="2" num="10" page="$page" return="data"}
{loop data="$data" return="r" key="k" i="i" start="1" empty="暂无数据"}
{$i}. {$r.title} {/loop}
{/ts}{$pages}💡 带 page 参数时，模板中自动获得 $pages 变量（分页 HTML）。
二、内容模块标签（module="content"，可省略）
对应文件：application/content/taglib/TagContent.php
2.1 栏目列表 — action="category"
// 顶级栏目列表
{ts action="category" pid="0" num="20" return="data"}
{loop data="$data" return="r"}
{$r.catname} {/loop}
{/ts}
// 指定单条栏目
{ts action="category" catid="3" return="cat"}
{$cat.catname} - {$cat.url}
{/ts}| 参数 | 默认值 | 说明 |
|---|---|---|
| pid | 0 | 父栏目ID，0=顶级 |
| catid | 0 | 指定栏目ID，传了则返回单条 |
| num | 20 | 最大条数 |
| order | listorder DESC, catid ASC | 排序 |
| where | - | 额外条件，如 `type`=1 |
可用字段：
$r.catid — 栏目ID
$r.catname — 栏目名称
$r.catdir — 栏目目录
$r.parentid — 父栏目ID
$r.arrparentid — 所有父栏目ID
$r.arrchildid — 所有子栏目ID
$r.child — 是否有子栏目
$r.type — 类型
$r.modelid — 模型ID
$r.image — 栏目图片
$r.url — 栏目URL
$r.setting — 配置
$r.description — 描述
$r.listorder — 排序
$r.status — 状态
2.2 内容列表 — action="lists"
{ts action="lists" catid="1" num="10" page="$page" return="data"}
{loop data="$data" return="r"}
{$r.title} {date('Y-m-d', $r.createtime)} 阅读：{$r.hits} {/loop}
{/ts}
{$pages}| 参数 | 默认值 | 说明 |
|---|---|---|
| catid | 0 | 栏目ID，包含子栏目 |
| modelid | 模型ID | 模型ID |
| num | 10 | 条数 |
| order | listorder DESC, id DESC | 排序 |
| field | a.* | 字段 |
| moreinfo | 0 | 是否联查副表 |
| page | 0 | 分页页码 |
| where | - | 额外SQL条件 |
| ext | - | 指定副表字段，如 content,price |
| flag | - | 推荐位筛选 |
| showsql | 0 | 1=显示SQL语句 |
循环内可用字段：
$r.id — 文章ID
$r.title — 标题
$r.catid — 栏目ID
$r.url — URL
$r.keywords — 关键词
$r.description — 摘要
$r.thumb — 缩略图
$r.hits — 点击量
$r.createtime — 创建时间
$r.updatetime — 更新时间
$r.status — 状态
$r.slug — URL别名
$r.username — 发布者
$r.listorder — 排序
$r.posids — 推荐位
$r.modelid — 模型ID
2.3 内容详情 — action="show"（单条，不用 loop）
{ts action="show" id="1" catid="1" return="vo"}
{$vo.title} {$vo.content} 发布时间：{date('Y-m-d', $vo.createtime)}{/ts}| 参数 | 必填 | 说明 |
|---|---|---|
| id | 是 | 文章ID |
| catid | 是 | 栏目ID |
返回单条数据，含主表和副表所有字段。
2.4 上一篇 — action="pre"（单条）
{ts action="pre" id="5" catid="1" tips="这是第一篇" return="vo"}
{$vo.title}{/ts}2.5 下一篇 — action="next"（单条）
{ts action="next" id="5" catid="1" tips="这是最后一篇" return="vo"}
{$vo.title}{/ts}| 参数 | 说明 |
|---|---|
| id | 当前文章ID |
| catid | 当前栏目ID |
| tips | 无结果时的提示，默认"没有了" |
2.6 文章标签列表 — action="tag"（获取某篇文章绑定的标签）
{ts action="tag" id="5" catid="1" return="data"}
{loop data="$data" return="r"}
{$r.tag} {/loop}
{/ts}| 参数 | 说明 |
|---|---|
| id | 文章ID（必填） |
| catid / modelid | 二选一，推导模型ID |
| field | 字段，默认 * |
2.7 标签列表 — action="taglist"
{ts action="taglist" num="20" page="$page" return="data"}
{loop data="$data" return="r"}
{$r.tag}（{$r.items}篇） {/loop}
{/ts}
{$pages}| 参数 | 默认值 | 说明 |
|---|---|---|
| num / pagesize | 20 | 每页条数 |
| page | 0 | 分页页码 |
2.8 标签内容列表 — action="tagcontent"
{ts action="tagcontent" tag="PHP" num="10" page="$page" return="data"}
{loop data="$data" return="r"}
{$r.title} {/loop}
{/ts}
{$pages}| 参数 | 说明 |
|---|---|
| tag | 标签名称（与tagid二选一） |
| tagid | 标签ID（与tag二选一） |
| num / pagesize | 每页条数，默认10 |
| page | 分页 |
| catid | 限定栏目 |
| modelid | 限定模型 |
2.9 相关文章 — action="relation"
{ts action="relation" keywords="$keywords" catid="$catid" id="$id" num="5" return="data"}
{loop data="$data" return="r"}
{$r.title} {/loop}
{/ts}| 参数 | 默认值 | 说明 |
|---|---|---|
| keywords | - | 关键词（必填），匹配 title 和 keywords 字段 |
| catid | 0 | 限定栏目 |
| modelid | 由catid推导 | 模型ID |
| id | 0 | 排除当前文章 |
| num | 10 | 返回数量 |
| field | * | 查询字段 |
| order | updatetime DESC, id DESC | 排序 |
| where | - | 额外条件 |
三、其他全局标签
3.1 GET标签 — ts:get
// 按表名查询
{ts:get table="member" order="userid DESC" num="10" return="data"}
{loop data="$data" return="r"}
用户名：{$r.username} - 邮箱：{$r.email}
{/loop}
{/ts:get}
// 按 SQL 查询
{ts:get sql="SELECT * FROM tc_member WHERE status=1" order="userid DESC" num="10" return="data"}
{loop data="$data" return="r"}
{$r.username}
{/loop}
{/ts:get}| 参数 | 说明 |
|---|---|
| table | 表名（不含前缀） |
| sql | 原生 SQL（与 table 二选一） |
| order | 排序 |
| num | 条数 |
| page | 分页 |
| cache | 缓存秒数 |
| return | 变量名，默认 item |
| where（仅table模式） | 额外条件 |
⚠ SQL 模式禁止 delete/insert/update/drop/alter 操作。
3.2 碎片标签 — ts:pos
// 简单文本碎片（自动输出）
{ts:pos name="footer_about"}{/ts:pos}
// 组图碎片（配合 loop 手动处理）
{ts:pos name="home_banners" return="block"}
{loop data="$block" return="r"}
{/loop}
{/ts:pos}| 参数 | 说明 |
|---|---|
| name | 碎片位置标识（必填） |
| return | 变量名，默认 block。设了则需自己用 loop 处理 |
3.3 模板引入 — ts:template
{ts:template file="content/header" /}等价于 {include file="content/header" /}。
四、其他模块
4.1 广告模块（module="ad"）
{ts module="ad" action="lists" typeid="1" num="5" return="data"}
{loop data="$data" return="r"}
{/loop}
{/ts}| 参数 | 默认值 | 说明 |
|---|---|---|
| typeid | 0 | 广告分类ID |
| num | 5 | 数量 |
| order | listorder DESC, adid DESC | 排序 |
| where | - | 额外条件 |
4.2、幻灯片模块（module="swiper"）
{ts module="swiper" action="lists" typeid="1" num="5" return="data"}
{loop data="$data" return="r"}
{/loop}
{/ts}| 参数 | 默认值 | 说明 |
|---|---|---|
| typeid | 0 | 分类ID |
| num | 5 | 数量 |
| order | listorder DESC, id DESC | 排序 |
可用字段：
$r.id — 幻灯片ID
$r.name — 名称
$r.image — 图片
$r.url — 链接
$r.typeid — 分类ID
$r.status — 状态
$r.description — 描述
$r.createtime — 创建时间
$r.listorder — 排序
幻灯片分类列表
{ts module="swiper" action="type" num="10" return="data"}
{loop data="$data" return="r"}
{$r.name} - {$r.typeid}
{/loop}
{/ts}幻灯片详情
{ts module="swiper" action="info" id="1" return="r"}
{$r.name} - {$r.image}
{/ts}4.3 友情链接模块（module="link"）
{ts module="link" action="lists" typeid="1" num="10" return="data"}
{loop data="$data" return="r"}
{$r.webname} {/loop}
{/ts}| 参数 | 默认值 | 说明 |
|---|---|---|
| typeid | 0 | 分类ID |
| num | 0（全部） | 数量 |
| order | listorder DESC, linkid DESC | 排序 |
| recommend | 0 | 1=仅推荐 |
可用字段：
$r.linkid — 链接ID
$r.webname — 网站名
$r.url — 网站URL
$r.logo — Logo图片
$r.typeid — 分类ID
$r.description — 描述
$r.recommend — 推荐
$r.passed — 审核
友情链接分类列表
{ts module="link" action="type" num="10" return="data"}
{loop data="$data" return="r"}
{$r.name} - {$r.typeid}
{/loop}
{/ts}4.4 表单模块（module="formguide"）
表单信息
{ts module="formguide" action="form" formid="5" return="info"}
表单名称：{$info.name}
提交地址：{$info.action}
{/ts}表单数据列表
{ts module="formguide" action="list" modelid="5" num="10" page="$page" return="data"}
{loop data="$data" return="r"}
{$r.id} - {$r.createtime}
{/loop}
{/ts}
{$pages}| 参数 | 默认值 | 说明 |
|---|---|---|
| modelid | 0 | 表单模型ID（必填） |
| num | 10 | 条数 |
| order | id DESC | 排序 |
| where | - | 条件 |
| field | * | 字段 |
| page | 0 | 分页 |
五、各页面可直接使用的模板变量
以下变量由控制器自动赋值，在对应模板中直接使用，无需通过标签获取。
5.1 首页（index.html）
| 变量 | 类型 | 说明 |
|---|---|---|
$SEO | array | SEO 信息数组：$SEO.title、$SEO.keyword、$SEO.description |
$page | int | 当前页码 |
5.2 列表页（list.html）
| 变量 | 类型 | 说明 |
|---|---|---|
$SEO | array | SEO 信息数组 |
$catid | int | 当前栏目ID |
$category | array | 当前栏目完整信息（含 catname、catdir、setting、parentid 等） |
$page | int | 当前页码 |
栏目字段列表（$category）：
$category.catid — 栏目ID
$category.catname — 栏目名称
$category.catdir — 栏目目录
$category.parentid — 父栏目ID
$category.type — 类型（0列表/1单页/2外链）
$category.modelid — 模型ID
$category.image — 栏目图片
$category.child — 是否有子栏目
$category.description — 栏目描述
$category.arrchildid — 子栏目ID串
$category.url — 栏目URL
$category.setting — 配置数组
5.3 内容详情页（show.html）
| 变量 | 类型 | 说明 |
|---|---|---|
$SEO | array | SEO 信息数组 |
$catid | int | 当前栏目ID |
$id | int | 当前文章ID |
$category | array | 当前栏目完整信息 |
$content | array | 当前文章数据（含主表和副表所有字段） |
$tag | array | 文章关联的标签列表 |
$page | int | 当前页码 |
文章字段列表（$content）：
$content.id — 文章ID
$content.title — 标题
$content.catid — 栏目ID
$content.url — 文章URL
$content.keywords — 关键词
$content.description — 摘要
$content.thumb — 缩略图
$content.hits — 点击量
$content.createtime — 创建时间
$content.updatetime — 更新时间
$content.status — 状态
$content.slug — URL别名
$content.username — 发布者
$content.listorder — 排序
$content.posids — 推荐位
$content.content — 正文（副表）
$content.modelid — 模型ID
$content.{自定义字段} — 模型自定义字段
注意：所有自定义变量都会生成一个加_的同名字段，例如color，会生成一个_color返回对应内容
💡 控制器会执行 $this->assign($content)，所以 $content 内的所有字段也会直接成为顶层变量，如 {$title}、{$content}、{$hits} 等，可直接使用。
5.4 单页面（page.html）
| 变量 | 类型 | 说明 |
|---|---|---|
$SEO | array | SEO 信息数组 |
$catid | int | 当前栏目ID |
$category | array | 当前栏目完整信息 |
$info | array | 单页面数据（含 title、content、hits 等） |
💡 page.html 同样会执行 $this->assign($pageInfo)，可直接用 {$title}、{$content}。
5.5 搜索页（search.html / search_result.html）
| 变量 | 说明 |
|---|---|
$SEO | SEO 信息数组 |
$keyword | 搜索关键词 |
$modelid | 搜索的模型ID |
$modellist | 可搜索的模型列表 |
$list | 搜索结果列表 |
$pages | 分页 HTML |
$count | 结果总数 |
$history | 搜索历史 |
5.6 标签页（tag.html / tag_list.html）
| 变量 | 说明 |
|---|---|
$SEO | SEO 信息数组 |
$tag | 当前标签名称 |
$page | 当前页码 |
5.7 所有页面通用变量
$sysinfo — 系统配置
$style — 模板风格
$site_url — 站点URL
__PUBLIC__ — 根目录
__STATIC__ — 静态资源
__CSS_PATH__ — CSS目录
__JS_PATH__ — JS目录
__IMG_PATH__ — 图片目录
__UPLOAD__ — 上传目录
六、完整模板示例
首页（index.html）
{$SEO.title} {include file="content/header" /}
{ts module="swiper" action="lists" typeid="1" num="5" return="data"}
{loop data="$data" return="r"}
{/loop}
{/ts}
{ts action="lists" catid="1" num="8" return="data"}
{loop data="$data" return="r"}
{$r.title} - {date('m-d', $r.createtime)} {/loop}
{/ts}
{ts module="link" action="lists" num="20" return="data"}
{loop data="$data" return="r"}
{$r.webname} {/loop}
{/ts}
{include file="content/footer" /}列表页（list.html）
位置：{catpos($catid)}
{$category.catname}
{ts action="category" pid="$catid" num="10" return="data"}
{loop data="$data" return="r"}
{$r.catname} {/loop}
{/ts}
{ts action="lists" catid="$catid" num="10" page="$page" return="data"}
{loop data="$data" return="r"}
{$r.title} {date('Y-m-d', $r.createtime)} 阅读：{$r.hits} {str_cut($r.description, 200)} {/loop}
{/ts}{$pages}详情页（show.html）
{$content.title} 栏目：{$category.catname} | 时间：{date('Y-m-d', $content.createtime)} | 点击：{$content.hits}{$content.content}标签：
{ts action="tag" id="$id" catid="$catid" return="data"}
{loop data="$data" return="r"}
{$r.tag} {/loop}
{/ts} 上一篇：{ts action="pre" id="$id" catid="$catid" return="vo"}{$vo.title}{/ts} 下一篇：{ts action="next" id="$id" catid="$catid" return="vo"}{$vo.title}{/ts}相关文章{ts action="relation" keywords="$content.keywords" catid="$catid" id="$id" num="5" return="data"}
{loop data="$data" return="r"}
{$r.title} {/loop}
{/ts}
$catid, 'id'=>$id])}" cdata_tag="script" _ue_custom_node_="true">单页面（page.html）
{$info.title}{$info.content} 
