快速开始

本章节介绍如何快速接入 template-sdk 到你的模板项目中。

完整接入流程

第一步：编写 configJson

在项目中创建 src/template/config.ts 文件，定义模板的字段结构：

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

const configJson = defineTemplateConfig({
  meta: {
    name: '示例模板',
    code: 'demo-template',
    version: '0.1.0'
  },
  dataSchema: {
    fields: [
      {
        key: 'title',
        type: 'string',
        label: '标题',
        value: '星图态势科技舱'
      },
      {
        key: 'poster',
        type: 'image',
        label: '主视觉海报',
        value: '/assets/template/poster-core.svg'
      }
    ]
  },
  functions: {}
})

export default configJson

第二步：配置 Vite 插件

在 vite.config.ts 中启用 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()
  ]
})

第三步：安装运行时

在 main.ts 中安装 TemplateSdk：

import { createApp } from 'vue'
import App from './App.vue'
import TemplateSdk from 'template-sdk'

const app = createApp(App)
app.use(TemplateSdk)
app.mount('#app')

第四步：在组件中取值

使用 useTemplateValue 组合式函数读取字段值：

<!-- src/components/HeroSection.vue -->
<script setup>
import { useTemplateValue } from 'template-sdk'

// 读取标题字段
const title = useTemplateValue('title', '默认标题')

// 读取图片字段
const poster = useTemplateValue('poster', null)
</script>

<template>gt;
  <section class="hero">
    <h1>{{ title }}</h1>
    <img :src="poster?.url" :alt="poster?.alt" />
  </section>
</template>

第五步：构建产物

开发完成后，运行构建命令生成模板产物：

pnpm build

构建完成后，dist 目录中会包含 config.json 和 assets/template-sdk/valueMap.json 等文件，这些是上传到管理后台的必需文件。

完整示例

完整的配置示例展示了如何使用所有支持的字段类型：

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

const configJson = defineTemplateConfig({
  meta: {
    name: '示例模板',
    code: 'demo-template',
    version: '0.1.0'
  },
  dataSchema: {
    fields: [
      // string 类型
      { key: 'title', type: 'string', label: '标题', value: '默认标题' },

      // number 类型
      { key: 'count', type: 'number', label: '数量', value: 3 },

      // boolean 类型
      { key: 'enabled', type: 'boolean', label: '启用状态', value: true },

      // image 类型
      { key: 'poster', type: 'image', label: '海报', value: '/assets/poster.png' },

      // video 类型
      { key: 'trailer', type: 'video', label: '视频', value: 'https://example.com/video.mp4' },

      // array 类型（数组字段）
      {
        key: 'timeline',
        type: 'array',
        label: '时间轴',
        operations: ['add', 'delete'],
        value: [
          { key: 'phase01', type: 'string', label: '阶段一', value: '接入边缘传感节点。' },
          { key: 'phase02', type: 'string', label: '阶段二', value: '将采集数据转换为状态向量。' }
        ]
      }
    ]
  },
  functions: {}
})

export default configJson

常见问题

Q: 为什么使用 defineTemplateConfig 而不是直接导出对象？

defineTemplateConfig 提供了 TypeScript 类型推导支持。使用它可以让编辑器准确知道配置的结构，从而提供更好的智能提示。

Q: image 和 video 字段的 value 为什么是字符串？

在 configJson 中，媒体字段的值是资源路径字符串（相对路径或绝对 URL）。SDK 在运行时会自动将其转换为媒体对象，提供更丰富的属性（如 url、poster、alt）。

Q: 如何修改模板的运行时内容？

平台侧可以通过修改构建产物中的 valueMap.json 来改变模板的运行时内容，无需修改 configJson 源文件。