主题开发完整手册

主题负责前台和会员中心展示。业务逻辑、迁移、控制器和服务不放进主题。

一、主题目录

常见结构：

themes/default/
├─ index.html
├─ header.html
├─ footer.html
├─ list.html
├─ show.html
├─ page.html
├─ search.html
├─ member/
└─ modules/

模板文件名由后台栏目配置决定，不受固定白名单限制。

二、模板语法

主题模板使用 TanzCMS .html 语法：

{template "header.html"}
{if $category}
  <h1>{$category.name}</h1>
{/if}
{template "footer.html"}

不要在主题中使用 Blade 指令。

三、栏目模板

栏目模板优先读取后台配置：

页面	配置
列表页	list_template
详情页	show_template
单页	page_template

如果需要不同布局，应新增模板并在后台栏目中选择，而不是在 PHP 控制器里按 slug 特判。

四、资源路径

普通主题资源优先使用：

<link rel="stylesheet" href="{THEME_PATH}css/style.css">
<script src="{THEME_PATH}js/app.js"></script>

需要自动版本或特殊资源时再使用资源标签。

五、模块模板覆盖

模块模板可以放在：

themes/{theme}/modules/{code}/

当前主题没有对应模板时，可以回退到默认主题模块模板。主题只覆盖展示，不复制模块控制器、服务和迁移。

六、插件模板覆盖

插件展示模板可以放在：

themes/{theme}/plugins/{code}/

插件禁用后，主题不能依赖插件标签才能正常渲染核心页面。

七、会员中心

会员中心模板放在：

themes/{theme}/member/

会员页面包含登录态、CSRF、个人资料和插件菜单，不应作为普通游客页面整页缓存。

八、禁止事项

• 不在主题里写 PHP 业务逻辑。
• 不把后台管理接口写入主题 JS 后绕过权限。
• 不写死 /themes/default/ 作为资源路径。
• 不为单个栏目修改核心控制器。
• 不把插件源码复制进主题目录。