@syhr/sy-graph

一个基于 Meta2D 的平面图形配置工具 Vue 3 组件库。

特性

• 🎨 基于 Meta2D 的强大图形编辑能力
• 🔧 支持多种图形类型和图表
• 📱 响应式设计，支持移动端
• 🎯 完整的 TypeScript 支持
• 📦 多种模块格式支持（ES、UMD、CommonJS）
• 🔌 Vue 3 插件化架构
• 🛡️ 安全的全局属性处理，避免变量冲突
• 🔄 实时数据更新和 WebSocket 支持
• 🎛️ 可定制的错误处理和回调机制
• 🚀 高性能渲染和批量更新
• 🎨 多层级显示控制
• 📡 支持自定义 API 和事件总线注入

安装

npm install @syhr/sy-graph

Peer Dependencies

确保你的项目已安装以下 peer dependencies：

# 必需依赖
npm install vue@^3.0.0 element-plus@^2.0.0 @meta2d/core@^1.0.0 @meta2d/svg@^1.0.0 @meta2d/utils@^1.0.0 lodash-es@^4.17.0

# 可选依赖（根据需要安装）
npm install pinia@^2.0.0 vue-router@^4.0.0

使用

全局注册（推荐）

import { createApp } from 'vue';
import SyGraph from '@syhr/sy-graph';
import '@syhr/sy-graph/style';

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

局部使用

import { SyGraph } from '@syhr/sy-graph';

export default {
  components: {
    SyGraph,
  },
};

在模板中使用

<template>
  <div>
    <SyGraph
      ref="graphRef"
      :url="graphUrl"
      :local="false"
      :show-map="true"
      :config="graphConfig"
      @loaded="handleLoaded"
      @error="handleError"
      @custom-msg="handleCustomMsg"
      @socket-msg="handleSocketMsg"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { SyGraph } from '@syhr/sy-graph';
const graphRef = ref();
const graphUrl = ref('path/to/your/graph.json');

// 自定义配置
const graphConfig = ref({
  socketUrl: 'ws://localhost:8080',
  stationIdKey: 'STATION_ID',
  userTokenKey: 'USER_TOKEN',
  messageDelay: 200,
  debounceDelay: 100,
  enableAutoFit: true,
  enableWebSocket: true,
});

const handleLoaded = (stage) => {
  console.log('Graph loaded:', stage);
  // 可以通过 stage 进行图纸操作
};

const handleError = (errorInfo) => {
  console.error('Graph error:', errorInfo);
};

const handleCustomMsg = (msg) => {
  console.log('Custom message:', msg);
};

const handleSocketMsg = (msg) => {
  console.log('Socket message:', msg);
};

// 组件方法调用示例
const toggleLevel = () => {
  graphRef.value?.changeVisibleByLevel(3, false);
};

const batchUpdate = (dataList) => {
  graphRef.value?.batchUpdatePen(dataList);
};
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | | --------------- | ------- | -------------- | -------------------- | | url | String | '' | 图纸数据 URL | | gid | String | '' | 图纸 ID | | data | Object | null | 直接传入的图纸数据 | | local | Boolean | false | 是否为本地数据 | | config | Object | 默认配置对象 | WebSocket 和其他配置 | | showMap | Boolean | false | 是否显示地图 | | isFactory | Boolean | false | 是否为工厂模式 | | apiInstance | Object | 内置 Api | 自定义 API 实例 | | mittInstance | Object | 内置 mitt | 自定义事件总线实例 | | customCallbacks | Object | {} | 自定义回调函数集合 | | errorHandler | Object | 默认错误处理器 | 错误处理配置 | | devConfig | Object | 默认配置对象 | 打包后开发环境配置 |

Events

| 事件名 | 说明 | 参数 | | ---------- | -------------- | ----------------------- | | error | 错误事件 | errorInfo: 错误信息对象 | | loaded | 图纸加载完成 | stage: Meta2D 实例 | | custom-msg | 自定义消息事件 | msg: 消息对象 | | socket-msg | WebSocket 消息 | msg: WebSocket 消息 |

方法

通过 ref 获取组件实例后可调用以下方法：

• setValue(pen, render = true) - 设置图元属性
• getStage() - 获取 Meta2D 实例
• getAllPens() - 获取所有图元
• getCustomPenType() - 获取所有图元类型
• batchUpdatePen(dataList) - 批量更新图元
• handleLineCross() - 处理线条交叉
• changeVisibleByLevel(level, isStrict = false) - 切换显示层级

TypeScript 支持

本包提供完整的 TypeScript 类型声明：

import { ref } from 'vue';
import type {
  SyGraphProps,
  SyGraphInstance,
  GraphConfig,
  CustomCallbacks,
  ErrorHandler,
  DataItem,
} from '@syhr/sy-graph';

// 组件 ref 类型
const graphRef = ref<SyGraphInstance>();

// Props 类型
const props: SyGraphProps = {
  url: 'path/to/graph.json',
  showMap: true,
  config: {
    socketUrl: 'ws://localhost:8080',
    enableAutoFit: true,
    enableWebSocket: true,
  } as GraphConfig,
  customCallbacks: {
    onStageLoaded: (stage) => console.log('Stage loaded:', stage),
    onBatchUpdate: (dataList: DataItem[]) => console.log('Batch update:', dataList),
  } as CustomCallbacks,
  errorHandler: {
    showMessage: true,
    callback: (errorInfo) => console.error('Custom error handler:', errorInfo),
  } as ErrorHandler,
};

// 方法调用示例
const toggleLevel = (level: number, isStrict: boolean = false) => {
  graphRef.value?.changeVisibleByLevel(level, isStrict);
};

const updateData = (dataList: DataItem[]) => {
  graphRef.value?.batchUpdatePen(dataList);
};

配置选项详解

GraphConfig 配置

const config = {
  socketUrl: 'ws://localhost:8080', // WebSocket服务器地址
  stationIdKey: 'STATION_ID', // 站点ID存储键名
  userTokenKey: 'USER_TOKEN', // 用户令牌存储键名
  messageDelay: 200, // 消息处理延迟（毫秒）
  debounceDelay: 100, // 防抖延迟（毫秒）
  enableAutoFit: true, // 是否自动适应视图
  enableWebSocket: true, // 是否启用WebSocket
  graphSocket: 'graph:socket', // 图纸Socket事件名
};

CustomCallbacks 回调

const callbacks = {
  onWebSocketMessage: (message) => {
    // 处理WebSocket消息
  },
  onCustomMessage: (msg) => {
    // 处理自定义消息
  },
  onStageLoaded: (stage) => {
    // 图纸加载完成后的处理
  },
  onGraphLoaded: (url) => {
    // 图纸URL加载完成
  },
  onBatchUpdate: (dataList) => {
    // 批量数据更新后的处理
  },
  onLevelChange: (level, isStrict) => {
    // 显示层级变更后的处理
  },
};

CustomCallbacks 回调

const devConfig = {
  isDev: false, // 打包后是否是开发环境
  devServerUrl: '', // 打包后的开发环境地址
  devServerPort: 8443, // 打包后的开发环境端口
}

使用场景

1. 基础图纸展示

<SyGraph :url="'/api/graph/123'" />

2. 本地图纸文件

<SyGraph :url="'/assets/graph.json'" :local="true" />

3. 直接传入数据

<SyGraph :data="graphData" />

4. 完整配置示例

<SyGraph
  :gid="graphId"
  :config="graphConfig"
  :custom-callbacks="callbacks"
  :error-handler="errorHandler"
  :show-map="true"
  @loaded="onGraphLoaded"
  @error="onGraphError"
/>

浏览器支持

• Chrome >= 60
• Firefox >= 60
• Safari >= 12
• Edge >= 79

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建库
npm run build:lib

# 构建类型
npm run build:types

# 完整构建
npm run build:all

# 类型检查
npm run type-check

# 代码检查
npm run lint

许可证

MIT

更新日志

查看 CHANGELOG.md 了解详细的更新记录。

贡献

欢迎提交 Issue 和 Pull Request。

相关链接

• Meta2D 官方文档
• Vue 3 文档
• Element Plus 文档