Theme Introduction

主题介绍

StackPanel 主题用于替换平台的视觉风格和页面结构。主题是配置而非代码：颜色以 CSS 自定义属性（Token）声明在 theme.css，页面模板由随包提供的前端包声明。

主题包内容

一个主题包包含以下文件：

• theme.json — 主题清单，声明 ID、名称、版本等元数据。
• theme.css — CSS Token 声明，覆盖默认配色。
• assets/ — 可选静态资源，如 Logo、favicon、字体。
• frontend/ — 可选前端包，提供页面模板、Layout 与 Finder。

管理员可配置的主题选项在 frontend/manifest.json 的 settingsSchema 中声明。各文件的位置与职责见主题结构。

能力边界

主题可以：

• 定义 CSS Token，覆盖默认视觉风格；
• 携带前端包，提供自定义页面模板、Layout 与 Finder；
• 通过 settingsSchema 声明配置项，由管理员在后台表单中填写；
• 携带静态资源。

主题不提供后端能力：不能声明 HTTP 路由，不能读写数据库表，也没有插件扩展点。需要这些能力时应改用插件。

包内禁止包含的文件

上传校验会拒绝包含以下内容的主题包：

• 可执行后端代码；
• HTTP 路由声明；
• 除前端包 dist/ 目录外的 .js、.ts、.mjs、.cjs、.jsx、.tsx 文件；
• theme.css 中的 url()、@import 等 @ 规则、:root 与 .dark 之外的选择器，以及 expression() 表达式。

完整的校验规则与体积限制见打包与上传。

主题与插件的分工

能力	主题	插件
后端代码	不支持	支持
CSS Token	支持（theme.css）	不支持
前端包	支持（可选）	支持（可选）
HTTP 路由	不支持	支持
数据库表	不支持	支持

前端渲染优先级

前端页面渲染遵循 主题 > 插件 > 内置 的覆盖顺序，主题的页面模板优先于插件和内置模板。判定规则与 overrides 用法见主题前端包。

内置主题

default 是内置主题，启动时自动 seed 到 data/themes/default/。它不可删除，并保证平台上至少有一个可用主题。

default 包含完整的前端包，其中的 /about、/blog、/blog/:slug 等页面路由和主题 404 页面可以直接作为编写模板的参照。

激活与预览

• 激活：同一时刻只有一个主题 active=true。激活新主题时自动取消旧主题。
• 预览：无需激活即可预览任意主题，预览状态存储在 settings 表，不影响线上。

操作步骤见打包与上传。