valueMap 的角色

了解 valueMap 在 SDK 中的重要地位，以及为什么需要将"结构定义"和"运行时内容"彻底分离。

核心概念

valueMap 是 SDK 最重要的数据边界。它是 SDK 根据 configJson 生成的运行时快照，包含所有字段的当前值。

一句话总结： configJson 是源配置，valueMap 是运行时快照。模板项目开发阶段只维护 configJson，运行时只读取 valueMap。

数据边界划分

谁维护什么

文件	维护者	用途
configJson	模板作者	定义字段结构和默认值
valueMap.json	SDK（构建时生成）	运行时读取的内容

SDK 自动生成

SDK 在开发和构建阶段根据 configJson 自动生成 valueMap：

┌─────────────────┐      SDK       ┌─────────────────┐
│                 │   ──────────>   │                 │
│   configJson    │   (构建时)       │   valueMap      │
│                 │                 │                 │
└─────────────────┘                 └─────────────────┘
     模板作者维护                       运行时读取

为什么需要分离

configJson 和 valueMap 分离的目的是把"结构定义"和"运行时内容"彻底分开。

保证不互相干扰

模板作者：维护的配置结构不会被运行时回写
平台侧：只需要替换 valueMap.json 就能改变页面展示内容

构建时和运行时一致性

SDK 使用同一套字段校验与默认值归一逻辑，确保：

构建时的配置校验逻辑和运行时的取值逻辑完全一致
不会出现"构建通过但运行出错"的情况

运行链路

SDK 的运行链路是固定的：

模板项目把 configJson 传给 templateSdkPlugin

在 vite.config.ts 中配置

插件生成 .template-sdk/**/*.d.ts 和产物

生成 config.json 和 valueMap.json

模板项目运行时只安装 TemplateSdk

在 main.ts 中调用 app.use(TemplateSdk)

TemplateSdk 自动读取配置和值映射

读取 ./config.json 和 ./assets/template-sdk/valueMap.json

页面组件通过 useTemplateValue 按路径读取

使用点路径如 title、timeline[0].phase 读取值

useTemplateValue 路径规则

useTemplateValue 只有一套路径语义：

只接受点路径，例如 title、timeline[0].phase
不接受以 / 开头的旧写法
普通字段直接返回标量值
image/video 运行时统一读取为媒体对象
array 运行时读取为字段对象数组

路径示例

路径	说明
`title`	读取根级 string 字段
`poster`	读取根级 image 字段
`timeline`	读取根级 array 字段
`timeline[0]`	读取数组第一项
`timeline[0].phase`	读取数组第一项的 phase 子字段

产物结构

构建完成后，dist 目录中包含以下与 SDK 相关的文件：

dist/
├── config.json                              # 模板配置副本
└── assets/
    └── template-sdk/
        └── valueMap.json                    # 运行时值映射
            └── ...