ThinkTemplate 模板中可用函数大全 | 使用方法

求元工坊CMS 基于 ThinkPHP6 + ThinkTemplate 模板引擎，模板中可以直接调用 PHP 原生函数及 ThinkTemplate 内置函数，用于对字段值进行格式化、截取、转换等处理。

一、函数调用通用语法

1.1 管道符调用格式

{字段|函数名=参数1,参数2,...,参数n}

1.2 占位符规则

<!-- 字段在第一个参数位置：可省略 ### -->
{$item['title']|substr=0,20}

<!-- 字段在第一个参数位置：也可显式写 ### -->
{$item['title']|substr=###,0,20}

<!-- 字段在非第一个参数位置：必须显式写 ### -->
{$item['created_at']|date='Y-m-d',###}

注解：字段值所在参数位置用 ### 占位。如果在第一个参数位置，### 可省略；其他位置不能省略。

1.3 多函数链式调用

<!-- 先截取再转大写 -->
{$item['title']|substr=0,20|upper}

<!-- 先格式化时间再处理空值 -->
{$item['created_at']|date='Y-m-d',###|default='未知'}

二、字符串处理函数

2.1 substr 函数 | 截取指定长度的字符串

substr(str, start, length)

参数说明：

1. str 表示要截取的字符串。必需；
2. start 表示起始位置（0为第一个字符）。必需；
3. length 表示截取长度。必需；

例子：

{volist name="list" id="item"}
   <a href="{$item['url']}">{$item['title']|substr=0,20}</a>
{/volist}

注解：获取文档列表，标题只显示前20个字符。

2.2 strtoupper / strtolower 函数 | 大小写转换

strtoupper(str)  // 转大写
strtolower(str)  // 转小写

例子：

{$item['title']|strtoupper}
{$item['category']|strtolower}

2.3 trim 函数 | 去除首尾空白字符

trim(str)

例子：

{$item['summary']|trim}

2.4 htmlspecialchars 函数 | HTML 实体编码

htmlspecialchars(str)

例子：

<input type="text" value="{$item['title']|htmlspecialchars}">

注解：将 HTML 特殊字符（如 <、>、& 等）转为实体编码，防止 XSS 攻击。

2.5 md5 函数 | MD5 加密

md5(str)

例子：

{$item['email']|md5}

三、日期时间函数

3.1 date 函数 | 格式化日期时间

date(format, timestamp)

参数说明：

1. format 表示返回的日期格式。必需；
2. timestamp 表示要转换的时间戳。必需；

常用格式字符：

例子：

{volist name="list" id="item"}
   <li>
     <a href="{$item['url']}">{$item['title']}</a>
     <span>{$item['created_at']|date='Y-m-d H:i:s',###}</span>
   </li>
{/volist}

注解：将时间戳字段格式化为 "2024-04-01 10:22:50" 的样式显示。

四、ThinkTemplate 内置函数

4.1 default 函数 | 默认值

default(value)

例子：

{$item['author']|default='匿名'}
{$item['cover']|default='/static/home/img/default.png'}

注解：当字段值为空时，显示指定的默认值。常用于作者、封面图等可选字段。

4.2 raw 函数 | 原始输出（不转义）

raw(str)

例子：

{$item['content']|raw}

注解：输出 HTML 富文本内容，不进行转义。注意：仅用于可信数据源，防止 XSS。

4.3 upper / lower 函数 | 大小写转换（简写）

upper(str)  // 同 strtoupper
lower(str)  // 同 strtolower

例子：

{$item['title']|upper}
{$item['title']|lower}

五、综合使用示例

5.1 文档列表（标题截取 + 日期格式化 + 默认值）

{volist name="list" id="item"}
   <div class="doc-item">
     <h3><a href="{$item['url']}">{$item['title']|substr=0,30}</a></h3>
     <p>{$item['summary']|substr=0,100|default='暂无摘要'}</p>
     <div class="meta">
       <span>{$item['author']|default='匿名'}</span>
       <span>{$item['created_at']|date='Y-m-d',###}</span>
       <span>{$item['views']} 次阅读</span>
     </div>
   </div>
{/volist}

注解：标题截取30字符，摘要截取100字符并设默认值，作者设默认值为"匿名"，日期格式化为 "Y-m-d"。

5.2 图片输出（带尺寸处理）

<img src="{$item['cover']|default='/static/home/img/default.png'}" 
     alt="{$item['title']|htmlspecialchars}">

注解：封面图为空时显示默认图，标题转义后作为 alt 属性。

六、注意事项

1. 函数仅针对字段值：模板函数只作用于 volist 或控制器传递的字段，不能用于常量或表达式。
2. 数组下标语法：函数调用时必须使用数组下标 {$item['field']|func}，不支持点语法 {$item.field|func}。
3. 参数分隔符：参数之间用逗号 , 分隔，字符串参数需用引号包裹。
4. ### 占位规则：字段在第一个参数时可省略 ###，其他位置必须显式写 ###。
5. 链式调用顺序：函数按从左到右顺序执行，如 |substr=0,20|upper 先截取再转大写。
6. 安全性：输出用户提交的内容时，建议先用 htmlspecialchars 过滤；富文本内容使用 raw 时需确保来源可信。

本文档适用于求元工坊CMS v1.0 及以上版本。更多模板语法请参考 ThinkTemplate SSR 数据渲染指南、模板算术运算符使用指南、模板条件判断语句（if 标签） 和 循环调用多级子栏目。