vue3-wiring-diagram 1.0.1

package/README.md

@@ -0,0 +1,1727 @@
+<h1 align="center">vue3-wiring-diagram</h1>
+
+Vue 3 wiring diagram components based on X6 and Element Plus.
+
+[中文文档](#中文文档) | [API Specification](#api-specification) | [中文接口规范](#接口规范)
+
+## Features
+
+- Editor, preview, and automatic generation components.
+- Built-in `zh-CN` and `en-US` text.
+- Shared API configuration for `baseURL`, `token`, custom headers, timeout, and image asset prefix.
+- Component `locale` controls both UI text and the `Accept-Language` request header.
+- Element Plus is provided by the host application, so existing host themes can keep taking effect.
+
+## Requirements
+
+The host application must use Vue 3 and install Element Plus:
+
+```bash
+npm install vue element-plus @element-plus/icons-vue
+```
+
+## Install
+
+```bash
+npm install vue3-wiring-diagram
+```
+
+## Basic Host Setup
+
+Register Element Plus in the host application first. Then import the plugin style.
+
+```js
+import {createApp} from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import '@/styles/index.scss'
+
+import 'vue3-wiring-diagram/style.css'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(ElementPlus)
+app.mount('#app')
+```
+
+If your host project uses Vite, dedupe Vue and Element Plus to avoid loading two Vue runtimes:
+
+```js
+// vite.config.js
+export default {
+  resolve: {
+    dedupe: ['vue', 'element-plus', '@element-plus/icons-vue']
+  }
+}
+```
+
+## Request Configuration
+
+Call `configure` before rendering components. `headers` is optional and only needed when your backend requires extra headers, such as tenant id, app id, or custom auth fields. If your backend does not need them, omit `headers`.
+
+```js
+import {
+  configure,
+  setAssetBaseURL,
+  setBaseURL,
+  setToken
+} from 'vue3-wiring-diagram'
+
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token',
+  timeout: 10000
+})
+
+setBaseURL('/api/cny')
+setAssetBaseURL('/api')
+setToken('token')
+```
+
+Optional custom headers:
+
+```js
+configure({
+  baseURL: '/api/cny',
+  token: 'token',
+  headers: {
+    'X-Tenant-Id': 'tenant-id'
+  }
+})
+```
+
+Image path example:
+
+- API base URL: `/api/cny`
+- Backend image path: `/cny/upload/a.png`
+- Expected browser image URL: `/api/cny/upload/a.png`
+
+Use:
+
+```js
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token'
+})
+```
+
+## Global Registration
+
+Register all public components globally:
+
+```js
+import {createApp} from 'vue'
+import ElementPlus from 'element-plus'
+import vueWiringDiagram, {configure} from 'vue3-wiring-diagram'
+import 'element-plus/dist/index.css'
+import 'vue3-wiring-diagram/style.css'
+import App from './App.vue'
+
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token'
+})
+
+const app = createApp(App)
+
+app.use(ElementPlus)
+app.use(vueWiringDiagram)
+app.mount('#app')
+```
+
+Then use component tags directly:
+
+```vue
+<wiring-diagram-editor :id="id" :item-id="itemId" locale="zh-CN" />
+<wiring-diagram-preview :id="id" locale="en-US" />
+```
+
+## On-Demand Import
+
+Import only the components needed by a page:
+
+```js
+import {
+  WiringDiagramEditor,
+  WiringDiagramPreview,
+  configure
+} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+```
+
+Short aliases are also exported:
+
+```js
+import {Editor, Preview} from 'vue3-wiring-diagram'
+```
+
+## Editor
+
+The editor loads an existing diagram by `id`, uses `itemId` to load device-related data, and emits diagram JSON through `getJson`.
+
+Props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | `''` | Template id. When empty, the editor starts with a blank diagram. |
+| `itemId` | `string` | `''` | Project/item id used by device list APIs. |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | UI language and request `Accept-Language`. |
+
+Events:
+
+| Event | Payload |
+| --- | --- |
+| `getJson` | `{ background, grid, data }` |
+
+On-demand example:
+
+```vue
+<template>
+  <div class="wiring-page">
+    <WiringDiagramEditor
+      :id="id"
+      :item-id="itemId"
+      locale="zh-CN"
+      @getJson="handleSave"
+    />
+  </div>
+</template>
+
+<script setup>
+import {ref, onMounted} from 'vue'
+import {WiringDiagramEditor, configure, updateData} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+
+const id = ref('195')
+const itemId = ref('1115')
+
+onMounted(() => {
+  configure({
+    baseURL: '/api/cny',
+    assetBaseURL: '/api',
+    token: 'token'
+  })
+})
+
+const handleSave = (diagram) => {
+  updateData(id.value, diagram)
+}
+</script>
+
+<style scoped>
+.wiring-page {
+  width: 100%;
+  height: 100%;
+}
+</style>
+```
+
+Global component example:
+
+```vue
+<wiring-diagram-editor
+  :id="id"
+  :item-id="itemId"
+  locale="zh-CN"
+  @getJson="handleSave"
+/>
+```
+
+## Preview
+
+The preview component can load data by `id`, or render diagram data passed from the page.
+
+Props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | `''` | Template id. When provided, preview loads diagram data through the configured API. |
+| `background` | `object` | `{}` | Diagram background config used when `id` is empty. |
+| `grid` | `object` | `{}` | Diagram grid config used when `id` is empty. |
+| `data` | `object` | `{}` | Diagram JSON used when `id` is empty. |
+| `type` | `string \| null` | `null` | Internal display type for nested preview. |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | UI language and request `Accept-Language`. |
+
+Events:
+
+| Event | Payload |
+| --- | --- |
+| `close` | none |
+
+Preview by template id:
+
+```vue
+<template>
+  <div class="wiring-page">
+    <WiringDiagramPreview :id="id" locale="en-US" />
+  </div>
+</template>
+
+<script setup>
+import {ref, onMounted} from 'vue'
+import {WiringDiagramPreview, configure} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+
+const id = ref('195')
+
+onMounted(() => {
+  configure({
+    baseURL: '/api/cny',
+    assetBaseURL: '/api',
+    token: 'token'
+  })
+})
+</script>
+```
+
+Preview by existing diagram JSON:
+
+```vue
+<template>
+  <WiringDiagramPreview
+    :background="diagram.background"
+    :grid="diagram.grid"
+    :data="diagram.data"
+    locale="zh-CN"
+  />
+</template>
+
+<script setup>
+import {ref} from 'vue'
+import {WiringDiagramPreview} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+
+const diagram = ref({
+  background: {},
+  grid: {},
+  data: {cells: []}
+})
+</script>
+```
+
+## Public Exports
+
+```js
+import {
+  Editor,
+  Preview,
+  WiringDiagramEditor,
+  WiringDiagramPreview,
+  configure,
+  setBaseURL,
+  setAssetBaseURL,
+  setToken,
+  getData,
+  updateData
+} from 'vue3-wiring-diagram'
+```
+
+## Locale
+
+Use `locale` to switch built-in text. It also updates the request `Accept-Language` header for component requests:
+
+```vue
+<wiring-diagram-editor locale="zh-CN" />
+<wiring-diagram-editor locale="en-US" />
+```
+
+Default locale is `zh-CN`.
+
+## Theme
+
+The plugin exposes CSS variables. Override them in the host page when needed:
+
+```css
+.wiring-page {
+  --wiring-bg: rgb(9 23 87 / 0.6);
+  --wiring-panel-bg: rgb(9 23 87 / 0.6);
+  --wiring-text-color: #ffffff;
+  --wiring-muted-text-color: #ffffff;
+  --wiring-border-color: rgb(9 23 87 / 0.6);
+  --wiring-primary-color: #2563eb;
+  --wiring-primary-soft-color: #2364dd4d;
+}
+```
+
+## Avoid Duplicate Vue
+
+Do not import from the source folder in the host application:
+
+```js
+// Do not do this
+import {WiringDiagramEditor} from '../../wiring-diagram/packages/index.js'
+```
+
+Always import from the package name:
+
+```js
+import {WiringDiagramEditor} from 'vue3-wiring-diagram'
+```
+
+If you see an error like `Cannot read properties of null (reading 'ce')` and the stack points to another package's `node_modules/@vue/runtime-core`, the host is loading two Vue runtimes. Clear the host cache and reinstall:
+
+```bash
+rm -rf node_modules/.vite node_modules/.cache node_modules/vue3-wiring-diagram
+npm install vue3-wiring-diagram
+```
+
+---
+
+<a id="中文文档"></a>
+
+# 中文文档
+
+基于 Vue 3、X6、Element Plus 的接线图组件库。
+
+[English](#vue3-wiring-diagram) | [API Specification](#api-specification) | [接口规范](#接口规范)
+
+## 功能
+
+- 提供编辑器和预览两个核心组件。
+- 内置中文和英文，支持 `zh-CN`、`en-US`。
+- 统一配置接口地址、token、自定义请求头、超时时间和图片资源前缀。
+- 组件 `locale` 同时控制界面文案和请求头 `Accept-Language`。
+- Element Plus 由宿主项目提供，宿主项目已有的 Element Plus 主题样式可以继续生效。
+
+## 环境要求
+
+宿主项目需要使用 Vue 3，并安装 Element Plus：
+
+```bash
+npm install vue element-plus @element-plus/icons-vue
+```
+
+## 安装
+
+```bash
+npm install vue3-wiring-diagram
+```
+
+## 宿主项目基础配置
+
+宿主项目先注册 Element Plus，再引入插件样式。
+
+```js
+import {createApp} from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import '@/styles/index.scss'
+
+import 'vue3-wiring-diagram/style.css'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(ElementPlus)
+app.mount('#app')
+```
+
+如果宿主项目是 Vite，建议加上 `dedupe`，避免加载两份 Vue：
+
+```js
+// vite.config.js
+export default {
+  resolve: {
+    dedupe: ['vue', 'element-plus', '@element-plus/icons-vue']
+  }
+}
+```
+
+## 请求配置
+
+组件渲染前调用 `configure`。`headers` 是可选项，只在后端需要额外请求头时使用，例如租户 id、应用 id 或自定义鉴权字段。如果后端不需要，可以不传。
+
+```js
+import {
+  configure,
+  setAssetBaseURL,
+  setBaseURL,
+  setToken
+} from 'vue3-wiring-diagram'
+
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token',
+  timeout: 10000
+})
+
+setBaseURL('/api/cny')
+setAssetBaseURL('/api')
+setToken('token')
+```
+
+可选自定义请求头：
+
+```js
+configure({
+  baseURL: '/api/cny',
+  token: 'token',
+  headers: {
+    'X-Tenant-Id': 'tenant-id'
+  }
+})
+```
+
+图片路径示例：
+
+- 接口地址前缀：`/api/cny`
+- 后端返回图片路径：`/cny/upload/a.png`
+- 浏览器实际图片请求：`/api/cny/upload/a.png`
+
+配置方式：
+
+```js
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token'
+})
+```
+
+## 全局引入
+
+一次性注册所有公开组件：
+
+```js
+import {createApp} from 'vue'
+import ElementPlus from 'element-plus'
+import vueWiringDiagram, {configure} from 'vue3-wiring-diagram'
+import 'element-plus/dist/index.css'
+import 'vue3-wiring-diagram/style.css'
+import App from './App.vue'
+
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token'
+})
+
+const app = createApp(App)
+
+app.use(ElementPlus)
+app.use(vueWiringDiagram)
+app.mount('#app')
+```
+
+注册后可以直接使用组件标签：
+
+```vue
+<wiring-diagram-editor :id="id" :item-id="itemId" locale="zh-CN" />
+<wiring-diagram-preview :id="id" locale="en-US" />
+```
+
+## 按需引入
+
+页面里只引入需要的组件：
+
+```js
+import {
+  WiringDiagramEditor,
+  WiringDiagramPreview,
+  configure
+} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+```
+
+也提供短别名：
+
+```js
+import {Editor, Preview} from 'vue3-wiring-diagram'
+```
+
+## 编辑器
+
+编辑器可通过 `id` 加载已有图纸，通过 `itemId` 加载设备相关数据，并通过 `getJson` 事件返回图纸 JSON。
+
+Props：
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | `''` | 模板 id。为空时打开空白画布。 |
+| `itemId` | `string` | `''` | 项目/站点 id，用于设备列表等接口。 |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | 组件语言，同时同步请求头 `Accept-Language`。 |
+
+事件：
+
+| 事件 | 参数 |
+| --- | --- |
+| `getJson` | `{ background, grid, data }` |
+
+按需引入示例：
+
+```vue
+<template>
+  <div class="wiring-page">
+    <WiringDiagramEditor
+      :id="id"
+      :item-id="itemId"
+      locale="zh-CN"
+      @getJson="handleSave"
+    />
+  </div>
+</template>
+
+<script setup>
+import {ref, onMounted} from 'vue'
+import {WiringDiagramEditor, configure, updateData} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+
+const id = ref('195')
+const itemId = ref('1115')
+
+onMounted(() => {
+  configure({
+    baseURL: '/api/cny',
+    assetBaseURL: '/api',
+    token: 'token'
+  })
+})
+
+const handleSave = (diagram) => {
+  updateData(id.value, diagram)
+}
+</script>
+
+<style scoped>
+.wiring-page {
+  width: 100%;
+  height: 100%;
+}
+</style>
+```
+
+全局组件示例：
+
+```vue
+<wiring-diagram-editor
+  :id="id"
+  :item-id="itemId"
+  locale="zh-CN"
+  @getJson="handleSave"
+/>
+```
+
+## 预览
+
+预览组件可以通过 `id` 加载数据，也可以直接渲染页面传入的图纸 JSON。
+
+Props：
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | `''` | 模板 id。传入后会通过配置的接口加载图纸数据。 |
+| `background` | `object` | `{}` | `id` 为空时使用的画布背景配置。 |
+| `grid` | `object` | `{}` | `id` 为空时使用的网格配置。 |
+| `data` | `object` | `{}` | `id` 为空时使用的图纸 JSON。 |
+| `type` | `string \| null` | `null` | 内部多层预览标识。 |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | 组件语言，同时同步请求头 `Accept-Language`。 |
+
+事件：
+
+| 事件 | 参数 |
+| --- | --- |
+| `close` | 无 |
+
+通过模板 id 预览：
+
+```vue
+<template>
+  <div class="wiring-page">
+    <WiringDiagramPreview :id="id" locale="en-US" />
+  </div>
+</template>
+
+<script setup>
+import {ref, onMounted} from 'vue'
+import {WiringDiagramPreview, configure} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+
+const id = ref('195')
+
+onMounted(() => {
+  configure({
+    baseURL: '/api/cny',
+    assetBaseURL: '/api',
+    token: 'token'
+  })
+})
+</script>
+```
+
+通过已有图纸 JSON 预览：
+
+```vue
+<template>
+  <WiringDiagramPreview
+    :background="diagram.background"
+    :grid="diagram.grid"
+    :data="diagram.data"
+    locale="zh-CN"
+  />
+</template>
+
+<script setup>
+import {ref} from 'vue'
+import {WiringDiagramPreview} from 'vue3-wiring-diagram'
+import 'vue3-wiring-diagram/style.css'
+
+const diagram = ref({
+  background: {},
+  grid: {},
+  data: {cells: []}
+})
+</script>
+```
+
+## 公开导出
+
+```js
+import {
+  Editor,
+  Preview,
+  WiringDiagramEditor,
+  WiringDiagramPreview,
+  configure,
+  setBaseURL,
+  setAssetBaseURL,
+  setToken,
+  getData,
+  updateData
+} from 'vue3-wiring-diagram'
+```
+
+## 中英文
+
+通过 `locale` 切换组件内置文本，同时会同步组件请求头里的 `Accept-Language`：
+
+```vue
+<wiring-diagram-editor locale="zh-CN" />
+<wiring-diagram-editor locale="en-US" />
+```
+
+默认是 `zh-CN`。
+
+## 样式
+
+插件暴露 CSS 变量，宿主页面可以按需覆盖：
+
+```css
+.wiring-page {
+  --wiring-bg: rgb(9 23 87 / 0.6);
+  --wiring-panel-bg: rgb(9 23 87 / 0.6);
+  --wiring-text-color: #ffffff;
+  --wiring-muted-text-color: #ffffff;
+  --wiring-border-color: rgb(9 23 87 / 0.6);
+  --wiring-primary-color: #2563eb;
+  --wiring-primary-soft-color: #2364dd4d;
+}
+```
+
+如果宿主项目已有 Element Plus 全局样式，可以继续保留。插件样式只处理接线图内部布局和少量必要样式。
+
+## 避免重复 Vue
+
+宿主项目不要直接从插件源码目录引入：
+
+```js
+// 不要这样写
+import {WiringDiagramEditor} from '../../wiring-diagram/packages/index.js'
+```
+
+应该从包名引入：
+
+```js
+import {WiringDiagramEditor} from 'vue3-wiring-diagram'
+```
+
+如果出现下面的错误：
+
+```text
+Cannot read properties of null (reading 'ce')
+```
+
+并且堆栈里出现其他包下面的：
+
+```text
+node_modules/@vue/runtime-core
+```
+
+说明宿主项目加载了两份 Vue。清理宿主项目缓存后重新安装：
+
+```bash
+rm -rf node_modules/.vite node_modules/.cache node_modules/vue3-wiring-diagram
+npm install vue3-wiring-diagram
+```
+
+---
+
+# API Specification
+
+This document describes the backend APIs used by `vue3-wiring-diagram`. A host application can integrate the editor and preview components by implementing the following endpoints, request parameters, and response structures.
+
+[中文接口规范](./API.zh-CN.md)
+
+## Base Rules
+
+All requests are based on `configure({ baseURL })`. Example:
+
+```js
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token'
+})
+```
+
+When the component requests `/template/selectOne`, the actual browser request is:
+
+```text
+/api/cny/template/selectOne
+```
+
+## Request Headers
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `token` | `string` | No | Set by `configure({ token })` or `setToken(token)`. The plugin writes it to the `token` request header. |
+| `Accept-Language` | `zh-CN \| en-US` | No | Set automatically from component `locale`. `locale="zh-CN"` sends `zh-CN`; `locale="en-US"` sends `en-US`. |
+| Custom headers | `string` | No | Passed through by `configure({ headers })`, such as tenant id, app id, organization id, or custom auth fields. The plugin does not require them. |
+
+## Standard Response
+
+All JSON APIs should return:
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {}
+}
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `code` | `number` | Yes | Business status code. The plugin treats `code === 200` as success. |
+| `msg` | `string` | No | Message used for failure prompts. |
+| `data` | `any` | No | Business data. Each endpoint defines its own `data` structure. |
+
+APIs must return JSON, not HTML. HTML responses are treated as invalid API responses.
+
+## 1. Get Diagram Detail
+
+Used by the editor to load an existing diagram and by preview to render by `id`.
+
+```text
+GET /template/selectOne
+```
+
+### Request Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | Yes | Diagram template id, matching the component `id` prop. |
+
+### Response `data`
+
+```json
+{
+  "id": 195,
+  "remark": "{\"background\":{},\"grid\":{},\"data\":{\"cells\":[]}}"
+}
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | No | Diagram template id. The plugin does not depend on it. |
+| `remark` | `string` | Yes | Diagram JSON string. It must be `JSON.stringify({ background, grid, data })`. |
+
+### Parsed `remark`
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `background` | `object` | Yes | X6 graph background configuration. |
+| `grid` | `object` | Yes | X6 graph grid configuration. |
+| `data` | `object` | Yes | X6 diagram data, usually containing `cells`. |
+| `data.cells` | `array` | Yes | X6 node and edge list. |
+
+## 2. Save Diagram
+
+Used by the editor to save diagram data.
+
+```text
+POST /template/insert
+```
+
+### Request Body
+
+```json
+{
+  "id": "195",
+  "remark": "{\"background\":{},\"grid\":{},\"data\":{\"cells\":[]}}"
+}
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | Yes | Diagram template id. |
+| `remark` | `string` | Yes | Diagram JSON string. The plugin sends `JSON.stringify({ background, grid, data })`. |
+
+### Response `data`
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `data` | `any` | No | The plugin only checks `code === 200`; it does not depend on this data. |
+
+## 3. Get Device List
+
+Used by text, image, pipe, and arrow controls to bind devices.
+
+```text
+GET /custom/deviceList
+```
+
+### Request Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `itemIds` | `string \| number` | Yes | Project/site id, matching the editor `itemId` prop. |
+
+### Response `data`
+
+```json
+[
+  {
+    "deviceName": "Device Name",
+    "deviceCode": "device-code"
+  }
+]
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `deviceName` | `string` | Yes | Device name shown in select options. |
+| `deviceCode` | `string` | Yes | Device code used to query fields and save bindings. |
+
+## 4. Get Device Field List
+
+Used by text, image, pipe, and arrow controls to select monitoring fields.
+
+```text
+GET /custom/monitorInfo
+```
+
+### Request Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `deviceCode` | `string` | Yes | Device code from `/custom/deviceList`. |
+| `fieldType` | `number` | Yes | Field type. The plugin always sends `1`. |
+
+### Response `data`
+
+```json
+[
+  {
+    "name": "Voltage",
+    "dataField": "voltage",
+    "unit": "V"
+  }
+]
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | Yes | Field name shown in select options and text bindings. |
+| `dataField` | `string` | Yes | Field code saved to diagram node `fields[].field`. |
+| `unit` | `string` | No | Unit used in text binding prompts. |
+
+## 5. Get DI Field List
+
+Used by pipe dynamic flow settings.
+
+```text
+GET /template/getDiField
+```
+
+### Request Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `itemIds` | `string \| number` | Yes | Project/site id, matching the editor `itemId` prop. |
+
+### Response `data`
+
+```json
+[
+  {
+    "deviceCode": "device-code",
+    "field": "status",
+    "deviceName": "Device Name",
+    "name": "Running Status"
+  }
+]
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `deviceCode` | `string` | Yes | Device code. The plugin combines it with `field` as an internal unique id. |
+| `field` | `string` | Yes | Field code. |
+| `deviceName` | `string` | No | Device name. |
+| `name` | `string` | No | Field name. |
+
+## 6. Get Real-Time Data
+
+Used by preview to refresh text, pipe, arrow, and image status. The plugin sends batches of up to 5 cells.
+
+```text
+POST /custom/arrRealData2
+```
+
+### Request Body
+
+```json
+[
+  {
+    "id": "x6-cell-id",
+    "fields": [
+      {
+        "index": 0,
+        "deviceName": "Device Name",
+        "deviceCode": "device-code",
+        "field": "voltage"
+      }
+    ]
+  }
+]
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | X6 node or edge id. Return it unchanged so the plugin can locate the cell to update. |
+| `fields` | `array` | Yes | Bound field list for this cell. |
+| `fields[].index` | `number` | Yes | Field index. Text templates match this index by `${}` order. |
+| `fields[].deviceName` | `string` | No | Device name. |
+| `fields[].deviceCode` | `string` | Yes | Device code. |
+| `fields[].field` | `string` | Yes | Field code. |
+
+### Response `data`
+
+```json
+[
+  {
+    "id": "x6-cell-id",
+    "fields": [
+      {
+        "index": 0,
+        "field": "voltage",
+        "value": 220,
+        "valueName": "220V"
+      }
+    ]
+  }
+]
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | X6 node or edge id. Must match the request `id`. |
+| `fields` | `array` | Yes | Real-time field values. |
+| `fields[].index` | `number` | Yes | Field index used by text replacement. |
+| `fields[].field` | `string` | No | Field code. |
+| `fields[].value` | `string \| number \| boolean` | Yes | Raw value used by pipe, arrow, and image condition checks. |
+| `fields[].valueName` | `string` | No | Display value. Text components prefer this value for `${}` replacement. |
+
+## 7. Get Image Groups and Images
+
+Used by the left stencil, image management, and image condition replacement.
+
+```text
+GET /custom/groupList
+```
+
+### Request Parameters
+
+None.
+
+### Response `data`
+
+`data` can be an array directly, or a paged object containing `records`, `list`, `items`, or `rows`.
+
+```json
+[
+  {
+    "id": 1,
+    "groupName": "Meter",
+    "sort": 1,
+    "isShow": 1,
+    "pictureList": [
+      {
+        "id": 10,
+        "groupId": 1,
+        "imageName": "Meter",
+        "imageUrl": "/cny/upload/meter.png",
+        "sort": 1,
+        "isShow": 1
+      }
+    ]
+  }
+]
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | Yes | Image group id. |
+| `groupName` | `string` | Yes | Image group name used as the left stencil group title. |
+| `sort` | `number` | No | Sort value. |
+| `isShow` | `number` | No | Visibility flag. Recommended: `1` visible, `0` hidden. |
+| `pictureList` | `array` | Yes | Image list under this group. |
+| `pictureList[].id` | `string \| number` | Yes | Image id. |
+| `pictureList[].groupId` | `string \| number` | Yes | Parent group id. |
+| `pictureList[].imageName` | `string` | Yes | Image name. |
+| `pictureList[].imageUrl` | `string` | Yes | Image URL. It can be an absolute URL or a relative path, such as `/cny/upload/meter.png`. |
+| `pictureList[].sort` | `number` | No | Image sort value. |
+| `pictureList[].isShow` | `number` | No | Visibility flag. Recommended: `1` visible, `0` hidden. |
+
+## 8. Create Image Group
+
+```text
+POST /custom/saveGroup
+```
+
+### Request Body
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `groupName` | `string` | Yes | Group name. Recommended length: 1 to 20 characters. |
+| `sort` | `number` | Yes | Sort value. |
+| `isShow` | `number` | Yes | Visibility flag. `1` visible, `0` hidden. |
+
+### Response `data`
+
+The plugin only checks `code === 200`; it does not depend on this data.
+
+## 9. Update Image Group
+
+```text
+POST /custom/updateGroup
+```
+
+### Request Body
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | Yes | Group id. |
+| `groupName` | `string` | Yes | Group name. Recommended length: 1 to 20 characters. |
+| `sort` | `number` | Yes | Sort value. |
+| `isShow` | `number` | Yes | Visibility flag. `1` visible, `0` hidden. |
+
+### Response `data`
+
+The plugin only checks `code === 200`; it does not depend on this data.
+
+## 10. Delete Image Group
+
+```text
+GET /custom/removeGroup/{id}
+```
+
+### Path Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | Yes | Image group id to delete. |
+
+### Response `data`
+
+The plugin only checks `code === 200`; it does not depend on this data.
+
+## 11. Upload Image File
+
+```text
+POST /file/fileUpload
+Content-Type: multipart/form-data
+```
+
+### Request Body
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `file` | `File` | Yes | Image file. The plugin validates that the MIME type contains `image`. |
+
+### Response `data`
+
+```json
+"/cny/upload/meter.png"
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `data` | `string` | Yes | Uploaded image URL. It is submitted as `imageUrl` when saving an image. |
+
+## 12. Create or Update Image
+
+```text
+POST /custom/savePicture
+```
+
+### Request Body
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | No | Image id. Empty for create; existing id for edit. |
+| `groupId` | `string \| number` | Yes | Parent image group id. |
+| `imageName` | `string` | Yes | Image name. Recommended length: 1 to 20 characters. |
+| `imageUrl` | `string` | Yes | Image URL, usually from `/file/fileUpload` response `data`. |
+| `sort` | `number` | Yes | Sort value. |
+| `isShow` | `number` | Yes | Visibility flag. `1` visible, `0` hidden. |
+
+### Response `data`
+
+The plugin only checks `code === 200`; it does not depend on this data.
+
+## 13. Delete Image
+
+```text
+GET /custom/removePicture/{id}
+```
+
+### Path Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | Yes | Image id to delete. |
+
+### Response `data`
+
+The plugin only checks `code === 200`; it does not depend on this data.
+
+## 14. Get Template List
+
+Used by image node jump-source selection.
+
+```text
+GET /template/listPage
+```
+
+### Request Parameters
+
+The plugin always sends:
+
+```json
+{
+  "pageNum": 1,
+  "pageSize": 9999
+}
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `pageNum` | `number` | Yes | Page number. The plugin always sends `1`. |
+| `pageSize` | `number` | Yes | Page size. The plugin always sends `9999`. |
+
+### Response `data`
+
+```json
+{
+  "records": [
+    {
+      "id": 195,
+      "name": "Main Diagram"
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `records` | `array` | Yes | Template list. |
+| `records[].id` | `string \| number` | Yes | Template id. |
+| `records[].name` | `string` | Yes | Template name shown in select options. |
+
+---
+
+# 接口规范
+
+本文档描述 `vue3-wiring-diagram` 组件运行时用到的后端接口。宿主项目只要按以下路径、入参和返回结构实现接口，即可接入编辑器和预览组件。
+
+## 基础约定
+
+所有接口都基于 `configure({ baseURL })` 配置的地址发起请求。例如：
+
+```js
+configure({
+  baseURL: '/api/cny',
+  assetBaseURL: '/api',
+  token: 'token'
+})
+```
+
+组件内部请求 `/template/selectOne` 时，浏览器实际请求地址为：
+
+```text
+/api/cny/template/selectOne
+```
+
+## 请求头
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `token` | `string` | 否 | 通过 `configure({ token })` 或 `setToken(token)` 设置。插件会写入请求头 `token`。 |
+| `Accept-Language` | `zh-CN \| en-US` | 否 | 由组件 `locale` 自动设置。`locale="zh-CN"` 时传 `zh-CN`，`locale="en-US"` 时传 `en-US`。 |
+| 自定义请求头 | `string` | 否 | 通过 `configure({ headers })` 透传给后端。例如租户 id、应用 id、组织 id 等。插件不强制要求。 |
+
+## 统一响应结构
+
+所有 JSON 接口建议返回以下结构：
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {}
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `code` | `number` | 是 | 状态码。插件内部以 `code === 200` 判断业务成功。 |
+| `msg` | `string` | 否 | 提示信息。失败时会用于页面提示。 |
+| `data` | `any` | 否 | 业务数据。不同接口结构不同，详见下文。 |
+
+注意：接口必须返回 JSON，不能返回 HTML。否则插件会认为响应格式错误。
+
+## 1. 获取图纸详情
+
+用于编辑器加载已有图纸，也用于预览组件按 `id` 预览。
+
+```text
+GET /template/selectOne
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 是 | 图纸模板 id，对应组件传入的 `id`。 |
+
+### 返回 `data`
+
+```json
+{
+  "id": 195,
+  "remark": "{\"background\":{},\"grid\":{},\"data\":{\"cells\":[]}}"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 否 | 图纸模板 id。插件不强依赖该字段。 |
+| `remark` | `string` | 是 | 图纸 JSON 字符串。必须是 `JSON.stringify({ background, grid, data })` 后的字符串。 |
+
+### `remark` 解析后的结构
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `background` | `object` | 是 | X6 画布背景配置。 |
+| `grid` | `object` | 是 | X6 网格配置。 |
+| `data` | `object` | 是 | X6 图纸数据，通常包含 `cells`。 |
+| `data.cells` | `array` | 是 | X6 节点和连线数组。 |
+
+## 2. 保存图纸
+
+用于编辑器保存图纸。
+
+```text
+POST /template/insert
+```
+
+### 入参
+
+```json
+{
+  "id": "195",
+  "remark": "{\"background\":{},\"grid\":{},\"data\":{\"cells\":[]}}"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 是 | 图纸模板 id。 |
+| `remark` | `string` | 是 | 图纸 JSON 字符串。插件会把 `{ background, grid, data }` 使用 `JSON.stringify` 后传给后端。 |
+
+### 返回 `data`
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `any` | 否 | 插件只判断 `code === 200`，不依赖具体返回数据。 |
+
+## 3. 获取设备列表
+
+用于文本、图片、管道、箭头等组件绑定设备。
+
+```text
+GET /custom/deviceList
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `itemIds` | `string \| number` | 是 | 项目/站点 id，对应编辑器组件传入的 `itemId`。 |
+
+### 返回 `data`
+
+```json
+[
+  {
+    "deviceName": "设备名称",
+    "deviceCode": "device-code"
+  }
+]
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `deviceName` | `string` | 是 | 设备名称，用于下拉框展示。 |
+| `deviceCode` | `string` | 是 | 设备编码，用于查询字段列表和保存绑定关系。 |
+
+## 4. 获取设备字段列表
+
+用于文本、图片、管道、箭头等组件选择监测字段。
+
+```text
+GET /custom/monitorInfo
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `deviceCode` | `string` | 是 | 设备编码，来自 `/custom/deviceList` 的 `deviceCode`。 |
+| `fieldType` | `number` | 是 | 字段类型。插件固定传 `1`。 |
+
+### 返回 `data`
+
+```json
+[
+  {
+    "name": "电压",
+    "dataField": "voltage",
+    "unit": "V"
+  }
+]
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `name` | `string` | 是 | 字段名称，用于下拉框展示和文本模板绑定。 |
+| `dataField` | `string` | 是 | 字段编码，会保存到图纸节点的 `fields[].field` 中。 |
+| `unit` | `string` | 否 | 单位。文本绑定时用于展示提示。 |
+
+## 5. 获取 DI 字段列表
+
+用于管道动态流向相关字段选择。
+
+```text
+GET /template/getDiField
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `itemIds` | `string \| number` | 是 | 项目/站点 id，对应编辑器组件传入的 `itemId`。 |
+
+### 返回 `data`
+
+```json
+[
+  {
+    "deviceCode": "device-code",
+    "field": "status",
+    "deviceName": "设备名称",
+    "name": "运行状态"
+  }
+]
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `deviceCode` | `string` | 是 | 设备编码。插件会和 `field` 拼成内部唯一 id。 |
+| `field` | `string` | 是 | 字段编码。 |
+| `deviceName` | `string` | 否 | 设备名称。 |
+| `name` | `string` | 否 | 字段名称。 |
+
+## 6. 获取实时数据
+
+用于预览组件刷新文本、管道、箭头和图片的实时状态。插件会按批次调用，每批最多 5 个节点。
+
+```text
+POST /custom/arrRealData2
+```
+
+### 入参
+
+```json
+[
+  {
+    "id": "x6-cell-id",
+    "fields": [
+      {
+        "index": 0,
+        "deviceName": "设备名称",
+        "deviceCode": "device-code",
+        "field": "voltage"
+      }
+    ]
+  }
+]
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | 是 | X6 节点或连线 id。后端需要原样返回，用于插件定位要更新的图元。 |
+| `fields` | `array` | 是 | 该图元绑定的字段列表。 |
+| `fields[].index` | `number` | 是 | 字段索引。文本模板中会按 `${}` 出现顺序匹配。 |
+| `fields[].deviceName` | `string` | 否 | 设备名称。 |
+| `fields[].deviceCode` | `string` | 是 | 设备编码。 |
+| `fields[].field` | `string` | 是 | 字段编码。 |
+
+### 返回 `data`
+
+```json
+[
+  {
+    "id": "x6-cell-id",
+    "fields": [
+      {
+        "index": 0,
+        "field": "voltage",
+        "value": 220,
+        "valueName": "220V"
+      }
+    ]
+  }
+]
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | 是 | X6 节点或连线 id，必须和入参中的 `id` 一致。 |
+| `fields` | `array` | 是 | 字段实时值列表。 |
+| `fields[].index` | `number` | 是 | 字段索引。文本替换时按该字段匹配。 |
+| `fields[].field` | `string` | 否 | 字段编码。 |
+| `fields[].value` | `string \| number \| boolean` | 是 | 原始值。管道、箭头、图片条件判断会使用该值。 |
+| `fields[].valueName` | `string` | 否 | 展示值。文本组件会优先使用该字段替换 `${}`。 |
+
+## 7. 获取图片分组和图片列表
+
+用于左侧元件库、图片管理、图片条件替换。
+
+```text
+GET /custom/groupList
+```
+
+### 入参
+
+无。
+
+### 返回 `data`
+
+`data` 可以直接是数组，也可以是分页对象中的 `records`、`list`、`items` 或 `rows`。
+
+```json
+[
+  {
+    "id": 1,
+    "groupName": "电表",
+    "sort": 1,
+    "isShow": 1,
+    "pictureList": [
+      {
+        "id": 10,
+        "groupId": 1,
+        "imageName": "电表",
+        "imageUrl": "/cny/upload/meter.png",
+        "sort": 1,
+        "isShow": 1
+      }
+    ]
+  }
+]
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 是 | 图片分组 id。 |
+| `groupName` | `string` | 是 | 图片分组名称，用于左侧分组标题。 |
+| `sort` | `number` | 否 | 排序值。 |
+| `isShow` | `number` | 否 | 是否显示。建议 `1` 表示显示，`0` 表示隐藏。 |
+| `pictureList` | `array` | 是 | 分组下的图片列表。 |
+| `pictureList[].id` | `string \| number` | 是 | 图片 id。 |
+| `pictureList[].groupId` | `string \| number` | 是 | 所属分组 id。 |
+| `pictureList[].imageName` | `string` | 是 | 图片名称。 |
+| `pictureList[].imageUrl` | `string` | 是 | 图片地址。可以是完整 URL，也可以是相对路径，例如 `/cny/upload/meter.png`。 |
+| `pictureList[].sort` | `number` | 否 | 图片排序值。 |
+| `pictureList[].isShow` | `number` | 否 | 是否显示。建议 `1` 表示显示，`0` 表示隐藏。 |
+
+## 8. 新增图片分组
+
+```text
+POST /custom/saveGroup
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `groupName` | `string` | 是 | 分组名称，长度建议 1 到 20 个字符。 |
+| `sort` | `number` | 是 | 排序值。 |
+| `isShow` | `number` | 是 | 是否显示。`1` 表示显示，`0` 表示隐藏。 |
+
+### 返回 `data`
+
+插件只判断 `code === 200`，不依赖具体返回数据。
+
+## 9. 更新图片分组
+
+```text
+POST /custom/updateGroup
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 是 | 分组 id。 |
+| `groupName` | `string` | 是 | 分组名称，长度建议 1 到 20 个字符。 |
+| `sort` | `number` | 是 | 排序值。 |
+| `isShow` | `number` | 是 | 是否显示。`1` 表示显示，`0` 表示隐藏。 |
+
+### 返回 `data`
+
+插件只判断 `code === 200`，不依赖具体返回数据。
+
+## 10. 删除图片分组
+
+```text
+GET /custom/removeGroup/{id}
+```
+
+### 路径参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 是 | 要删除的图片分组 id。 |
+
+### 返回 `data`
+
+插件只判断 `code === 200`，不依赖具体返回数据。
+
+## 11. 上传图片文件
+
+```text
+POST /file/fileUpload
+Content-Type: multipart/form-data
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `file` | `File` | 是 | 图片文件。插件会校验文件 MIME 类型包含 `image`。 |
+
+### 返回 `data`
+
+```json
+"/cny/upload/meter.png"
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `string` | 是 | 上传后的图片地址。保存图片时会作为 `imageUrl` 提交。 |
+
+## 12. 新增或更新图片
+
+```text
+POST /custom/savePicture
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 否 | 图片 id。新增时可为空，编辑时传原图片 id。 |
+| `groupId` | `string \| number` | 是 | 所属图片分组 id。 |
+| `imageName` | `string` | 是 | 图片名称，长度建议 1 到 20 个字符。 |
+| `imageUrl` | `string` | 是 | 图片地址，通常来自 `/file/fileUpload` 返回的 `data`。 |
+| `sort` | `number` | 是 | 排序值。 |
+| `isShow` | `number` | 是 | 是否显示。`1` 表示显示，`0` 表示隐藏。 |
+
+### 返回 `data`
+
+插件只判断 `code === 200`，不依赖具体返回数据。
+
+## 13. 删除图片
+
+```text
+GET /custom/removePicture/{id}
+```
+
+### 路径参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string \| number` | 是 | 要删除的图片 id。 |
+
+### 返回 `data`
+
+插件只判断 `code === 200`，不依赖具体返回数据。
+
+## 14. 获取模板列表
+
+用于图片节点的跳转图源选择。
+
+```text
+GET /template/listPage
+```
+
+### 入参
+
+插件固定传：
+
+```json
+{
+  "pageNum": 1,
+  "pageSize": 9999
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `pageNum` | `number` | 是 | 页码。插件固定传 `1`。 |
+| `pageSize` | `number` | 是 | 每页数量。插件固定传 `9999`。 |
+
+### 返回 `data`
+
+```json
+{
+  "records": [
+    {
+      "id": 195,
+      "name": "主接线图"
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `records` | `array` | 是 | 模板列表。 |
+| `records[].id` | `string \| number` | 是 | 模板 id。 |
+| `records[].name` | `string` | 是 | 模板名称，用于下拉框展示。 |