configJson 结构

了解 configJson 的完整结构，包括所有支持的字段类型和配置选项。

顶层结构

configJson 必须是完整的配置对象：

{
  "meta": {},
  "dataSchema": {
    "fields": []
  },
  "functions": {}
}

属性	说明	类型
`meta`	模板元信息对象	`object`
`dataSchema`	字段定义容器	`object`
`functions`	模板函数能力声明，用于后台展示和跨设备函数绑定	`object`

meta 对象

meta 是模板元信息对象，没有强制字段白名单，常见字段如下：

{
  "meta": {
    "name": "示例模板",
    "code": "demo-template",
    "version": "0.1.0"
  }
}

属性	说明	类型	必填
`name`	模板名称	`string`	否
`code`	模板代码	`string`	否
`version`	模板版本	`string`	否

通用字段对象

字段对象用于描述一个可配置项。根字段和 object 子字段需要 key，数组项模板可以省略 key。

{
  "key": "title",
  "type": "string",
  "label": "标题",
  "value": "默认标题"
}

属性	说明	类型	必填
`key`	字段唯一标识；根字段和 object 子字段必填，数组项模板可省略	`string`	按位置决定
`type`	字段类型	`string`	是
`label`	字段展示名	`string`	否
`value`	默认值	`unknown`	否

通用规则：

根字段和 object.value 子字段的 key 必须是非空字符串
array.value 中的数组项模板可以省略 key
同一层级内 key 不能重复
value 不是必填；有 value 时表示默认值

支持的字段类型

当前支持以下类型：

string

普通文本

number

数字

boolean

布尔值

image

图片路径

video

视频路径

file

文件路径

object

对象字段

array

字段数组

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/template/poster-core.svg"
}

注意： image 在 configJson 里只接受字符串路径（相对路径或绝对 URL）。

video 字段

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

注意： video 在 configJson 里只接受字符串路径（相对路径或绝对 URL）。

file 字段

{
  "key": "modelFile",
  "type": "file",
  "label": "模型文件",
  "value": "/assets/models/demo.glb",
  "accept": [".glb", ".gltf"]
}

accept 写法： 可填写内置类型 image、video、audio，也可以填写带点号的后缀，例如 .glb、.pdf。

object 字段

object.value 是一组带 key 的子字段，页面中读取为普通对象。

{
  "key": "profile",
  "type": "object",
  "label": "基础信息",
  "value": [
    { "key": "name", "type": "string", "label": "名称", "value": "示例展项" },
    { "key": "level", "type": "number", "label": "等级", "value": 1 }
  ]
}

array 字段

array.value 的第一项是新增数组项时使用的结构模板。数组项模板可以省略 key；当一项包含多个字段时，推荐使用匿名 object。

{
  "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"] }
      ]
    }
  ]
}

operations 属性

值	说明
`add`	允许添加新项
`delete`	允许删除已有项

operations 默认行为：

未填写 operations 时，默认允许 add 和 delete
operations: [] 表示不允许任何操作
新增数组项只复用第一项结构，不复制第一项内容
新增值会按类型置空，例如 string/file 为空字符串、number 为 0、boolean 为 false

functions 函数声明

从 0.2.0 开始，functions 不再只是预留对象，而是模板能力清单。后台会读取这些函数，设备关联后可以按规则触发其他模板或硬件函数。

{
  "functions": {
    "playVideo": {
      "label": "播放视频",
      "description": "按视频 ID 播放指定内容",
      "direction": "inout",
      "params": [
        { "name": "id", "type": "string", "required": true },
        { "name": "seekTo", "type": "number", "defaultValue": 0 }
      ],
      "transport": {
        "qos": "at_most_once",
        "timeoutMs": 3000
      },
      "tags": ["video"]
    }
  }
}

属性	说明
`label`	后台展示名。
`description`	函数说明。
`direction`	`in` 可被外部调用，`out` 作为触发源，`inout` 两者都支持。
`params`	参数定义，类型支持 `string`、`number`、`boolean`、`object`、`array`、`any`。
`transport`	调用超时和 QoS 配置，`timeoutMs` 支持 100 到 30000。

保留字段： valueMap.__templateSdk 是 SDK 元信息命名空间，业务字段不能使用 __templateSdk 作为 key。