xiis模板标签系统的三类标签与语法机制

xiis 模板标签系统通过全局标签、循环标签与字段标签三类标签，把站点配置、内容列表与数据字段渲染为最终页面。模板作者掌握双引号参数、成对闭合与字段前缀三条约定，即可覆盖从首页到详情页的全部动态渲染需求。

三类标签的分工边界

三类标签解决三个不同问题：全局标签输出单个值，循环标签重复输出一组数据，字段标签在循环内部取出当前行字段。识别方式很直接——没有闭标签且不带方括号的单值替换是全局标签，成对出现的是循环标签，方括号包裹的是字段标签。

全局标签输出单个值

全局标签用于站点信息与页面上下文，例如 {xiis:网站标题} 输出站点名称，{xiis:当前位置} 生成面包屑导航，{xiis:内容总数} 输出已发布内容数量。站点信息类标签的数据来自站点配置表，统计类标签按站点隔离统计，URL 类标签则由链接配置驱动。

循环标签重复输出列表

循环标签以成对形式包裹模板片段，例如 {xiis:内容列表 数量="10" 栏目="1"} 循环输出文章卡片，中间可以放任意 HTML 与字段标签，结尾必须写闭标签。循环标签的参数支持中英文双语，数量、排序、排列方式等参数都有对应的英文别名。

字段标签在循环内取值

字段标签只能出现在匹配的循环标签内部：内容列表内使用 [内容:标题]，栏目列表内使用 [栏目:名称]。字段标签支持格式参数与三元条件两种扩展写法，[内容:发布时间 Y-m-d] 按指定格式输出时间，[页面分类:激活?active:] 在激活时返回 active、未激活时返回空字符串。

语法约定与中英双语写法

参数值必须使用双引号包裹，这是解析层的第一条硬约定；标签名与参数名可以中英文自由混用，{xiis:内容列表 num="10" 栏目="1"} 是合法写法。标签名本身也有英文别名，例如内容列表可写作 {xiis:list}、导航列表可写作 {xiis:nav}，团队可以按统一风格选用其中一种。

标签语法中还包含一批并不显眼但影响解析结果的细节。中英文混合参数名（如 父ID、分类id）受解析层专门支持，参数名不区分大小写；字段标签的时间格式遵循字段级优先于列表级的覆盖顺序；三元条件可以只写真值与冒号，假值省略时输出空字符串。这些约定在排查标签不输出数据类问题时通常是第一检查项。

三层渲染管道与注册表机制

模板标签系统的渲染分三层完成：先由 Go 的 html/template 引擎处理模板变量与 XSS 防护，再由标签解析层处理 {xiis:xxx} 自定义标签，最后把整页输出交给 HTML 输出缓存并预压缩。三层各管一段，标签解析层不介入模板引擎的安全职责。

标签通过注册表模式管理，全局标签与循环标签各自维护一张注册表，新增标签只需增加一行注册项，无需修改核心处理函数。这种结构让标签数量增长时核心代码保持稳定，也让自定义标签与内置标签在调用方式上完全一致。

安全机制与递归限制

标签系统默认按严格白名单运行：排序字段必须命中白名单，防止拼接 SQL；栏目点号标签的字段名必须命中映射表，未命中直接返回空字符串；多站点场景下所有查询强制携带站点条件。递归深度同样有硬限制——全局标签最多 10 层、循环标签 3 层，避免恶意模板引发无限递归。

字段标签同样采用白名单模式运行，映射表之外的字段名不会泄露内部数据。对于内容详情点号标签这类支持动态回退的场景，回退范围也仅限该内容自身的 meta 键，不会越权读取其他表或站点的数据。

三类标签速览对照

掌握三类标签的分工后，模板开发的核心工作就变成选对标签、写对参数、放对位置。xiis 模板标签系统用一层轻量的解析管道，把站点配置、列表数据与字段渲染统一在模板里表达，模板不依赖控制器透传数据，站点配置变化后模板依然可用。