核心模板标签手册

从一段模板到最终页面，按例子逐步看懂。

1. 先分清静态、动态与复用标记

标签写在 HTML 模板中，由引擎把它替换成内容。先在后台建好数据分组，再把模板放到对应站点的模板目录。下面每个例子都列出数据条件、实际标签和生成结果。

关闭页面缓存时，s 与 d 数据标签都会重新处理；s 本身不承诺永久固定。修改模板或数据后，若启用了缓存，先清除对应缓存再验证。

示例中的随机结果只展示一次可能抽取情况。需要重现某个确定结果时，在测试分组只放示例这一条数据。分组名使用字母、数字和下划线，大小写与实际目录一致。语法总览中的中文为参数说明，请替换成实际名称；完整例子可以直接复制到已准备好对应数据的测试模板。

{s:rand:alpha:12}|{d:rand:alpha:12}|{s:json:example:title:1}|{d:json:example:content:1}

FjanwYiMPkHV|dnxZVGTKGvOG|示例标题一|这是第一条示例内容

FjanwYiMPkHV|wHXQPWIaRodm|示例标题一|这是第三条示例内容

2. 文本：同一标题重复使用

交付包已有 keyword 分组，对应 sites/default/data/text/keyword.txt，内容如下：

关键词一
关键词二
关键词三

<title>{s:text:keyword:1}</title>
<h1>{s:text:keyword:1}</h1>

<title>关键词二</title>
<h1>关键词二</h1>

两处允许各自抽取时使用：

<li>{d:text:keyword:random}</li>
<li>{d:text:keyword:random}</li>

<li>关键词三</li>
<li>关键词一</li>

{s:text:分组名}
{s:text:分组名:复用标记}
{d:text:分组名:random}

{s:text:keyword}|{s:text:keyword:1}|{d:text:keyword:1}|{s:text:keyword:2}|{d:text:keyword:2}|{s:text:keyword:random}|{s:text:keyword:random}

关键词二|关键词二|关键词二|关键词一|关键词一|关键词一|关键词二

3. JSON：标题与正文必须配对

在测试站点的「JSON 数据」创建 news 分组，添加一条记录，例如 news/hello.json：

{
  "title": "姐夫工具箱",
  "summary": "整理文本，保存笔记。",
  "author": {"name": "JFT3am"}
}

<article>
  <h1>{s:json:news:title:1}</h1>
  <p>{s:json:news:summary:1}</p>
  <small>{s:json:news:author.name:1}</small>
</article>

<article>
  <h1>姐夫工具箱</h1>
  <p>整理文本，保存笔记。</p>
  <small>JFT3am</small>
</article>

交付包已有 example 分组，字段为 title、content，可直接使用 {s:json:example:title:1} 和 {s:json:example:content:1}。

不要把标题和正文分别写成 :random 再期待配对。开启页面缓存时也不要把 s 标题与 d 正文混用，命中缓存后两者可能来自不同记录。也不要用 :1 指定名为 1.json 的文件，它不是文件名选择器。

{s:json:分组名:字段路径:复用标记}
{d:json:分组名:字段路径:random}

{s:json:example:title:1}|{s:json:example:content:1}|{d:json:example:title:1}|{s:json:example:title:2}|{s:json:example:content:2}

示例标题三|这是第三条示例内容|示例标题三|示例标题三|这是第三条示例内容

4. 文件：名称和内容一起取

在「文件数据」创建 articles 分组，添加 hello.txt，文件内容为：

这是姐夫的第一篇笔记。

<article>
  <h2>{s:file:articles:name:1}</h2>
  <p>{s:file:articles:content:1}</p>
</article>

<article>
  <h2>hello</h2>
  <p>这是姐夫的第一篇笔记。</p>
</article>

省略后缀使用默认标记 1；:random 每处独立选文件。交付包已有 example 分组。文件内容按原文输出，允许包含模板标签，但不要写回自身文件标签造成循环嵌套。

5. 随机字符：先选对字符集

交付包内的字符集包括 num、alpha、lower、upper、hex 和 mix。字符取值由对应文件内容决定。

{s:rand:字符集名}
{s:rand:字符集名:长度}
{d:rand:字符集名:最小长度:最大长度}

<span data-code="{d:rand:num:6}">编号样式</span>

<span data-code="381152">编号样式</span>

例如 {s:rand:alpha:8} 输出 8 个字符，{d:rand:lower:6:12} 输出 6–12 个字符。这里的数字是长度，与 text / json / file 的复用标记不同。省略长度默认生成 5 个字符。同一个 rand 标签每处独立生成，不像文本标签那样按数字后缀复用；开启缓存后 s 结果随页面缓存保留。

{s:rand:num}|{s:rand:alpha:8}|{s:rand:alpha:8}|{d:rand:alpha:8}|{s:rand:num:2:4}|{s:rand:num:4:2}

44848|LkUZYLHC|CEnuohCt|TVMtQZSm|88|268

6. 时间：给定时间看输出

客户程序时区为 Asia/Shanghai。假设本次处理时间是 2026-09-20 10:15:30：

<time>{d:time:year}-{d:time:month}-{d:time:day}</time>

<time>2026-09-20</time>

实时更新时间用 d；页面生成时间用 s，并配合页面缓存。同次处理的 s:time:past 会复用，d:time:past 每处重新抽取；random_time 每处独立生成。

7. 站点：访问地址与生成内容

假设当前请求为 https://www.example.com/news/a.html：

<link rel="canonical" href="{d:site:url}">
<a href="{d:site:base}/about.html">关于我们</a>
<span>{d:site:host}</span>

<link rel="canonical" href="https://www.example.com/news/a.html">
<a href="https://www.example.com/about.html">关于我们</a>
<span>www.example.com</span>

涉及访客 IP 等每次请求不同的内容，应使用 d，避免写入共享页面缓存。反向代理环境需正确传递可信的协议和地址信息。

8. 循环：重复三条内容

<ul>
{loop row="3"}<li>第 {i} 条</li>{/loop}
</ul>

<ul>
<li>第 1 条</li><li>第 2 条</li><li>第 3 条</li>
</ul>

{i} 从 1 开始，row 使用单引号或双引号。循环是复制模板片段，不是按顺序遍历数据库。

循环内写 {s:json:news:title:{i}} 会在展开后得到不同复用标记；仍然随机取记录，不保证去重。需要标题与正文配对时，两者都使用同一个 {i}。

{loop row="3"}[{i}:{s:json:example:title:{i}}|{s:json:example:content:{i}}]{/loop}

[1:示例标题一|这是第一条示例内容][2:示例标题一|这是第一条示例内容][3:示例标题二|这是第二条示例内容]

9. 截取：生成纯文本摘要

<p>{cut count="4"}<b>姐夫</b> 工具箱{/cut}</p>

<p>姐夫工具</p>

先去掉 HTML 标签和空白（包括全角空格），再按 UTF-8 字符数量截取。适合摘要；不会自动添加省略号，也不是 HTML 属性值的安全转义。

10. 编码：源码与浏览器显示分开看

{encode dec}姐夫 JFT3am{/encode}

姐夫 JFT3am

浏览器看到：姐夫 JFT3am

默认随机选十进制或十六进制实体；dec 指定十进制，hex 指定十六进制。非 ASCII 字符被转换，英文、数字及 HTML 符号不变。

这是文本实体编码，不是 HTML 安全过滤。不要把不可信用户输入直接插入模板，尤其是属性和脚本位置。

11. 替换规则：先放片段，再处理标签

在站点的「高优先级替换」中，将占位文字 __HEADER__ 设为：

<header><strong>姐夫</strong></header>

__HEADER__
<main>正文</main>

<header><strong>姐夫</strong></header>
<main>正文</main>

高优先级替换在循环前执行，适合插入带循环的整段模板；「内容替换」位于后续数据阶段。替换值可继续包含标签，但不要递归引用自身占位符。

12. 一张配对内容卡片

沿用前面的 news 分组，本次记录包含 title 与 summary：

<article>
  <h2>{s:json:news:title:1}</h2>
  <p>{cut count="4"}{s:json:news:summary:1}{/cut}</p>
  <a href="/notes.html">阅读全文</a>
</article>

<article>
  <h2>姐夫工具箱</h2>
  <p>整理文本</p>
  <a href="/notes.html">阅读全文</a>
</article>

先取同一记录，再做截取。不要分别随机抽标题和摘要，否则读者看到的内容可能对不上。

13. 对不上示例时先查这些

1. 先检查实际数据分组：交付包是 keyword、example、alpha / num 等，不会自动存在教程中的 news、articles。
2. 核对字段：example 默认字段为 title、content，news 示例里的 summary、author.name 需要自行创建。
3. 有输出但不是第一条：数字后缀是复用标记，正常情况下仍随机选择。
4. 标题与正文不一致：检查是否同一分组、同一模式、同一复用标记。
5. 修改无变化：核对站点、模板类型和页面缓存。
6. 标签原样显示或空输出：核对拼写、文件内容与闭合标签；不同标签的缺失数据行为不同。
7. 复制示例到测试站点先验证单条数据，再增加数据量和组合。