文 文枢CMS v1.0.0
登录 免费注册
模板开发 3 更新于 2026-10-13

模板开发 · 入门

一、主题目录规范

一个主题就是 theme/ 下的一个文件夹：

theme/mytheme/
├── theme.json          主题清单（必需）
├── preview.png         预览图（可选）
├── index/              首页
│   └── index.html
├── list/               列表页
│   ├── index.html      通用列表
│   └── product.html    分类专属列表
├── detail/             详情页
│   └── index.html
├── single/             单页
│   └── index.html
├── form/               表单页
│   └── index.html
├── tag/                标签页
│   └── index.html
├── search/             搜索页
│   └── index.html
├── error/              错误页
│   ├── 404.html
│   └── 500.html
└── common/             公共片段
    ├── header.html
    └── footer.html

静态资源放在 public/theme/mytheme/static/：

public/theme/mytheme/static/
├── css/style.css
├── js/main.js
└── images/

二、theme.json

{
  "name": "mytheme",
  "title": "我的主题",
  "version": "1.0.0",
  "author": "你的名字",
  "description": "一句话描述",
  "responsive": true,
  "settings": [
    { "name": "primary_color", "title": "主色调", "type": "color", "default": "#4f46e5" },
    { "name": "show_banner",   "title": "显示首屏大图", "type": "switch", "default": "1" }
  ]
}

s settings 会在后台「模板管理 → 主题设置」中自动渲染成表单。

三、模板分层与回退

程序按以下顺序查找模板，命中即用：

1. list/product.html   栏目专属模板（栏目里指定，或按模型名匹配）
2. list/index.html     通用列表模板
3. 出错                 提示「模板文件不存在」

四、公共片段

common/header.html：

<!DOCTYPE html>
<html lang="{$siteLang}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{$seoTitle}</title>
  <meta name="keywords" content="{$seoKeywords}">
  <meta name="description" content="{$seoDescription}">
  {$hreflangHtml|raw}
  <link rel="stylesheet" href="{:theme_static('css/style.css')}">
</head>
<body>

common/footer.html：

<footer class="site-footer">
  <p>{$siteCopyright}</p>
</footer>
<script src="{:theme_static('js/main.js')}"></script>
</body>
</html>

在具体模板中引入：

{include file="common/header" /}
<main> ... </main>
{include file="common/footer" /}

五、你的第一个主题

  1. 复制 theme/default 为 theme/mytheme
  1. 修改 theme.json 里的 name 为 mytheme
  1. 后台 → 模板管理 → 启用「我的主题」
  1. 改 public/theme/mytheme/static/css/style.css 调整外观

后台改完 CSS/JS 不需要手动清缓存：cms_asset() 会按文件 mtime 自动附加版本号。

六、模板调试

  • 模板中可直接写 {:dump($cat)} 查看变量结构（生产环境请移除）
  • 报错信息在 .env 中开启 APP_DEBUG = true 后可见
  • 「模板文件不存在」几乎都是模板名没以 / 开头，或目录名拼错

七、打包发布到应用市场

主题开发完成后，theme.json 需位于包根且含 name / title / version 三个必填字段， 包内需有首页模板。完整检测项、打包命令与常见驳回原因见 安装包规范与打包，从认证到上架的流程见 开发者中心与上架流程。

下一页