meta 资源配置说明

本文说明 public/webtopo/meta/ 下各 JSON 配置的字段含义、写法与接入方式。示例可参考 GitHub 仓库 examples/public/webtopo/meta/ 与 examples/public/webtopo/manifest.json。

组态在启动时会加载这四类资源，分别驱动：

配置文件	界面位置	作用
graphics.json	左侧栏「更多图形」	可选图元分组，勾选后在 Stencil 中展示
decorate.json	右侧面板「装饰」	装饰图片分组与列表
background.json	「选择背景图片」弹窗	静态背景图列表
templates.json	底部「组态模板」抽屉	预置画面模板

说明：系统不再内置成套行业图元/装饰资源包，需由宿主项目按本文配置并部署静态文件。

---

1. 如何接入

1.1 方式一：manifest 远程加载（静态部署）

将 webtopo/manifest.json 与 webtopo/meta/*.json 部署到站点可访问路径，组件传入 manifest 地址：

<Webtopo resourceManifest="./webtopo/manifest.json" />

组态会先请求 manifest，再按其中 resources 字段的相对路径依次拉取四个 JSON 文件。路径相对于 manifest 所在目录解析。

1.2 方式二：直接传入对象（打包进前端）

跳过 fetch，在宿主工程中 import JSON 后通过 resources 传入（优先级高于 resourceManifest）：

import graphics from '../public/webtopo/meta/graphics.json'
import decorate from '../public/webtopo/meta/decorate.json'
import background from '../public/webtopo/meta/background.json'
import templates from '../public/webtopo/meta/templates.json'

const webtopoResources = {
  graphics,
  decorate,
  background,
  templates,
}

<Webtopo :resources="webtopoResources" />

1.3 manifest.json 结构

{
  "schemaVersion": 1,
  "resources": {
    "graphics": "meta/graphics.json",
    "decorate": "meta/decorate.json",
    "background": "meta/background.json",
    "templates": "meta/templates.json"
  }
}

• schemaVersion：预留版本号，当前为 1。
• resources：四个资源的相对路径；某键留空或文件缺失时，对应能力为空列表，不会阻断编辑器启动。

---

2. 通用结构

四个文件共用同一套「资源文档」模型，顶层字段如下：

字段	类型	说明
description	string	可选，仅供维护者阅读
groups	array	分组列表，每组含 items
items	array	可选，无分组时的扁平列表（解析时会合成名为「默认」的分组）
defaultGroups	string[]	仅 graphics.json 使用
definitions	object	仅 graphics.json 使用，可复用模板库

2.1 分组（group）

{
  "key": "电力",
  "name": "电力",
  "label": "电力",
  "items": [ /* 资源项 */ ]
}

字段	必填	说明
name	是	分组显示名
key	否	内部标识，缺省同 name
label	否	展示文案，装饰面板下拉优先用 label
items	是	至少包含一条有效资源项

2.2 资源项（item）

字段	必填	说明
key	是	唯一标识
name	是	显示名称 / 搜索关键字
url	条件	图片或 SVG 地址；与 x6Node.markup 二选一
thumb	否	预览缩略图
tagName	否	X6 节点标签，如 "use"
x6Node	否	自定义节点 markup / attrs
status	否	多状态配置

URL 约定

• 推荐相对站点根：./webtopo/nodes/power/Power.svg#Dis_V_D_Open
• 支持 https:// 外链
• SVG 精灵图用 #fragment 引用 symbol id

2.3 pattern 批量展开

{
  "pattern": {
    "template": "./webtopo/decorate/header/{n}.png",
    "from": 1,
    "to": 10
  }
}

• {n} 替换为 from～to 的整数
• 未写 from 时默认为 1
• 单次最多展开 500 条

---

3. graphics.json 高级写法

graphics.json 可通过 definitions + $ref / $use 复用片段。

3.1 definitions — 片段库

在顶层 definitions 中定义可复用对象，不会直接出现在界面：

{
  "definitions": {
    "powerUseItem": {
      "key": "{{url}}",
      "name": "{{name}}",
      "url": "{{url}}",
      "tagName": "use"
    }
  }
}

3.2 $use + $vars — 整项模板

{
  "$use": "powerSwitchVoltageItem",
  "$vars": {
    "key": "./webtopo/nodes/power/Power.svg#Dis_V_D_Open",
    "name": "隔离开关-下",
    "url": "./webtopo/nodes/power/Power.svg#Dis_V_D_Open"
  }
}

3.3 与内置图元的区别

• 基础图元、图表 等仍来自 npm 包内内置列表，不由 meta 配置。
• graphics.json 仅控制「更多图形」里额外展示的分组。
• 用户通过「更多图形」勾选的分组会写入 localStorage（键名 webtopo_select_groups）。

---

4. decorate.json — 装饰图元

用于右侧装饰面板：

{
  "groups": [
    {
      "key": "header",
      "name": "顶部装饰",
      "label": "顶部装饰",
      "items": [
        {
          "pattern": {
            "template": "./webtopo/decorate/header/{n}.png",
            "from": 1,
            "to": 10
          }
        }
      ]
    }
  ]
}

静态文件放在 public/webtopo/decorate/ 下，与 template 路径一致。

---

5. background.json — 背景图列表

用于「选择背景图片」弹窗中的静态背景列表：

{
  "items": [
    {
      "pattern": {
        "template": "./webtopo/background/backgroundH{n}.jpg",
        "from": 1,
        "to": 57
      }
    },
    {
      "key": "bg-svg-2",
      "name": "电厂监控2",
      "url": "./webtopo/background/电厂监控2.svg"
    }
  ]
}

用户上传的个人背景仍走 webtopoAPI 的 getImages / uploadFile。

---

6. templates.json — 组态模板

驱动底部模板抽屉（需开启 showModelTemplateButton）：

{
  "items": [
    {
      "key": "model1",
      "name": "模板1",
      "url": "./webtopo/model/json/model1.json",
      "thumb": "./webtopo/model/model1.png"
    }
  ]
}

字段	说明
key	模板唯一 id
name	抽屉中展示的名称
url	画面 JSON 路径；「应用」会加载并覆盖当前画布
thumb	可选预览图

预览模式也可通过 URL 参数 key 加载 public/webtopo/model/json/<key>.json。

---

7. 配置检查清单

1. 路径可访问：Network 中 JSON 及引用的图片 / 模型文件均返回 200。
2. key 唯一：同一分组内 key 不重复。
3. 分组名一致：defaultGroups 必须与某个 group.name 完全一致。
4. pattern 范围：from ≤ to，且不超过 500 条。
5. 未配置 meta 时：更多图形分组为空，但基础图元、图表等仍可用。

---

8. 相关文档

• 快速接入
• API 接口
• 用户手册 — 图元库
• GitHub 示例：examples/public/webtopo/meta/