简介

本文件面向设计师与前端开发者，系统化说明 DouPHP 小程序与网站的主题定制机制。内容涵盖：

• 多主题支持的技术实现（主题变量、动态切换、用户偏好存储）
• 图片与资源的主题化管理（图标、背景图、品牌色等）
• 登录界面与评论界面的主题适配方案
• 主题预览、调试与测试方法
• 主题兼容性与降级策略、性能优化建议

项目结构

DouPHP 同时提供“网站主题”和“小程序主题”两套体系：

• 网站主题位于 theme 目录，按主题名组织模板、样式与资源；默认主题为 default。
• 小程序主题位于 miniprogram 目录，包含 pages、images、style、app.json 等；默认主题为 default。
• 后台配置项通过 SettingService 暴露，用于管理站点 Logo、微信二维码等可主题化资源。

graph TB
A["前端请求"] --> B["初始化模块<br/>front/init/Init.php"]
B --> C["视图引擎<br/>DouView"]
C --> D["主题目录选择<br/>theme/{activeTheme}"]
D --> E["模板渲染<br/>.dwt + inc/*"]
subgraph "小程序"
F["小程序入口<br/>miniprogram/default/app.json"]
G["页面与样式<br/>pages/*, style/*, images/*"]
end
H["后台设置<br/>admin/service/setting/SettingService.php"] --> D
H --> F

核心组件

• 主题加载器：在初始化阶段根据当前激活主题确定模板目录，并注册预处理器与编译缓存路径。
• 主题扩展钩子：允许主题通过 inc/..from_theme.php 注入业务逻辑或覆盖默认行为。
• 页面级主题覆盖：控制器可按 slug 优先使用主题内同名 .dwt 模板，否则回退到默认模板。
• 小程序主题配置：app.json 定义窗口样式、TabBar 图标与颜色；setting.php 提供图片尺寸规范。
• 后台设置服务：集中处理站点 Logo、微信二维码等可主题化资源的路径转换与选项框生成。

架构总览

网站端主题渲染流程：

• 初始化时确定 activeTheme，将 DouView 的 template_dir 指向 theme/{activeTheme}。
• 模板文件采用 .dwt 与 inc/*.tpl 组合，header.tpl/footer.tpl 作为公共布局片段。
• 页面控制器优先匹配主题内同名模板，未命中则回退到默认模板。

小程序端主题渲染流程：

• app.json 声明页面路由、窗口样式与 TabBar 图标/颜色。
• 各页面 wxml/wxss/ts 组合实现 UI 与交互，images 存放主题资源。
• 后台设置项经 API 下发后，小程序侧以本地 store 或页面 data 驱动 UI。

sequenceDiagram
participant U as "用户"
participant FE as "网站前端"
participant INIT as "初始化(Init.php)"
participant VIEW as "视图引擎(DouView)"
participant TPL as "主题模板(.dwt)"
participant CTRL as "页面控制器"
U->>FE : 访问页面
FE->>INIT : 触发初始化
INIT->>VIEW : 设置 template_dir = theme/{activeTheme}
VIEW->>CTRL : 解析路由与数据
CTRL->>TPL : 优先加载主题模板 / 回退默认模板
TPL-->>FE : 返回渲染后的HTML/CSS/JS

详细组件分析

网站主题系统

• 主题目录与模板：
  • 模板根目录为 theme/{activeTheme}，包含 .dwt 页面模板与 inc/ 公共片段。
  • header.tpl 负责顶部导航、语言切换、搜索与登录态展示；footer.tpl 负责底部导航、联系方式与版权信息。
• 主题扩展：
  • 若存在 inc/..from_theme.php，将在页面渲染前执行，便于主题注入自定义逻辑或覆盖默认行为。
• 页面模板优先级：
  • 控制器会先查找 theme/{activeTheme}/{slug}.dwt，不存在则使用默认 page.dwt。

flowchart TD
Start(["进入页面"]) --> CheckTpl{"主题内是否存在 {slug}.dwt?"}
CheckTpl --> |是| UseTheme["使用主题模板渲染"]
CheckTpl --> |否| UseDefault["使用默认模板渲染"]
UseTheme --> End(["完成"])
UseDefault --> End

小程序主题系统

• 全局样式与 TabBar：
  • app.json 中 window 控制导航栏样式，tabBar 控制底部导航图标与选中色。
  • 主题可通过替换 images/tabbar_* 与修改 selectedColor 实现品牌色切换。
• 图片与尺寸规范：
  • setting.php 定义了 logo、banner、产品图、文章图等推荐尺寸，指导主题资源制作。
• 登录页主题适配：
  • 登录页 login_account.wxml/ts 通过 commonStore/site 获取站点名称与基础配置，结合 wxss 实现主题化样式。
• 用户中心与数据绑定：
  • user.ts 在 onShow 中拉取用户信息与功能开关，结合 store 与 data 驱动界面状态。

sequenceDiagram
participant App as "小程序应用"
participant JSON as "app.json"
participant Page as "登录页(login_account.ts)"
participant Store as "commonStore/site"
participant API as "后端API"
App->>JSON : 读取窗口与TabBar配置
Page->>Store : 读取站点配置(site)
Page->>API : 检查登录状态/提交登录
API-->>Page : 返回用户信息与跳转目标
Page->>App : 重定向至首页或工作台

主题变量与动态切换

• 网站端：
  • 通过后台设置项（如 site_logo_miniprogram、weixin_img）集中管理可主题化资源，SettingService 负责路径拼接与选项框生成。
  • 主题切换由 activeTheme 决定，可在后台启用不同主题目录。
• 小程序端：
  • 通过 app.json 的 window/tabBar 与 images 资源实现主题外观切换。
  • 登录成功后，根据后端返回决定是否跳转到工作台或会员中心，体现不同主题的差异化流程。

图片与资源的主题化管理

• 网站主题资源：
  • 主题目录下的 images 与 css/js 共同构成视觉风格；header.tpl/footer.tpl 引用站点 Logo 与二维码等资源。
• 小程序主题资源：
  • images/tabbar_* 系列图标与 logo.png 等为核心品牌元素；app.json 指定 TabBar 图标路径与颜色。
• 第三方主题示例：
  • _' 目录下多个主题（如 m029、m064）展示了独立 CSS 与资源组织方式，便于对比学习。

登录界面与评论界面的主题适配

• 登录界面：
  • 登录页通过 commonStore/site 获取站点名称与基础配置，结合 wxss 实现主题化样式；登录后根据后端返回进行页面跳转。
• 评论界面：
  • 小程序 comment 页面位于 pages/comment，其 wxml/wxss 可依据主题 images 与 style 进行定制；网站端 comment.dwt 与 comment.css 同理。

主题开发工具链（预览、调试与测试）

• 预览：
  • 网站端：切换 activeTheme 后刷新页面即可看到主题效果；利用浏览器开发者工具检查模板与样式加载。
  • 小程序端：使用微信开发者工具打开 miniprogram/default，实时预览 app.json 与页面样式变化。
• 调试：
  • 网站端：查看 DouView 编译缓存目录（STORAGE_PATH/cache/template/front），确认模板是否按预期编译。
  • 小程序端：通过控制台日志与网络面板检查 API 调用与数据绑定。
• 测试：
  • 验证不同主题下 header/footer 的资源引用是否正确。
  • 验证小程序 TabBar 图标与颜色是否符合品牌规范。
  • 验证登录流程在不同主题下的跳转逻辑一致。

依赖关系分析

• 初始化依赖：
  • Init.php 负责装配视图引擎与主题目录，ThemeExtensionLoader.php 提供主题扩展能力。
• 控制器依赖：
  • PageController.php 根据 slug 选择模板，确保主题优先。
• 小程序依赖：
  • app.json 声明页面与窗口样式，login_account.ts 与 user.ts 负责用户流程与数据绑定。

graph LR
INIT["front/init/Init.php"] --> VIEW["DouView"]
VIEW --> THEME["theme/{activeTheme}"]
THEME --> HEADER["inc/header.tpl"]
THEME --> FOOTER["inc/footer.tpl"]
PAGECTRL["front/controller/page/PageController.php"] --> THEME
APPJSON["miniprogram/default/app.json"] --> PAGES["pages/*"]
LOGIN["miniprogram/default/pages/user/login_account.ts"] --> STORE["commonStore/site"]

性能与兼容性

• 性能优化建议：
  • 图片压缩与按需加载：遵循 setting.php 的尺寸规范，避免过大图片影响加载速度。
  • 模板编译缓存：确保 STORAGE_PATH 可写，减少重复编译开销。
  • 样式拆分与懒加载：将非首屏样式延迟加载，提升首屏渲染速度。
• 兼容性处理：
  • 旧版浏览器：使用 polyfill 或降级样式，确保基本功能可用。
  • 小程序基础库差异：在 ts 中做能力检测，必要时降级交互体验。
• 降级策略：
  • 主题资源缺失时，回退到默认主题资源。
  • 接口异常时，显示友好提示并保留当前页面状态。

故障排查指南

• 主题未生效：
  • 检查 activeTheme 是否正确设置，template_dir 是否指向主题目录。
  • 确认 .dwt 模板是否存在且命名正确。
• 小程序 TabBar 异常：
  • 核对 app.json 中 tabBar.list 的 iconPath 与 selectedIconPath 是否存在。
  • 检查 images 目录下的图标文件是否完整。
• 登录流程异常：
  • 检查后端返回的用户信息与跳转逻辑，确认 store 中的数据绑定是否正确。

结论

DouPHP 的主题系统通过清晰的目录结构与模板机制，实现了网站与小程序的多主题支持。借助后台设置与小程序配置，可灵活管理品牌资源与外观样式。遵循本文档的实践建议，设计师与前端开发者可高效完成主题定制、调试与发布。

附录：主题开发工具链与实践

• 主题创建步骤：
  • 在 theme 或 miniprogram 下新建主题目录，复制默认主题结构。
  • 修改 app.json 或 .dwt 中的资源路径与样式。
• 预览与调试：
  • 网站端使用浏览器开发者工具；小程序端使用微信开发者工具。
• 测试清单：
  • 验证所有页面模板是否按主题加载。
  • 验证小程序 TabBar 与登录流程是否正常。
• 最佳实践：
  • 保持资源命名规范，避免冲突。
  • 使用统一的样式变量与尺寸规范，便于维护与升级。