模板开发 · 主题配置

主题配置让使用者不改代码就能调整外观。文枢CMS 采用「theme.json 声明字段 → 后台自动渲染表单 → 模板读取值」的模式。

一、声明字段

在 theme.json 的 settings 数组里声明：

{
  "name": "mytheme",
  "title": "我的主题",
  "version": "1.0.0",
  "settings": [
    { "name": "primary_color", "title": "主色调",     "type": "color",  "default": "#4f46e5" },
    { "name": "logo",          "title": "站点 Logo",  "type": "image",  "default": "" },
    { "name": "show_banner",   "title": "显示首屏图", "type": "switch", "default": "1" },
    { "name": "layout",        "title": "列表布局",   "type": "select", "default": "grid",
      "options": { "grid": "网格", "list": "列表" } },
    { "name": "footer_text",   "title": "页脚文字",   "type": "textarea", "default": "" },
    { "name": "icp",           "title": "备案号",     "type": "text",   "default": "" }
  ]
}

支持的字段类型

switch 类型未勾选时提交空值，读取时请统一用 Theme::setting('show_banner') 判断。

二、后台自动渲染

进入 后台 → 模板管理 → 主题设置，程序会：

• 按字段顺序渲染成表单

• 多个字段自动分组为选项卡

• image 类型带上传与预览

• icon 类型带图标选择弹层（数据源：1856 个 Free 图标）

• 保存后写入 ws_theme_setting 表

三、模板中读取

<style>
  :root { --primary: {:theme_setting('primary_color','#4f46e5')}; }
</style>

{if {:theme_setting('show_banner') == '1'}
  <section class="banner"> ... </section>
{/if}

<footer>
  <p>{:theme_setting('footer_text')}</p>
  <a href="https://beian.miit.gov.cn">{:theme_setting('icp')}</a>
</footer>

快捷函数：

{:theme_setting('key')}            取主题设置
{:theme_setting('key','默认值')}   带默认值
{:theme_static('css/style.css')}   主题静态资源地址
{:theme_image('logo')}             图片类型的完整地址

四、多站点与多主题

• 主题设置在站点维度存储，不同站点可使用不同主题与不同配置

• 切换主题后设置值保留，重新切回无需重配

• 主题目录被删除时，相关设置自动忽略并回退默认主题

五、发布主题到应用市场

1. 确认目录结构符合规范（见 模板开发 · 入门）

1. 打包为 .zip，确保 theme.json 位于压缩包根目录或单一顶层目录内

1. 在官网「开发者中心 → 发布应用」上传，或后台「应用市场 → 上传安装」自测

1. 填写标题、分类、价格（免费填 0）、截图与详情

1. 通过审核后即可在市场中被搜索到

同名主题目录存在时会拒绝安装，避免覆盖用户正在使用的主题。