Frontend Settings Schema

设置 Schema

前端包可以通过 settingsSchema 声明可配置选项，平台自动生成管理后台设置表单。

Schema 结构

{
  "settingsSchema": {
    "groups": [
      {
        "id": "general",
        "label": "常规设置",
        "fields": [
          {
            "name": "siteTitle",
            "label": "站点标题",
            "type": "text",
            "default": "StackPanel"
          },
          {
            "name": "itemsPerPage",
            "label": "每页条数",
            "type": "number",
            "default": 20
          },
          {
            "name": "showSidebar",
            "label": "显示侧边栏",
            "type": "boolean",
            "default": true
          }
        ]
      },
      {
        "id": "theme",
        "label": "主题样式",
        "fields": [
          {
            "name": "accentColor",
            "label": "强调色",
            "type": "color",
            "default": "#2563eb"
          },
          {
            "name": "layout",
            "label": "布局模式",
            "type": "select",
            "default": "sidebar",
            "options": [
              { "label": "侧边栏", "value": "sidebar" },
              { "label": "顶部导航", "value": "topnav" }
            ]
          }
        ]
      }
    ]
  }
}

字段详解

group

字段	必填	说明
id	✅	分组标识（英文）
label	✅	分组显示名
fields	✅	字段列表

field

字段	必填	说明
name	✅	字段标识（英文）
label	✅	字段显示名
type	✅	text / textarea / color / number / boolean / select / radio
default	—	默认值（类型必须与 type 匹配）
help	—	字段下方的说明文字
required	—	是否必填
placeholder	—	占位符（text / textarea / color）
min/max	—	数值范围（number）
step	—	步长（number）
options	—	select / radio 必填，[{ label, value }]，至少一项

支持的类型

type	值类型	表单控件
text	string	文本输入
textarea	string	多行文本
color	string	颜色选择器
number	number	数字输入
boolean	boolean	开关
select	string	下拉选择
radio	string	单选按钮组

设置存储

设置值存储在 settings 表：

包类型	键格式
主题	theme:<id>
插件	plugin:<id>

设置解析

读取设置时，平台合并 schema 默认值 + 存储值：

resolved = merge(defaultsFromSchema, storedValues)

合并后用 zod schema 验证，确保类型正确。

设置更新

更新是 partial merge——只更新传入的字段，未传入的保持不变：

PATCH /admin/plugins/my-plugin/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"general": {"siteTitle": "新标题"}}}'

查询接口

获取设置 Schema

GET /plugins/my-plugin/settings-schema
GET /themes/my-theme/settings-schema
→ { "schema": { "groups": [...] } }

获取解析后设置

GET /plugins/my-plugin/settings
GET /themes/my-theme/settings
→ { "settings": { "general": { "siteTitle": "StackPanel", "itemsPerPage": 20 } } }

更新设置（管理员）

PATCH /admin/plugins/my-plugin/settings
PATCH /admin/themes/my-theme/settings

前端使用

组件通过 props 接收设置值：

export function HomePage({ settings }: { settings: FrontendSettings }) {
  const siteTitle = settings.general?.siteTitle ?? 'StackPanel';
  return <h1>{siteTitle}</h1>;
}

无 Schema

如果前端包没有声明 settingsSchema，设置相关端点返回空值，更新端点返回错误。