Template 模块（模板协议）

Template 模块负责统一模板 JSON 协议、模板导入导出 helper，以及把模板快照应用到 runtime。

API 列表

方法	返回值	说明
sdk.template.getFieldOptions({ panelSchema })	TemplateFieldOption[]	将 PanelSchema 展平成模板作者可勾选字段
sdk.template.build(options)	GeneratorTemplateDefinition	根据当前状态、参数 schema 和勾选字段构建模板 JSON
sdk.template.serialize(template)	string	将模板对象序列化为可下载 JSON
sdk.template.parse(text)	GeneratorTemplateDefinition	解析并校验模板 JSON
sdk.template.download(template, options?)	void	在浏览器中下载模板 JSON
sdk.template.toRuntimeSnapshot(template)	TemplateRuntimeSnapshot	输出 { state, panelFilter }
sdk.template.applyToRuntime(runtime, template, options?)	Promise<void>	将模板状态应用到 runtime，并可回传 panelFilter

典型用法

const template = sdk.template.build({
  generatorId: runtime.generatorId,
  appKey: 'your_app_key',
  state: runtime.getState(),
  panelSchema: runtime.getPanelSchema(),
  selectedFieldPaths: ['params.text', 'params.color'],
  templateMeta: {
    name: '春日模板',
    authoringMode: 'manual',
  },
})

sdk.template.download(template)

const imported = sdk.template.parse(jsonText)
await sdk.template.applyToRuntime(runtime, imported, {
  onPanelFilter(panelFilter) {
    currentPanelFilter = panelFilter
  },
})

标准模板协议

interface GeneratorTemplateDefinition {
  type: 'generator-template'
  version: '1.0.0'
  generatorId: string
  appKey?: string
  templateMeta?: Record<string, unknown>
  defaults: Record<string, unknown>
  panelFilter: {
    includeGroups?: string[]
    includeFields?: string[]
    excludeGroups?: string[]
    excludeFields?: string[]
    readonlyFields?: string[]
  }
  adjustableFields: Array<{
    groupId: string
    groupTitle?: string
    fieldId: string
    fieldLabel?: string
    path: string
  }>
  metadata?: Record<string, unknown>
}

约定：

• defaults 是模板默认状态快照
• panelFilter 是模板消费侧的唯一标准
• adjustableFields 是模板作者工具元数据，不替代 panelFilter
• includeFields / excludeFields / readonlyFields 推荐使用 field.bind.path

getFieldOptions()

const options = sdk.template.getFieldOptions({
  panelSchema: runtime.getPanelSchema(),
})

返回值会把 PanelSchema.groups[].fields[] 扁平化为：

type TemplateFieldOption = {
  groupId: string
  groupTitle?: string
  fieldId: string
  fieldLabel?: string
  path: string
}

build()

const template = sdk.template.build({
  generatorId: 'frame-lab',
  state: runtime.getState(),
  panelSchema: runtime.getPanelSchema(),
  selectedFieldPaths: ['params.text', 'params.color'],
})

规则：

• selectedFieldPaths 必须能在 PanelSchema 中找到对应 bind.path
• 生成的 panelFilter.includeFields 会与所选路径保持一致
• 生成的 adjustableFields 会保留分组与字段标签，便于模板作者 UI 使用

parse() 与 serialize()

const text = sdk.template.serialize(template)
const parsed = sdk.template.parse(text)

parse() 会校验：

• type === 'generator-template'
• version === '1.0.0'
• generatorId、defaults、panelFilter、adjustableFields 的结构有效

toRuntimeSnapshot() 与 applyToRuntime()

const snapshot = sdk.template.toRuntimeSnapshot(template)
// snapshot => { state, panelFilter }

await sdk.template.applyToRuntime(runtime, template, {
  source: 'template-import',
  onPanelFilter(panelFilter) {
    hostPanelFilter = panelFilter
  },
})

说明：

• toRuntimeSnapshot() 适合宿主自己接管模板消费流程
• applyToRuntime() 默认调用 runtime.setState(snapshot.state, { source })
• 若宿主还要同步模板的参数裁剪结果，可通过 onPanelFilter 保存 panelFilter