快速开始

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

完整接入流程

第一步：编写 configJson

在项目中任选位置创建 configJson 文件，定义模板的字段结构。下面以 config.ts 为例：

import { defineTemplateConfig } from 'auto-exhibition-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: {
    showDetail: {
      label: '显示详情',
      description: '接收展项 ID 并切换到详情状态',
      direction: 'inout',
      params: [
        { name: 'id', type: 'string', required: true }
      ]
    }
  }
})

export default configJson

第二步：配置 Vite 插件

在 vite.config.ts 中启用 templateSdkPlugin：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import configJson from './config'
import { templateSdkPlugin } from 'auto-exhibition-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 'auto-exhibition-template-sdk'

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

第四步：在组件中取值

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

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

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

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

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

第五步：构建并上传

开发完成后，运行构建命令：

pnpm build

构建完成后，将 dist 目录打包上传到后台模板管理。上传的是构建后的目录，不是源码目录。

可选：注册模板函数

如果模板需要被其他设备或硬件规则触发，需要在运行时注册与 configJson.functions 对应的 handler：

import { registerTemplateFunction } from 'auto-exhibition-template-sdk'

registerTemplateFunction('showDetail', async (args) => {
  currentId.value = args.id
  return { ok: true }
})

完整示例

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

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

const configJson = defineTemplateConfig({
  meta: {
    name: '示例模板',
    code: 'demo-template',
    version: '0.1.0'
  },
  dataSchema: {
    fields: [
      { key: 'title', type: 'string', label: '标题', value: '默认标题' },
      { key: 'count', type: 'number', label: '数量', value: 3 },
      { key: 'enabled', type: 'boolean', label: '启用状态', value: true },
      { key: 'poster', type: 'image', label: '海报', value: '/assets/poster.png' },
      { key: 'trailer', type: 'video', label: '视频', value: 'https://example.com/video.mp4' },
      { key: 'modelFile', type: 'file', label: '模型文件', value: '/assets/model.glb', accept: ['.glb', '.gltf'] },
      {
        key: 'controls',
        type: 'object',
        label: '控制项',
        value: [
          { key: 'showGrid', type: 'boolean', label: '显示网格', value: true },
          { key: 'buttonText', type: 'string', label: '按钮文案', value: '查看模型' }
        ]
      },
      {
        key: 'models',
        type: 'array',
        label: '模型列表',
        operations: ['add', 'delete'],
        value: [
          {
            type: 'object',
            label: '模型项',
            value: [
              { key: 'name', type: 'string', label: '模型名称', value: 'Meteor Shower' },
              { key: 'url', type: 'file', label: '模型文件', value: '/assets/models/demo.glb', accept: ['.glb', '.gltf'] },
              { key: 'cameraDistance', type: 'number', label: '相机距离', value: 2.8 }
            ]
          }
        ]
      }
    ]
  },
  functions: {
    showDetail: {
      label: '显示详情',
      direction: 'inout',
      params: [
        { name: 'id', type: 'string', required: true }
      ]
    }
  }
})

export default configJson

常见问题

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

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

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

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

Q: 数组字段新增时会复制第一项内容吗？

不会。第一项只作为结构模板，后台新增数组项时会按字段类型生成空值，例如字符串为空字符串、数字为 0、布尔值为 false。