settings_schema.json 说明

路径：public/theme/default/config/settings_schema.json（database 主题存于 o_theme_asset 的 /config 目录）。
与 settings_data.json（默认值）成对使用；读取入口 ThemesService::getThemeConfig()，经 mergeDefaultSettingsSchema() 处理后返回给装修后台。

安装与前台整体链路（config → initThemeData → 哪些表 → 访客如何渲染）：见 theme-decoration-and-liquid-rendering.md § 一、总体流程。

一、文件在整体链路中的位置

flowchart LR
    subgraph Schema["settings_schema.json"]
        GS[global_setting]
        PS[pages_setting]
        BS[blocks_setting]
        DBS[default_blocks_setting]
    end

    subgraph Data["settings_data.json"]
        GD[global 默认值]
        PD[pages_settings 默认值]
    end

    subgraph DB["店铺数据"]
        STP[o_store_theme.params / preview_params]
        TB[o_theme_block]
    end

    subgraph API["后台 API"]
        CFG["GET themes/{id}/configs"]
        SEC["GET themes/{id}/sectionsconfig"]
        TD["GET themes/{id}/data"]
        GL["PUT themes/{id}/globaldata"]
    end

    Schema --> CFG
    Data --> CFG
    STP --> TD
    TB --> TD
    GS --> GL
    CFG --> AdminUI[装修后台 UI]
    SEC --> AdminUI
    TD --> AdminUI

文件 / 数据	角色
settings_schema.json	定义「能配什么、在哪一页、用什么表单控件」——结构 + UI schema
settings_data.json	定义「出厂默认填什么」——初始值
*sections/.liquid 内 schema**	单个 section/block 的字段定义与 `default`（`GET sectionsconfig`）
o_store_theme.params	商家保存的全局配置（含 header/footer 等 global section）
o_theme_block	各页面的积木块实例（拖拽区内容）

二、顶层结构

{
  "global_setting": [ ... ],
  "pages_setting": [ ... ],
  "blocks_setting": [ ... ],
  "default_blocks_setting": {
    "mode": "",
    "exclude_block_ids": []
  }
}

三、`global_setting` — 主题全局设置

3.1 作用

定义 整站级 装修表单：间距、颜色、字体、商品展示开关、社交媒体、账户中心等。
不对应某个 route 页面，也不写入 o_theme_block。

3.2 数据结构

数组，每项为一 Tab 分组：

{
  "name": { "zh_CN": "常规", "en_US": "Routine" },
  "settings": [
    {
      "type": "card_input_number",
      "id": "general_layout_spacing",
      "label": { "zh_CN": "积木块间距", "en_US": "Block spacing" },
      "min": 0,
      "max": 200,
      "default": "80",
      "info": { "zh_CN": "...", "en_US": "..." }
    }
  ]
}

字段	说明
`name`	Tab 标题（多语言）
`settings[]`	该 Tab 下表单项列表
`settings[].type`	控件类型（见下表）
`settings[].id`	字段 key，写入 `global` 根级或嵌套对象
`settings[].default`	schema 内默认值（最终以 `settings_data.json` + 商家保存为准）

default 主题 Tab 示例（6 个）：常规、颜色、字体、商品、社交媒体、账户中心。

3.3 支持的 `type`（表单控件）

type	用途
`card_header`	分组标题（无 id，仅展示）
`card_input_number`	数字输入
`card_input`	文本输入
`card_switch`	开关
`card_color`	颜色选择
`card_image`	图片（如转场 Logo）
`card_font`	字体选择
`card_select` / `card_select_show`	下拉
`card_radio_tag` / `card_tags` / `card_slider`	标签、滑块等

装修后台按 type 渲染对应 Vue/React 组件（前端不在本仓库，由 GET themes/{id}/configs 的 settings_schema.global_setting 驱动）。

3.4 与 `settings_data.global` 的关系

global_setting：字段定义（有哪些项、控件类型、范围）
settings_data.global：字段 默认值，结构示例：

{
  "sections": {
    "header": { "settings": { ... }, "blocks": [], "type": "header" },
    "footer": { "settings": { ... }, "blocks": [], "type": "footer" }
  },
  "general_layout_spacing": "80",
  "page_background_color": "#fff"
}

global.sections.header/footer 对应 global section（is_global=true），在 layout 里直接渲染，不进 o_theme_block。
根级 key（如 general_layout_spacing）对应 global_setting 里带 id 的表单项。

3.5 后台页面展示

后台区域	对应数据
主题设置 / 全局设置侧栏或顶栏	`global_setting` 各 Tab
保存	`PUT themes/{id}/globaldata` → `ThemesService::updateThemeGlobalData()`
读取合并值	`getThemeGlobalData()` = `settings_data.global` 深合并 `o_store_theme.preview_params`
前台变量	`HomePublicVarsService::setThemeGlobalData()` → Liquid `theme_config.global`

四、`pages_setting` — 可装修页面清单

4.1 作用

定义装修后台 左侧「页面列表」（首页、商品详情、专辑列表…）
声明每个页面 允许出现哪些 section、是否固定（header/footer）
安装主题时 initThemeData() 按此初始化 o_theme_block
运行时 sectionsFormat() 补全 fixed / global section

4.2 数据结构

{
  "name": { "zh_CN": "首页", "en_US": "Home page" },
  "route": "index/index",
  "route_handle": "",
  "max_block": 40,
  "layout": true,
  "sections": [
    {
      "type": "header",
      "fixed": "top",
      "name": { "zh_CN": "页头", "en_US": "Page header" }
    },
    {
      "type": "block_slides",
      "fixed": "",
      "name": { "zh_CN": "轮播图", "en_US": "Slideshow" }
    },
    {
      "type": "footer",
      "fixed": "bottom",
      "name": { "zh_CN": "页尾", "en_US": "Page footer" }
    }
  ]
}

字段	说明
`route`	ThinkPHP 路由，如 `product/detail`、`index/index`
`route_handle`	页面级 handle，多数列表/首页为空
`max_block`	该页可拖拽积木数量上限（后台校验用）
`layout`	是否走标准 layout（含 header/footer 外壳）
`sections[]`	该页 section 清单
`sections[].type`	对应 `sections/{type}.liquid`
`sections[].fixed`	位置约束（见下表）

4.3 `fixed` 取值

fixed	含义	DB `o_theme_block.fixed`	行为
`top`	页顶固定	1	如 header；global section 时数据在 `global.sections`
`bottom`	页底固定	3	如 footer
`require`	必需块	4	不可删，如 `product_detail`
`""`（空）	可拖拽区	2	商家可增删排序

首页 index/index 示例：1×top(header) + 13×可拖拽 block + 1×bottom(footer)。
商品详情 product/detail：header(top) + product_detail(require) + footer(bottom)。

4.4 API 增强字段

GET themes/{id}/configs 调用 getThemeConfig($id, [], 1)，needPagePreviewUrl=1 时为每项填充：

追加字段	来源
`url`	根据 `route` 生成带 `?theme_id=` 的预览 URL（取店铺第一个商品/专辑等）
`obj_type`	`ThemesConfigResponse` 从 route 推导，如 `PRODUCT`
`is_support_group`	是否支持组装修（商品/专辑等详情页为 true）

无有效预览 URL 的页面会从列表中移除（如店铺尚无商品时 product/detail 可能不出现）。

4.5 default 主题页面列表（16 个 route）

route	说明
`index/index`	首页
`product/detail`	商品详情（支持组装修）
`collection/list` / `collection/detail`	专辑列表 / 详情
`topic/list` / `topic/detail`	专题
`search/detail`	搜索
`coupon/list` / `coupon/detail`	优惠券
`promotion/list` / `promotion/detail`	促销活动
`blog/list` / `blog/detail`	博客
`news/list` / `news/detail`	新闻
`module/notfound`	404

4.6 后台页面展示

后台区域	对应数据
页面下拉 / 页面切换	`pages_setting[].name` + `url`
iframe 预览	`pages_setting[].url`
当前页固定区（头尾）	`sections` 中 `fixed=top/bottom/require`
中间拖拽画布	`GET themes/{id}/data?route=&route_handle=` 返回的 `sections`（来自 `o_theme_block`）
组装修入口	`is_support_group=true` 的页面显示分组切换

4.7 与 `initThemeData` 的关系

安装主题时遍历 pages_setting：

跳过 is_global=true 的 section（header/footer）
对其余 section 插入 o_theme_block，params 来自 settings_data.pages_settings[route_routeHandle][type] 或 section schema 的 default

五、`blocks_setting` — 可添加积木块库

5.1 作用

定义装修后台 「添加积木块」面板：分类、图标、可选 block 类型。
商家从库中拖拽/点击添加到当前 route 的中间区域。

与 pages_setting.sections 的区别：

	pages_setting	blocks_setting
用途	页面初始布局 + fixed 声明	可选添加的 block 类型库
安装时	写入 DB 初始 blocks	不直接写 DB
添加时	—	用户点击添加 → `POST themes/{id}/sections`

5.2 数据结构

按分类分组：

{
  "type": "card_header",
  "name": { "zh_CN": "基础积木", "en_US": "Basic Blocks" },
  "sections": [
    {
      "id": "block_slides",
      "type": "block",
      "name": { "zh_CN": "轮播图", "en_US": "Slideshow" },
      "icon": "icon-lunbotu",
      "routes": []
    }
  ]
}

字段	说明
`name`	分类名称（基础积木 / 商品块 / 运营类）
`sections[].id`	block 类型，对应 `sections/{id}.liquid`
`sections[].type`	固定为 `"block"`（与 page section 区分）
`sections[].icon`	后台图标 class
`sections[].routes`	可选；非空时仅在这些 route 下展示该 block

routes 过滤示例：

block_h1_media → 仅 ["index/index"]
block_default_product_recommend → 仅 ["product/detail"]
routes: [] → 所有页面可用

default 主题：3 个分类，共 61 个可添加 block（29 + 13 + 19）。

5.3 添加 block 时的默认值

ThemeBlockService::add()：

getThemeSectionsConfig() 取 sections/{type}.liquid 内 {% schema %} 的 default
写入 o_theme_block.preview_params
若无 default → 抛 THEME_BLOCK_CONFIG_NOT_FOUND

右侧 单块表单 由 sectionsconfig API 的 schema 驱动，不是 blocks_setting 里的条目。

5.4 后台页面展示

后台区域	对应数据
左侧「添加积木」分类树	`blocks_setting[].name`
分类下 block 列表	`blocks_setting[].sections[]`（按 `routes` 过滤当前页）
点击添加	`POST themes/{id}/sections`，body 含 `type` = `sections[].id`
右侧配置表单	`GET themes/{id}/sectionsconfig` → 对应 liquid schema

六、`default_blocks_setting` — 与 default 主题 merge 策略

6.1 作用

仅服务端使用，装修后台 不直接展示。
在 ThemesService::mergeDefaultSettingsSchema() 中，决定当前主题的 blocks_setting 是否与 public/theme/default/config/settings_schema.json 的 blocks_setting 合并。

6.2 数据结构

{
  "mode": "",
  "exclude_block_ids": []
}

字段	说明
`mode`	为 `"none"` 时不合并 default 的 blocks_setting，仅用当前主题自己的库
`exclude_block_ids`	合并时从 default 库中排除的 block id 列表

6.3 merge 逻辑（简述）

1. mode == "none" → 原样返回当前 schema
2. 读取 default 的 blocks_setting，按 exclude_block_ids 过滤
3. 与当前主题 blocks_setting 按分类 name.zh_CN 为 key 做 arrayMergeDeep
4. 同 id 的 block：当前主题覆盖 default
5. 写回 settings_schema.blocks_setting

典型场景：

子主题/二开皮只新增少量 block → 留空 mode，继承 default 全部 61 个基础 block
精简主题、只要自有 block → mode: "none"
继承 default 但去掉某几个 → exclude_block_ids: ["block_twitter", ...]

file 主题读磁盘时、database 主题读 asset 时都会走 merge。

七、与相关 API 的对照表

API	使用的 schema 部分	返回 / 作用
`GET themes/{id}/configs`	全部 + `setting_data`	装修初始化：全局表单、页面列表、积木库
`GET themes/{id}/sectionsconfig`	—（读 liquid `{% schema %}`）	每个 section/block 的字段 schema
`GET themes/{id}/data`	间接（route 来自 pages_setting）	当前页已保存 blocks + global
`PUT themes/{id}/globaldata`	global_setting 定义的字段	更新 `preview_params`
`POST themes/{id}/sections`	blocks_setting 的 `id`	新增 block 实例
`GET themes/{id}/settingsdata`	—	导出为 settings_data 格式（发布数据）

八、与 `settings_data.json` 的分工

问题	看哪个
后台表单长什么样？	`settings_schema`（global_setting / section liquid schema）
新装主题默认填什么？	`settings_data.json`
商家改过后存哪？	global → `o_store_theme`；页面积木 → `o_theme_block`
主题升级新增字段默认值？	`getThemeGlobalData()` 用 `arrayMergeDeep(setting_data.global, params)`

pages_settings 在 settings_data.json 中的结构与 pages_setting 不同：前者是值（含 params），后者是 页面与 section 类型声明。

九、改主题时的实践建议

新增可装修页面：在 pages_setting 增加 route + sections；必要时在 settings_data.pages_settings 写默认 params。
新增可拖拽 block：新增 sections/block_xxx.liquid + schema；在 blocks_setting 某分类下增加 id；若需仅某页可用，设 routes。
新增全局设置项：在 global_setting 某 Tab 加表单项 + settings_data.global 默认值。
子主题不继承 default 积木库：default_blocks_setting.mode = "none"。
database 主题：改 settings_schema.json 后通过 themeasset API 或 ThemeTool 同步；改 settings_data.json 可能触发 initThemeDataBySettingData 重建 blocks（谨慎）。

十、相关代码索引

逻辑	文件 / 方法
读取与 merge	`ThemesService::getThemeConfig()`, `mergeDefaultSettingsSchema()`
安装初始化 blocks	`ThemesService::initThemeData()`
全局保存	`ThemesService::updateThemeGlobalData()`
页面列表增强	`ThemesService::getThemeConfig(..., needPagePreviewUrl=1)`
组装修标记	`ThemesConfigResponse::handler()`
运行时补 fixed	`ThemesService::sectionsFormat()`
添加 block	`ThemeBlockService::add()` + `getThemeSectionsConfig()`

上级文档：theme-decoration-and-liquid-rendering.md

oemsaas 开发知识库

探索

settings-schema-reference

settings_schema.json 说明

一、文件在整体链路中的位置

二、顶层结构

三、`global_setting` — 主题全局设置

3.1 作用

3.2 数据结构

3.3 支持的 `type`（表单控件）

3.4 与 `settings_data.global` 的关系

3.5 后台页面展示

四、`pages_setting` — 可装修页面清单

4.1 作用

4.2 数据结构

4.3 `fixed` 取值

4.4 API 增强字段

4.5 default 主题页面列表（16 个 route）

4.6 后台页面展示

4.7 与 `initThemeData` 的关系

五、`blocks_setting` — 可添加积木块库

5.1 作用

5.2 数据结构

5.3 添加 block 时的默认值

5.4 后台页面展示

六、`default_blocks_setting` — 与 default 主题 merge 策略

6.1 作用

6.2 数据结构

6.3 merge 逻辑（简述）

七、与相关 API 的对照表

八、与 `settings_data.json` 的分工

九、改主题时的实践建议

十、相关代码索引

关系图谱

目录

反向链接

oemsaas 开发知识库

探索

settings-schema-reference

settings_schema.json 说明

一、文件在整体链路中的位置

二、顶层结构

三、global_setting — 主题全局设置

3.1 作用

3.2 数据结构

3.3 支持的 type（表单控件）

3.4 与 settings_data.global 的关系

3.5 后台页面展示

四、pages_setting — 可装修页面清单

4.1 作用

4.2 数据结构

4.3 fixed 取值

4.4 API 增强字段

4.5 default 主题页面列表（16 个 route）

4.6 后台页面展示

4.7 与 initThemeData 的关系

五、blocks_setting — 可添加积木块库

5.1 作用

5.2 数据结构

5.3 添加 block 时的默认值

5.4 后台页面展示

六、default_blocks_setting — 与 default 主题 merge 策略

6.1 作用

6.2 数据结构

6.3 merge 逻辑（简述）

七、与相关 API 的对照表

八、与 settings_data.json 的分工

九、改主题时的实践建议

十、相关代码索引

关系图谱

目录

反向链接

三、`global_setting` — 主题全局设置

3.3 支持的 `type`（表单控件）

3.4 与 `settings_data.global` 的关系

四、`pages_setting` — 可装修页面清单

4.3 `fixed` 取值

4.7 与 `initThemeData` 的关系

五、`blocks_setting` — 可添加积木块库

六、`default_blocks_setting` — 与 default 主题 merge 策略

八、与 `settings_data.json` 的分工