Skip to content

Theme Frontend

Jump to bottom
worable edited this page Oct 20, 2026 · 2 revisions

主题前端包

主题可以携带前端包，提供自定义页面模板、Layout 和 Finder。这是 StackPanel 主题系统的核心能力，类似于 Halo 的主题模板。

何时需要前端包

  • 如果主题只需要修改颜色/字体 → 只需 theme.css，不需要前端包
  • 如果主题需要自定义页面结构（如自定义首页、博客列表、文章详情）→ 需要前端包

结构

my-theme/
└── frontend/
    ├── manifest.json     # 前端清单
    └── dist/
        └── index.js      # 编译后的模板组件

前端清单

前端清单声明主题提供的页面、Layout、Finder 等。详见 前端包开发。

主题前端包的典型声明：

{
  "entry": "dist/index.js",
  "pages": [
    { "path": "/", "component": "HomePage" },
    { "path": "/about", "component": "AboutPage" },
    { "path": "/blog", "component": "BlogListPage" },
    { "path": "/blog/:slug", "component": "BlogPostPage" },
    { "path": "*", "component": "NotFoundPage" }
  ],
  "layouts": ["DefaultLayout"],
  "finders": ["blogPosts"]
}

三级覆盖

页面渲染优先级：主题 > 插件 > 内置（resolveFrontendPageSource）。

  • 主题声明了显式页面（非 *//**）时，优先使用主题模板；
  • 否则插件显式页面；再否则主题 fallback（*//**）、插件 fallback、内置。

主题还可以用 overrides 只接管插件的页面外观：键为插件页面路径（如 /shop、/shop/:id），值为主题自己的组件 id。命中时平台渲染主题组件，但页面数据、Finder 与 actions 仍来自插件（packages/sdk/src/frontend.ts 的 FrontendPackage.overrides、resolveThemeOverride）。

页面路由冲突

路由冲突检测只在插件之间进行：启用/安装插件时 assertNoConflictingFrontendPages 比较该插件与所有已激活插件的页面路径（: 参数与 * 通配参与匹配），重叠则返回 409。主题的页面不参与该检测——主题页面与插件页面通过上面的覆盖优先级共存。

预览

管理员可以通过 GET /preview?theme=<id>&path=<path> 预览任意主题的任意页面，无需激活。

详见 打包与上传。

参考

前端包的完整开发文档：

StackPanel 开发者指南

开始

构建内核扩展

AI 与自动化

对接平台

Clone this wiki locally