Theme Frontend

主题前端包

主题可以携带前端包，提供自定义页面模板、Layout 和 Finder。前端包位于主题的 frontend/ 目录，清单格式与插件前端包一致，完整写法见前端包介绍。

需要前端包的场景

• 只修改颜色或字体：提供 theme.css 即可，不需要前端包。
• 需要自定义页面结构（自定义首页、博客列表、文章详情等）：需要前端包。

结构

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

前端清单

前端清单声明主题提供的页面、Layout、Finder 等，字段定义见前端清单、页面路由、命名 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）：

1. 主题声明了显式页面（非 *//**）且路径命中时，使用主题模板；
2. 否则使用插件的显式页面；
3. 都没有时，依次回退到主题的 *//** 页面、插件的 *//** 页面，最后是内置页面。

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

页面路由冲突

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

预览

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

安装、激活与预览的操作步骤见打包与上传。