进阶用法

深入了解 SDK 的高级功能和使用场景。

类型推导

SDK 提供了完整的 TypeScript 类型推导支持。通过 InferTemplateValueMap 类型，可以从 configJson 自动推导出运行时 valueMap 的类型。

import { defineTemplateConfig } from 'template-sdk/config'
import type { InferTemplateValueMap } from 'template-sdk'

const configJson = defineTemplateConfig({
  meta: { name: 'demo' },
  dataSchema: {
    fields: [
      { key: 'title', type: 'string', value: 'Hello' }
    ]
  }
})

// 自动推导类型
type ValueMap = InferTemplateValueMap<typeof configJson>
// { title: string }

配置校验

使用 validateTemplateConfig 函数可以在运行时校验配置是否符合规范。

import { validateTemplateConfig } from 'template-sdk'

const issues = validateTemplateConfig({
  dataSchema: {
    fields: [
      { key: 'title', type: 'string' }
    ]
  }
})

if (issues.length > 0) {
  console.error('配置校验失败', issues)
}

构建产物导出

SDK 提供了多个构建相关的工具函数，可以用于自定义构建流程。

buildTemplateValueMap

根据 configJson 构建 valueMap。

import { buildTemplateValueMap } from 'template-sdk'

const valueMap = buildTemplateValueMap(configJson)

buildTemplateArtifacts

构建完整的模板产物。

import { buildTemplateArtifacts } from 'template-sdk'

const artifacts = buildTemplateArtifacts(configJson)

buildTemplateJsonFiles

构建 JSON 文件产物。

import { buildTemplateJsonFiles } from 'template-sdk'

const files = buildTemplateJsonFiles(configJson)

嵌套数组取值

对于嵌套的数组字段，可以使用点路径语法进行读取。

configJson 示例

{
  "dataSchema": {
    "fields": [
      {
        "key": "sections",
        "type": "array",
        "value": [
          {
            "key": "section1",
            "type": "array",
            "value": [
              { "key": "item", "type": "string" }
            ]
          }
        ]
      }
    ]
  }
}

取值方式

const sections = useTemplateValue('sections')
const firstSection = useTemplateValue('sections[0]')
const nestedItem = useTemplateValue('sections[0].item')

媒体对象

image 和 video 字段在运行时返回的是媒体对象，而不是字符串路径。

{
  "url": "/assets/poster.png",   // 媒体 URL
  "alt": "海报图片",             // 替代文本
  "poster": "/assets/poster-thumb.png" // 视频封面
}

在模板中使用

<template>gt;
  <img :src="poster.url" :alt="poster.alt" />

  <video :src="trailer.url" :poster="trailer.poster">
  </video>
</template>

自定义构建配置

templateSdkPlugin 支持传入额外的构建配置选项。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import configJson from './src/template/config'
import { templateSdkPlugin } from 'template-sdk/vite'

export default defineConfig({
  plugins: [
    templateSdkPlugin({
      configJson
      // 可以添加更多配置选项
    }),
    vue()
  ]
})

调试技巧

在开发过程中，可以通过以下方式进行调试：

查看运行时值

const title = useTemplateValue('title', '')

// 在控制台查看
console.log('title value:', title.value)

查看生成的类型文件

SDK 会自动生成 .template-sdk/**/*.d.ts 文件，可以查看这些文件了解 SDK 生成的类型定义。