主题目录结构 Theme Structure

一个前台主题就是站点根目录下的 theme/<主题名>/ 目录，前台模板引擎的模板根目录即该目录。当前生效主题由站点配置 site.site_theme 决定，在后台「模板」页面启用 / 切换。

一、目录布局

theme/<主题名>/
├── css/                     样式（style.css 必需：主题元数据 + 全站样式）
├── js/                      脚本
├── images/                  图片（screenshot.png 为主题列表预览图）
├── inc/                     公共片段与主题扩展脚本
│   ├── header.tpl           公共头
│   ├── footer.tpl           公共尾
│   ├── code_head.tpl        head 结束前插入点（全站自定义代码）
│   ├── code_footer.tpl      body 结束前插入点
│   ├── ..from_theme.php     主题数据装配脚本（可选）
│   └── ..setting.php        主题尺寸声明（可选）
├── index.dwt                首页
├── <模块名>.dwt             模块详情 / 单页
├── <模块名>_category.dwt    栏目模块分类列表页
├── <模块名>_user.dwt        会员中心子页
├── <模块名>_work.dwt        工作人员端子页
├── dou_msg.dwt              系统提示页
├── search.dwt               搜索结果页
└── page.dwt / landing.dwt   其它内置页面

二、模板文件与页面命名约定

模板文件由前台控制器通过 view('xxx.dwt', $data) 指定，主题侧只要提供同名文件即可：

补充约定：

• 模板文件扩展名白名单：.tpl / .htm / .html / .dwt；{include} 的资源名禁止包含 .. 或绝对路径；
• 公共片段放 inc/*.tpl，用 {include file="inc/header.tpl"} 引入；
• 静态资源写相对路径（css/style.css、images/logo.png），前台预过滤器会烘焙为绝对主题路径；
• 可用 HTML 注释包裹标签（写为 HTML 注释形式的 {if ...}），渲染时注释会被还原，便于模板直接用浏览器预览；
• 链接推荐用 {url link='模块.动作'} 标准写法。

三、主题元数据与预览图

后台主题列表会扫描 theme/ 下所有子目录，读取其 css/style.css（兼容旧位置根目录 style.css）头部注释作为主题信息：

/*
Theme Name: 我的主题
Theme URI: https://example.com/
Description: 主题描述
Version: 1.0
Author: 作者
Author URI: https://example.com/
*/

解析规则：含 /* 的行跳过，遇到 */ 行结束；中间每行按 键: 值 解析，键会转成小写、空格转下划线（Theme Name → theme_name）。预览图固定取 images/screenshot.png。

四、启用主题的三件事

在后台启用 / 切换主题时，系统会：

1. 主题目录内缺失的文件，从 theme/default 自动补齐（已存在的文件不覆盖）；
2. 商业主题目录名遵循 m001 ~ m999（正则 ^m\d{3}$）：未授权且为正式域名时自动回退到 default；
3. 清理模板编译缓存。

五、制作主题的推荐流程

1. 复制 theme/default 作为起点；
2. 目录命名：普通主题任意合法目录名，商业主题用 m001 ~ m999；
3. 编写 css/style.css 元数据注释，放入 images/screenshot.png 预览图；
4. 按命名约定编写 *.dwt 模板与 inc/*.tpl 公共片段；
5. 需要「跟随路由」的数据装配 → 增加 inc/..from_theme.php；
6. 需要后台图片尺寸提示 → 增加 inc/..setting.php；
7. 需要自定义文案 → 在对应语言包目录增加 *.lang.php；
8. 后台「模板」页面启用主题，逐页回归验证。