# 主题开发指南

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [AGENTS.MD](file://AGENTS.MD)
- [composer.json](file://composer.json)
- [public/themes/default/manifest.json](file://public/themes/default/manifest.json)
- [public/themes/admin_default/manifest.json](file://public/themes/admin_default/manifest.json)
- [public/themes/default/public/base.html](file://public/themes/default/public/base.html)
- [public/themes/default/public/head.html](file://public/themes/default/public/head.html)
- [public/themes/default/public/scripts.html](file://public/themes/default/public/scripts.html)
- [public/themes/default/public/config.json](file://public/themes/default/public/config.json)
- [public/themes/admin_default/admin/theme/index.html](file://public/themes/admin_default/admin/theme/index.html)
- [public/themes/admin_default/admin/theme/install.html](file://public/themes/admin_default/admin/theme/install.html)
- [public/themes/admin_default/admin/theme/files.html](file://public/themes/admin_default/admin/theme/files.html)
- [public/themes/admin_default/admin/theme/file_var_setting.html](file://public/themes/admin_default/admin/theme/file_var_setting.html)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html](file://public/themes/admin_default/admin/theme/file_public_var_setting.html)
- [public/themes/admin_default/admin/theme/file_array_data_edit.html](file://public/themes/admin_default/admin/theme/file_array_data_edit.html)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向希望基于 ThinkCMF 开发主题的开发者，覆盖从零创建新主题的完整流程：目录结构、基础文件与配置、开发环境与工具链、最佳实践、测试与打包发布、常见问题与调试技巧，以及主题商店提交与审核、升级与版本管理策略，并提供示例与模板参考路径。

## 项目结构
ThinkCMF 采用多应用与多主题架构，主题位于 public/themes 目录，分为前台主题与后台主题两套体系。前台主题默认为 default，后台主题默认为 admin_default。主题系统支持可视化设计、全局变量与组件区块配置、多语言等能力。

```mermaid
graph TB
Root["项目根目录"] --> Public["public/"]
Public --> Themes["themes/"]
Themes --> FTheme["default/<br/>前台主题"]
Themes --> ATheme["admin_default/<br/>后台主题"]
FTheme --> FPublic["public/<br/>公共模板"]
FTheme --> FApps["portal/blog 等应用视图<br/>public/themes/default/{应用}/"]
ATheme --> AAdmin["admin/<br/>后台视图"]
ATheme --> APublic["public/<br/>公共模板"]
Public --> Static["static/<br/>官方静态资源"]
Public --> Upload["upload/<br/>公开上传目录"]
Public --> Index["index.php/api.php<br/>应用入口"]
```

图表来源
- [AGENTS.MD:78-135](file://AGENTS.MD#L78-L135)
- [AGENTS.MD:322-363](file://AGENTS.MD#L322-L363)

章节来源
- [AGENTS.MD:78-135](file://AGENTS.MD#L78-L135)
- [AGENTS.MD:322-363](file://AGENTS.MD#L322-L363)

## 核心组件
- 主题清单与元数据
  - 前台主题清单：public/themes/default/manifest.json
  - 后台主题清单：public/themes/admin_default/manifest.json
- 主题公共模板
  - 基础布局：public/themes/default/public/base.html
  - 页面头部：public/themes/default/public/head.html
  - 页面尾部脚本：public/themes/default/public/scripts.html
  - 全局配置：public/themes/default/public/config.json
- 后台主题管理界面
  - 主题列表：public/themes/admin_default/admin/theme/index.html
  - 在线安装：public/themes/admin_default/admin/theme/install.html
  - 文件列表与可视化设计：public/themes/admin_default/admin/theme/files.html
  - 文件变量设置：public/themes/admin_default/admin/theme/file_var_setting.html
  - 全局变量设置：public/themes/admin_default/admin/theme/file_public_var_setting.html
  - 数组数据编辑：public/themes/admin_default/admin/theme/file_array_data_edit.html

章节来源
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)
- [public/themes/default/public/base.html:1-30](file://public/themes/default/public/base.html#L1-L30)
- [public/themes/default/public/head.html:1-59](file://public/themes/default/public/head.html#L1-L59)
- [public/themes/default/public/scripts.html:1-74](file://public/themes/default/public/scripts.html#L1-L74)
- [public/themes/default/public/config.json:1-40](file://public/themes/default/public/config.json#L1-L40)
- [public/themes/admin_default/admin/theme/index.html:1-107](file://public/themes/admin_default/admin/theme/index.html#L1-L107)
- [public/themes/admin_default/admin/theme/install.html:1-57](file://public/themes/admin_default/admin/theme/install.html#L1-L57)
- [public/themes/admin_default/admin/theme/files.html:30-57](file://public/themes/admin_default/admin/theme/files.html#L30-L57)
- [public/themes/admin_default/admin/theme/file_var_setting.html:1-32](file://public/themes/admin_default/admin/theme/file_var_setting.html#L1-L32)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html:34-68](file://public/themes/admin_default/admin/theme/file_public_var_setting.html#L34-L68)
- [public/themes/admin_default/admin/theme/file_array_data_edit.html:1-27](file://public/themes/admin_default/admin/theme/file_array_data_edit.html#L1-L27)

## 架构总览
ThinkCMF 的主题系统遵循“视图独立于应用”的原则：视图层位于 public/themes/{主题}/{应用}/，由控制器渲染。主题通过 manifest.json 提供元信息，通过 config.json 定义全局变量与组件区块，后台提供可视化设计与文件管理能力。

```mermaid
graph TB
subgraph "前台主题(default)"
FB["base.html<br/>布局"]
FH["head.html<br/>头部"]
FS["scripts.html<br/>脚本"]
FC["config.json<br/>全局配置"]
FM["manifest.json<br/>元数据"]
end
subgraph "后台主题(admin_default)"
AI["index.html<br/>主题列表"]
AS["install.html<br/>在线安装"]
AF["files.html<br/>文件与设计"]
AV["file_var_setting.html<br/>文件变量设置"]
AP["file_public_var_setting.html<br/>全局变量设置"]
AA["file_array_data_edit.html<br/>数组数据编辑"]
end
FB --> FH
FB --> FS
FC --> AV
FC --> AP
FM --> AI
FM --> AS
AF --> AV
AF --> AP
AF --> AA
```

图表来源
- [public/themes/default/public/base.html:1-30](file://public/themes/default/public/base.html#L1-L30)
- [public/themes/default/public/head.html:1-59](file://public/themes/default/public/head.html#L1-L59)
- [public/themes/default/public/scripts.html:1-74](file://public/themes/default/public/scripts.html#L1-L74)
- [public/themes/default/public/config.json:1-40](file://public/themes/default/public/config.json#L1-L40)
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/admin/theme/index.html:1-107](file://public/themes/admin_default/admin/theme/index.html#L1-L107)
- [public/themes/admin_default/admin/theme/install.html:1-57](file://public/themes/admin_default/admin/theme/install.html#L1-L57)
- [public/themes/admin_default/admin/theme/files.html:30-57](file://public/themes/admin_default/admin/theme/files.html#L30-L57)
- [public/themes/admin_default/admin/theme/file_var_setting.html:1-32](file://public/themes/admin_default/admin/theme/file_var_setting.html#L1-L32)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html:34-68](file://public/themes/admin_default/admin/theme/file_public_var_setting.html#L34-L68)
- [public/themes/admin_default/admin/theme/file_array_data_edit.html:1-27](file://public/themes/admin_default/admin/theme/file_array_data_edit.html#L1-L27)

## 详细组件分析

### 组件一：主题清单与元数据
- 前台主题清单字段：名称、版本、演示地址、作者、语言、作者链接、关键词、描述
- 后台主题清单字段：名称、版本、演示地址、作者、作者链接、关键词、描述
- 作用：主题商店识别、版本管理、安装与切换的基础依据

章节来源
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)

### 组件二：前台主题公共模板
- 基础布局 base.html：定义页面骨架、SEO 区块、公共头部与脚本、组件区块占位
- 页面头部 head.html：声明标签库、函数库、Meta、CSS、全局 JS 变量
- 页面脚本 scripts.html：加载 JS、初始化交互、组件脚本注入
- 全局配置 config.json：定义全局变量、组件区块、挂载点与默认组件

```mermaid
flowchart TD
Start(["进入页面"]) --> LoadBase["加载 base.html"]
LoadBase --> Head["包含 head.html<br/>注入 CSS/JS/全局变量"]
Head --> WidgetsHead["解析 widgetsHead 标签"]
WidgetsHead --> RenderBody["渲染主体内容区块"]
RenderBody --> Scripts["包含 scripts.html<br/>初始化脚本"]
Scripts --> WidgetsScript["解析 widgetsScript 标签"]
WidgetsScript --> End(["完成渲染"])
```

图表来源
- [public/themes/default/public/base.html:1-30](file://public/themes/default/public/base.html#L1-L30)
- [public/themes/default/public/head.html:1-59](file://public/themes/default/public/head.html#L1-L59)
- [public/themes/default/public/scripts.html:1-74](file://public/themes/default/public/scripts.html#L1-L74)
- [public/themes/default/public/config.json:1-40](file://public/themes/default/public/config.json#L1-L40)

章节来源
- [public/themes/default/public/base.html:1-30](file://public/themes/default/public/base.html#L1-L30)
- [public/themes/default/public/head.html:1-59](file://public/themes/default/public/head.html#L1-L59)
- [public/themes/default/public/scripts.html:1-74](file://public/themes/default/public/scripts.html#L1-L74)
- [public/themes/default/public/config.json:1-40](file://public/themes/default/public/config.json#L1-L40)

### 组件三：后台主题管理与可视化设计
- 主题列表：查看已安装主题、启用状态、设计入口、文件列表、卸载入口
- 在线安装：扫描可用主题并一键安装
- 文件列表与可视化设计：打开设计对话框，支持响应式预览与组件配置
- 文件变量设置：按文件维度配置变量与挂载点
- 全局变量设置：跨文件共享的全局变量配置
- 数组数据编辑：以数组形式维护多条记录的数据项

```mermaid
sequenceDiagram
participant Admin as "管理员"
participant UI as "后台主题界面"
participant Design as "可视化设计"
participant Theme as "主题文件"
Admin->>UI : 打开主题列表
UI-->>Admin : 展示主题与操作按钮
Admin->>UI : 点击“设计”
UI->>Design : 打开设计对话框
Design->>Theme : 加载主题文件与配置
Design-->>Admin : 实时预览与组件配置
Admin->>UI : 保存变量/全局设置
UI-->>Admin : 刷新或提示成功
```

图表来源
- [public/themes/admin_default/admin/theme/index.html:1-107](file://public/themes/admin_default/admin/theme/index.html#L1-L107)
- [public/themes/admin_default/admin/theme/install.html:1-57](file://public/themes/admin_default/admin/theme/install.html#L1-L57)
- [public/themes/admin_default/admin/theme/files.html:30-57](file://public/themes/admin_default/admin/theme/files.html#L30-L57)
- [public/themes/admin_default/admin/theme/file_var_setting.html:1-32](file://public/themes/admin_default/admin/theme/file_var_setting.html#L1-L32)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html:34-68](file://public/themes/admin_default/admin/theme/file_public_var_setting.html#L34-L68)
- [public/themes/admin_default/admin/theme/file_array_data_edit.html:1-27](file://public/themes/admin_default/admin/theme/file_array_data_edit.html#L1-L27)

章节来源
- [public/themes/admin_default/admin/theme/index.html:1-107](file://public/themes/admin_default/admin/theme/index.html#L1-L107)
- [public/themes/admin_default/admin/theme/install.html:1-57](file://public/themes/admin_default/admin/theme/install.html#L1-L57)
- [public/themes/admin_default/admin/theme/files.html:30-57](file://public/themes/admin_default/admin/theme/files.html#L30-L57)
- [public/themes/admin_default/admin/theme/file_var_setting.html:1-32](file://public/themes/admin_default/admin/theme/file_var_setting.html#L1-L32)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html:34-68](file://public/themes/admin_default/admin/theme/file_public_var_setting.html#L34-L68)
- [public/themes/admin_default/admin/theme/file_array_data_edit.html:1-27](file://public/themes/admin_default/admin/theme/file_array_data_edit.html#L1-L27)

## 依赖分析
- 自动加载与命名空间
  - PSR-4 映射 themes\ -> public/themes，使主题可通过命名空间访问
- Composer 依赖
  - ThinkCMF 核心包、API、安装、应用商店等
- 安装后自动脚本
  - 自动执行服务发现、资源发布、数据库迁移

```mermaid
graph LR
CJSON["composer.json<br/>PSR-4: themes\\ -> public/themes"] --> Loader["自动加载器"]
Loader --> ThemesNS["命名空间 themes\\*"]
Scripts["安装后脚本<br/>service:discover / vendor:publish / migrate:run"] --> Runtime["运行时配置/资源/迁移"]
```

图表来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [composer.json:67-72](file://composer.json#L67-L72)

章节来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [composer.json:67-72](file://composer.json#L67-L72)

## 性能考量
- 资源合并与去重
  - 使用模板标签避免重复引入同一 CSS/JS 文件
- 懒加载与按需加载
  - 将非首屏脚本置于页面底部，减少阻塞
- 组件化与区块复用
  - 通过 widgetsHead/widgetsBlock/widgetsScript 提升复用度，降低重复渲染
- 响应式与移动端优化
  - 在 head.html 中设置 viewport 与移动端适配，配合可视化设计的多端预览

章节来源
- [public/themes/default/public/head.html:1-59](file://public/themes/default/public/head.html#L1-L59)
- [public/themes/default/public/scripts.html:1-74](file://public/themes/default/public/scripts.html#L1-L74)
- [public/themes/default/public/base.html:1-30](file://public/themes/default/public/base.html#L1-L30)

## 故障排查指南
- 主题不可见或未生效
  - 检查主题清单 manifest.json 是否存在且字段完整
  - 确认后台主题列表中该主题处于启用状态
- 可视化设计无法打开或预览异常
  - 确认已正确调用设计入口并传入主题名
  - 检查文件列表与变量设置是否保存成功
- 变量或全局设置未生效
  - 确认变量类型与选项配置正确
  - 检查文件变量与全局变量的优先级与作用范围
- 在线安装失败
  - 检查目录权限与网络连通性
  - 确认安装后自动脚本已执行

章节来源
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/admin/theme/index.html:1-107](file://public/themes/admin_default/admin/theme/index.html#L1-L107)
- [public/themes/admin_default/admin/theme/install.html:1-57](file://public/themes/admin_default/admin/theme/install.html#L1-L57)
- [public/themes/admin_default/admin/theme/file_var_setting.html:1-32](file://public/themes/admin_default/admin/theme/file_var_setting.html#L1-L32)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html:34-68](file://public/themes/admin_default/admin/theme/file_public_var_setting.html#L34-L68)

## 结论
通过本指南，开发者可以基于 ThinkCMF 快速搭建并交付高质量主题。建议遵循“清单先行、配置清晰、组件化复用、可视化驱动”的开发流程，并结合后台主题管理工具完成测试、发布与升级。

## 附录

### 从零创建新主题的步骤
- 准备目录结构
  - 在 public/themes 下创建新主题目录，如 new_theme
  - 新建 public/ 与 {应用名}/ 子目录，复制 default 或 admin_default 的对应结构作为起点
- 编写清单与基础模板
  - 在主题根目录创建 manifest.json，填写元信息
  - 在 public/ 下准备 base.html、head.html、scripts.html
  - 在 public/ 下创建 config.json，定义全局变量与组件区块
- 后台主题管理接入
  - 在后台主题列表中可见并启用新主题
  - 使用可视化设计工具进行实时预览与组件配置
- 测试与验证
  - 在不同设备与浏览器下验证响应式效果
  - 使用数组数据编辑与全局变量设置进行数据驱动验证

章节来源
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/default/public/base.html:1-30](file://public/themes/default/public/base.html#L1-L30)
- [public/themes/default/public/head.html:1-59](file://public/themes/default/public/head.html#L1-L59)
- [public/themes/default/public/scripts.html:1-74](file://public/themes/default/public/scripts.html#L1-L74)
- [public/themes/default/public/config.json:1-40](file://public/themes/default/public/config.json#L1-L40)
- [public/themes/admin_default/admin/theme/index.html:1-107](file://public/themes/admin_default/admin/theme/index.html#L1-L107)

### 开发环境与工具链
- 环境要求
  - PHP 8.1+、MySQL 5.5+、开启 rewrite
- Composer 与 Think 命令
  - 安装依赖、更新依赖、优化自动加载
  - Think 命令：服务发现、资源发布、数据库迁移、CLI 工具
- Swagger（可选）
  - 后台安装 Swagger 插件后生成 API 文档

章节来源
- [README.md:84-95](file://README.md#L84-L95)
- [README.md:103-113](file://README.md#L103-L113)
- [AGENTS.MD:600-654](file://AGENTS.MD#L600-L654)

### 主题测试方法与工具
- 响应式测试：利用可视化设计的 PC/Pad/Mobile 预览
- 功能测试：通过数组数据编辑与全局变量设置验证数据驱动
- 兼容性测试：在不同浏览器与设备上验证样式与交互

章节来源
- [public/themes/admin_default/admin/theme/files.html:30-57](file://public/themes/admin_default/admin/theme/files.html#L30-L57)
- [public/themes/admin_default/admin/theme/file_array_data_edit.html:1-27](file://public/themes/admin_default/admin/theme/file_array_data_edit.html#L1-L27)
- [public/themes/admin_default/admin/theme/file_public_var_setting.html:34-68](file://public/themes/admin_default/admin/theme/file_public_var_setting.html#L34-L68)

### 主题打包与发布
- 打包工具
  - 使用 ThinkCMF 提供的“模板发布打包工具”生成可安装包
- 发布前检查
  - 清单完整性、配置正确性、资源无缺失、兼容性验证
- 主题商店提交与审核
  - 提交清单与演示链接，等待审核通过后上线

章节来源
- [README.md:47-49](file://README.md#L47-L49)
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)

### 升级与版本管理策略
- 版本号与兼容性
  - 在 manifest.json 中维护版本号，确保与后台主题列表一致
- 升级流程
  - 通过在线安装替换旧主题，或手动替换文件后刷新缓存
- 多语言与配置迁移
  - 升级时注意多语言配置与变量设置的迁移与回退

章节来源
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/admin/theme/install.html:1-57](file://public/themes/admin_default/admin/theme/install.html#L1-L57)

### 示例项目与模板参考
- 默认前台主题：public/themes/default
- 默认后台主题：public/themes/admin_default
- 可视化设计入口：/admin/theme/design?theme={主题名}

章节来源
- [AGENTS.MD:353-362](file://AGENTS.MD#L353-L362)
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)