主题开发指南

主题目录结构

每个主题独立存放于 themes/{主题ID}/：

themes/mytheme/
├── theme.json          # 主题声明与后台设置项
├── screenshot.png      # 后台展示的预览图
├── templates/          # 模板文件（.html）
│   ├── common/         # 公共片段（header / footer / sidebar）
│   ├── index.html      # 首页（文章列表）
│   ├── article.html    # 文章详情
│   ├── category.html   # 分类页
│   ├── tag.html        # 标签页
│   ├── tags.html       # 标签云
│   ├── page.html       # 独立页面
│   ├── search.html     # 搜索结果
│   ├── archives.html   # 归档页
│   ├── 404.html        # 未找到页面
│   ├── login.html / register.html        # 登录注册
│   └── profile_*.html / user_profile.html  # 用户中心系列
└── assets/             # 主题的 css / js / 图片

theme.json

{
    "id": "mytheme",
    "name": "我的主题",
    "version": "1.0.0",
    "author": "作者名",
    "description": "主题简介",
    "settings": [
        {
            "key": "show_back_to_top",
            "label": "显示回到顶部按钮",
            "type": "checkbox",
            "default": "1",
            "description": "是否在页面显示回到顶部按钮"
        }
    ]
}

settings 中声明的每一项都会出现在后台主题设置页，模板里通过 {site.设置键} 读取。id 必须与目录名一致。

模板中的数据

控制器渲染模板时注入的常用数据（以文章页为例）：

• 顶层变量：、 等；
• 详情对象：（标题、内容、分类、作者、时间等字段）；
• 列表数据：以数组传入，用 遍历，行内用 取值；
• 分页：。

模板语法完整参考见模板标签语法大全。

公共片段与继承

common/ 下放头部、底部、侧边栏等片段，通过 {include file="common/header"} 引入。布局高度重复时可用模板继承抽父布局。

开发流程建议

1. 复制 themes/default 改名（同步修改 theme.json 的 id），在其基础上调整；
2. 后台「主题管理」扫描并切换到新主题；
3. 修改模板后前台刷新即可看到效果（模板自动重新编译）；样式不生效时清理缓存；
4. 使用 在主题中预留插件挂载点。

打包与分发

完成后压缩整个主题目录（保持顶层目录名与主题 ID 一致），即可上传到官网应用市场或分享安装。