vue3-wiring-diagram

vue3-wiring-diagram

基于 Vue 3、X6 3.x、Element Plus 的工业画面组件库。

English

接口规范 | API Specification

功能

• 提供编辑器和预览两个核心组件。
• 内置中文和英文，支持 zh-CN、en-US。
• 统一配置接口地址、token、自定义请求头、超时时间和图片资源前缀。
• 组件 locale 同时控制界面文案和请求头 Accept-Language。
• Element Plus 由宿主项目提供，宿主项目已有的 Element Plus 主题样式可以继续生效。

环境要求

宿主项目需要使用 Node.js 20 及以上、Vue 3，并安装 Element Plus：

npm install vue element-plus @element-plus/icons-vue

安装

npm install vue3-wiring-diagram

宿主项目基础配置

宿主项目先注册 Element Plus，再引入插件样式。

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：

// vite.config.js
export default {
  resolve: {
    dedupe: ['vue', 'element-plus', '@element-plus/icons-vue']
  }
}

请求配置

组件渲染前调用 configure。headers 是可选项，只在后端需要额外请求头时使用，例如租户 id、应用 id 或自定义鉴权字段。如果后端不需要，可以不传。

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')

可选自定义请求头：

configure({
  baseURL: '/api/cny',
  token: 'token',
  headers: {
    'X-Tenant-Id': 'tenant-id'
  }
})

图片路径示例：

• 接口地址前缀：/api/cny
• 后端返回图片路径：/cny/upload/a.png
• 浏览器实际图片请求：/api/cny/upload/a.png

配置方式：

configure({
  baseURL: '/api/cny',
  assetBaseURL: '/api',
  token: 'token'
})

全局引入

一次性注册所有公开组件：

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')

注册后可以直接使用组件标签：

<wiring-diagram-editor :id="id" :item-id="itemId" locale="zh-CN" />
<wiring-diagram-preview :id="id" locale="en-US" />

按需引入

页面里只引入需要的组件：

import {
  WiringDiagramEditor,
  WiringDiagramPreview,
  configure
} from 'vue3-wiring-diagram'
import 'vue3-wiring-diagram/style.css'

也提供短别名：

import {Editor, Preview} from 'vue3-wiring-diagram'

编辑器

编辑器可通过 id 加载已有图纸，通过 itemId 加载设备相关数据，并通过 getJson 事件返回图纸 JSON。

Props：

事件：

工具栏会显示“未保存、保存中、已保存、保存失败”。宿主按照下方示例调用导出的 updateData(id, diagram) 后，组件会自动同步真实接口状态；保存过程中产生的新修改不会被误标记为已保存。

存在未保存内容、正在保存或保存失败时，刷新和关闭浏览器会触发浏览器原生离开确认框。受浏览器安全规则限制，确认框文字不能自定义。

按需引入示例：

<template>
  <div class="wiring-page">
    <WiringDiagramEditor
      :id="id"
      :item-id="itemId"
      locale="zh-CN"
      @getJson="handleSave"
      @back="handleBack"
    />
  </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 = async (diagram) => {
  const saved = await updateData(id.value, diagram)
  if (!saved) return
}

const handleBack = () => {
  history.back()
}
</script>

<style scoped>
.wiring-page {
  width: 100%;
  height: 100%;
}
</style>

全局组件示例：

<wiring-diagram-editor
  :id="id"
  :item-id="itemId"
  locale="zh-CN"
  @getJson="handleSave"
/>

预览

预览组件可以通过 id 加载数据，也可以直接渲染页面传入的图纸 JSON。

Props：

事件：

通过模板 id 预览：

<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 预览：

<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>

公开导出

import {
  Editor,
  Preview,
  WiringDiagramEditor,
  WiringDiagramPreview,
  configure,
  setBaseURL,
  setAssetBaseURL,
  setToken,
  getData,
  updateData
} from 'vue3-wiring-diagram'

中英文

通过 locale 切换组件内置文本，同时会同步组件请求头里的 Accept-Language：

<wiring-diagram-editor locale="zh-CN" />
<wiring-diagram-editor locale="en-US" />

默认是 zh-CN。

数据联动规则稳定性

图片和线段规则可以配置“持续满足”和“恢复延迟”，单位为秒，范围 0 至 3600，默认均为 0。同一规则持续命中时不会重复替换图片或重启线段动画；实时值为 null 或字段缺失时不会累计计时，并保留当前效果。

样式

插件暴露 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

宿主项目不要直接从插件源码目录引入：

// 不要这样写
import {WiringDiagramEditor} from '../../wiring-diagram/packages/index.js'

应该从包名引入：

import {WiringDiagramEditor} from 'vue3-wiring-diagram'

如果出现下面的错误：

Cannot read properties of null (reading 'ce')

并且堆栈里出现其他包下面的：

node_modules/@vue/runtime-core

说明宿主项目加载了两份 Vue。清理宿主项目缓存后重新安装：

rm -rf node_modules/.vite node_modules/.cache node_modules/vue3-wiring-diagram
npm install vue3-wiring-diagram