Template Module (Template Protocol)

The Template module is responsible for the unified template JSON protocol, template import/export helpers, and applying template snapshots to the runtime.

API List

Method	Return Value	Description
sdk.template.getFieldOptions({ panelSchema })	TemplateFieldOption[]	Flattens PanelSchema into options for template authors to select fields
sdk.template.build(options)	GeneratorTemplateDefinition	Builds a template JSON based on current state, parameter schema, and selected fields
sdk.template.serialize(template)	string	Serializes a template object into a downloadable JSON string
sdk.template.parse(text)	GeneratorTemplateDefinition	Parses and validates a template JSON string
sdk.template.download(template, options?)	void	Downloads the template JSON in the browser
sdk.template.toRuntimeSnapshot(template)	TemplateRuntimeSnapshot	Outputs { state, panelFilter }
sdk.template.applyToRuntime(runtime, template, options?)	Promise<void>	Applies the template state to the runtime and can return the panelFilter

Typical Usage

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: 'Spring Template',
    authoringMode: 'manual',
  },
})

sdk.template.download(template)

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

Standard Template Protocol

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>
}

Conventions:

• defaults is the default state snapshot of the template.
• panelFilter is the unique standard for the template consumption side.
• adjustableFields is metadata for template authoring tools and does not replace panelFilter.
• includeFields / excludeFields / readonlyFields are recommended to use field.bind.path.

getFieldOptions()

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

The return value flattens PanelSchema.groups[].fields[] into:

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'],
})

Rules:

• selectedFieldPaths must have corresponding bind.path in PanelSchema.
• The generated panelFilter.includeFields will match the selected paths.
• The generated adjustableFields will preserve groups and field labels for template authoring UIs.

parse() and serialize()

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

parse() validates:

• type === 'generator-template'
• version === '1.0.0'
• The structure of generatorId, defaults, panelFilter, and adjustableFields is valid.

toRuntimeSnapshot() and applyToRuntime()

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

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

Notes:

• toRuntimeSnapshot() is suitable for hosts that want to manage the template consumption process themselves.
• applyToRuntime() calls runtime.setState(snapshot.state, { source }) by default.
• If the host also needs to synchronize the template's parameter clipping results, it can save the panelFilter via onPanelFilter.