模板与主题管理

DoraCMS 支持灵活的模板和主题系统，允许你自定义网站的外观和布局，打造独特的用户体验。

模板系统概述

什么是模板

模板是网站前端展示的基础，包含：

页面布局：首页、列表页、详情页等
样式文件：CSS、SCSS 等样式
脚本文件：JavaScript 交互逻辑
静态资源：图片、字体等

模板系统

模板特点

主题切换：一键切换网站主题
完整性检查：自动验证模板文件完整性
版本管理：支持模板版本控制
配置灵活：可自定义模板配置

模板管理

查看模板列表

登录管理后台
进入"系统设置" → "模板管理"
查看已安装的模板

模板列表

模板信息

每个模板包含以下信息：

基本信息：

模板名称 (name)：模板的显示名称
模板标识 (slug)：唯一标识符，用于系统识别
版本号 (version)：模板版本，如 1.0.0
作者 (author)：模板开发者
描述 (description)：模板功能说明

状态信息：

是否激活 (active)：当前是否为激活主题
是否安装 (installed)：模板是否已安装
系统模板 (isSystemTemplate)：是否为系统内置模板

其他信息：

截图 (screenshot)：模板预览图
统计数据 (stats)：使用统计
创建时间 (createdAt)：模板创建时间

模板详情

切换主题

激活模板

在模板列表中找到要激活的模板
点击"激活"按钮
确认切换操作
系统会自动切换到新主题

注意：

同一时间只能激活一个主题
切换主题后前端页面会立即生效
建议在非高峰期切换主题

激活主题

预览主题

在激活前可以预览主题效果：

点击模板的"预览"按钮
在新窗口中查看主题效果
确认满意后再激活

模板配置

模板配置项

每个模板可以有自定义配置 (config)：

{
  "name": "默认主题",
  "slug": "default",
  "version": "1.0.0",
  "author": "doramart",
  "description": "DoraCMS 默认主题",
  "config": {
    "primaryColor": "#1890ff",
    "layout": "default",
    "showSidebar": true,
    "footerText": "© 2024 DoraCMS"
  }
}

常见配置项

颜色配置：

primaryColor：主题色
secondaryColor：辅助色
backgroundColor：背景色

布局配置：

layout：布局类型（default、boxed、full-width）
showSidebar：是否显示侧边栏
sidebarPosition：侧边栏位置（left、right）

功能配置：

showBreadcrumb：是否显示面包屑导航
showComments：是否显示评论
showRelated：是否显示相关文章

模板配置

模板完整性检查

什么是完整性检查

系统会自动检查模板文件的完整性，确保：

必需的文件都存在
文件格式正确
配置文件有效

检查结果

完整性检查会返回：

{
  "isValid": true,
  "missingFiles": [],
  "errors": [],
  "warnings": [
    "建议添加 favicon.ico"
  ]
}

检查项目：

必需文件：index.html、style.css 等
配置文件：theme.json
静态资源：图片、字体等

完整性检查

模板开发

模板目录结构

themes/
└── your-theme/
    ├── theme.json          # 主题配置文件
    ├── screenshot.png      # 主题截图
    ├── views/              # 视图模板
    │   ├── index.ejs       # 首页模板
    │   ├── list.ejs        # 列表页模板
    │   └── detail.ejs      # 详情页模板
    ├── public/             # 静态资源
    │   ├── css/            # 样式文件
    │   ├── js/             # 脚本文件
    │   └── images/         # 图片资源
    └── README.md           # 说明文档

主题配置文件

theme.json 示例：

{
  "name": "我的主题",
  "slug": "my-theme",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "一个简洁优雅的主题",
  "screenshot": "screenshot.png",
  "requiredVersion": "3.0.0",
  "config": {
    "primaryColor": "#1890ff",
    "layout": "default"
  },
  "features": [
    "响应式设计",
    "SEO 优化",
    "快速加载"
  ]
}

模板文件

首页模板 (index.ejs)：

<!DOCTYPE html>
<html>
<head>
  <title><%= siteName %></title>
  <link rel="stylesheet" href="/themes/<%= theme %>/css/style.css">
</head>
<body>
  <header>
    <h1><%= siteName %></h1>
  </header>

  
  <main>
    <% articles.forEach(article => { %>
      <article>
        <h2><%= article.title %></h2>
        <p><%= article.description %></p>
        <a href="/article/<%= article.id %>">阅读更多</a>
      </article>
    <% }) %>
  </main>

  
  <footer>
    <p><%= footerText %></p>
  </footer>
</body>
</html>

列表页模板 (list.ejs)：

<!DOCTYPE html>
<html>
<head>
  <title><%= category.name %> - <%= siteName %></title>
</head>
<body>
  <h1><%= category.name %></h1>

  
  <div class="article-list">
    <% articles.forEach(article => { %>
      <div class="article-item">
        <h2><a href="/article/<%= article.id %>"><%= article.title %></a></h2>
        <p><%= article.description %></p>
        <span class="date"><%= article.createdAt %></span>
      </div>
    <% }) %>
  </div>

  
  <!-- 分页 -->
  <div class="pagination">
    <!-- 分页组件 -->
  </div>
</body>
</html>

详情页模板 (detail.ejs)：

<!DOCTYPE html>
<html>
<head>
  <title><%= article.title %> - <%= siteName %></title>
  <meta name="description" content="<%= article.description %>">
  <meta name="keywords" content="<%= article.keywords %>">
</head>
<body>
  <article>
    <h1><%= article.title %></h1>
    <div class="meta">
      <span>作者：<%= article.author %></span>
      <span>发布时间：<%= article.createdAt %></span>
    </div>

    
    <div class="content">
      <%- article.content %>
    </div>

    
    <!-- 相关文章 -->
    <div class="related">
      <h3>相关文章</h3>
      <!-- 相关文章列表 -->
    </div>

    
    <!-- 评论 -->
    <div class="comments">
      <!-- 评论组件 -->
    </div>
  </article>
</body>
</html>

创建自定义模板

步骤说明

创建模板目录

mkdir -p themes/my-theme
cd themes/my-theme

创建配置文件
- 创建 theme.json
- 填写模板信息

创建视图文件
- 创建 views 目录
- 添加页面模板

添加静态资源
- 创建 public 目录
- 添加 CSS、JS、图片

添加截图
- 创建 screenshot.png
- 尺寸建议：800x600

注册模板
- 在管理后台添加模板
- 填写模板信息
- 上传模板文件

模板变量

在模板中可以使用以下变量：

系统变量：

siteName：网站名称
siteLogo：网站 Logo
siteKeywords：网站关键词
siteDescription：网站描述

内容变量：

article：文章对象
articles：文章列表
category：分类对象
categories：分类列表
tags：标签列表

用户变量：

user：当前用户信息
isLogin：是否登录

分页变量：

currentPage：当前页码
totalPages：总页数
pageSize：每页数量

模板缓存

缓存机制

DoraCMS 使用缓存提高模板渲染性能：

模板编译缓存：编译后的模板会被缓存
数据缓存：常用数据会被缓存
自动刷新：模板更新后自动清除缓存

清除缓存

在以下情况需要清除缓存：

修改模板文件后
切换主题后
更新配置后

清除方法：

进入"系统设置" → "缓存管理"
点击"清除模板缓存"
确认操作

最佳实践

性能优化

资源压缩
- 压缩 CSS 和 JavaScript 文件
- 优化图片大小
- 使用 CDN 加速

懒加载
- 图片懒加载
- 按需加载组件
- 延迟加载非关键资源

缓存策略
- 设置合理的缓存时间
- 使用浏览器缓存
- 启用服务器缓存

兼容性

浏览器兼容
- 测试主流浏览器
- 使用 CSS 前缀
- 提供降级方案

响应式设计
- 适配不同屏幕尺寸
- 使用媒体查询
- 测试移动端效果

无障碍访问
- 使用语义化 HTML
- 添加 ARIA 属性
- 提供键盘导航

安全性

XSS 防护
- 转义用户输入
- 使用 <%= 而不是 <%-
- 验证外部链接

CSRF 防护
- 使用 CSRF Token
- 验证请求来源

内容安全
- 过滤恶意代码
- 限制文件上传类型
- 验证数据格式

常见问题

模板不生效

问题：切换主题后前端没有变化

解决方案：

清除模板缓存
清除浏览器缓存（Ctrl+F5）
检查模板是否正确激活
查看服务器日志

模板文件缺失

问题：提示模板文件不完整

解决方案：

检查必需文件是否存在
查看完整性检查结果
补充缺失的文件
重新上传模板

样式显示异常

问题：页面样式错乱

解决方案：

检查 CSS 文件路径
确认静态资源正确加载
查看浏览器控制台错误
验证 CSS 语法

变量未定义

问题：模板中变量显示为 undefined

解决方案：

检查变量名是否正确
确认数据是否传递到模板
查看服务器日志
使用默认值处理

模板与主题管理