Theme Settings

主题设置

主题可以通过前端包的 settingsSchema 声明可配置选项，管理员在后台表单中修改，前端模板读取这些设置值。

设置 Schema

设置 schema 声明在前端包的 manifest.json 中，字段定义详见设置 Schema：

{
  "settingsSchema": {
    "groups": [
      {
        "id": "layout",
        "label": "布局",
        "fields": [
          {
            "name": "sidebarWidth",
            "label": "侧边栏宽度",
            "type": "number",
            "default": 240
          }
        ]
      },
      {
        "id": "colors",
        "label": "颜色",
        "fields": [
          {
            "name": "accentColor",
            "label": "强调色",
            "type": "color",
            "default": "#2563eb"
          }
        ]
      }
    ]
  }
}

读取设置

前端通过 GET /themes/:id/settings 获取解析后的设置值，结果是 schema 默认值与存储值的合并：

curl http://127.0.0.1:3001/themes/my-theme/settings

{
  "settings": {
    "layout": { "sidebarWidth": 240 },
    "colors": { "accentColor": "#2563eb" }
  }
}

设置存储在 settings 表，键格式为 theme:<id>。

修改设置

管理后台：/admin/themes → 选择主题 → 设置。

API：

curl -X PATCH http://127.0.0.1:3001/admin/themes/my-theme/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"layout": {"sidebarWidth": 300}}}'

更新是 partial merge：只更新传入的字段，未传入的字段保持不变；合并后的值会用 zod schema 验证。

设置 Schema 端点

获取主题的设置 schema，用于动态生成表单：

curl http://127.0.0.1:3001/themes/my-theme/settings-schema

{ "schema": { "groups": [] } }

存储机制

• 设置值存储在 settings 表的 value JSON 字段
• 键为 theme:<id>
• 读取时合并 schema 默认值与存储值
• 更新时对当前值与传入值做 partial merge
• updatedBy 记录最后修改者