模板标签开发进阶

模板标签用于把业务数据交给 .html 模板展示，不用于接管整页 HTML。

一、标签定位

模板标签应该做：

• 解析参数。
• 校验白名单。
• 查询数据。
• 组装结构化变量。
• 调用循环体渲染。
• 必要时返回低层小片段。

模板标签不应该做：

• 拼整页布局。
• 写死主题样式。
• 接收原始 SQL。
• 根据栏目 slug 特判页面。
• 输出未经清洗的用户 HTML。

二、处理器结构

class DemoTag implements TemplateTagHandlerContract
{
    public function names(): array
    {
        return ['demo'];
    }

    public function render(string $name, array $attributes, string $body, TemplateRenderContext $context): string
    {
        $return = preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', (string) ($attributes['return'] ?? 't'))
            ? (string) ($attributes['return'] ?? 't')
            : 't';
        $rows = $this->queryRows($attributes);

        return collect($rows)
            ->map(fn (array $row): string => $context->withData([$return => $row])->renderFragment($body))
            ->implode('');
    }
}

三、参数校验

常见参数要限制范围：

参数	建议
num / pagesize	限制最大值
order	白名单
catid / model	校验是否存在
return	限制变量名格式
cache	限制时间范围

四、结构化数据

推荐把 URL、标题、时间、状态、权限、缩略图等字段都作为变量返回，让主题决定 HTML：

{demo return=item}
  <a href="{$item.url}">{$item.title}</a>
{/demo}

五、缓存规则

标签可以按参数缓存查询结果，但必须考虑失效：

• 栏目变化。
• 内容发布、更新、删除。
• 插件设置变化。
• 会员菜单变化。
• 订单购买状态变化。

不要用旧缓存掩盖缺字段、缺表或插件未启用问题。

六、空数据

标签应支持 {empty} 分支：

{demo return=item}
  {$item.title}
{empty}
  暂无数据
{/empty}
{/demo}

七、安全输出

普通变量默认转义。只有确认安全的 HTML 才使用 {html ...}。标签返回用户提交内容时，应明确区分纯文本、富文本和已清洗 HTML。

八、文档要求

新增官方标签时应补充：

• 标签名。
• 参数表。
• 返回变量表。
• 最小示例。
• 列表页和详情页差异。
• 缓存和权限注意事项。