npm package: @syhr/sy-graph
Description: Planar graphic config tool based on @meta2d.
Author: syhr
Latest version: 1.0.9-beta.6

# @syhr/sy-graph

一个基于 Meta2D 的平面图形配置工具 Vue 3 组件库。

## 特性

- 🎨 基于 Meta2D 的强大图形编辑能力
- 🔧 支持多种图形类型和图表
- 📱 响应式设计，支持移动端
- 🎯 完整的 TypeScript 支持
- 📦 多种模块格式支持（ES、UMD、CommonJS）
- 🔌 Vue 3 插件化架构
- 🛡️ 安全的全局属性处理，避免变量冲突
- 🔄 实时数据更新和 WebSocket 支持
- 🎛️ 可定制的错误处理和回调机制
- 🚀 高性能渲染和批量更新
- 🎨 多层级显示控制
- 📡 支持自定义 API 和事件总线注入

## 安装

```bash
npm install @syhr/sy-graph
```

### Peer Dependencies

确保你的项目已安装以下 peer dependencies：

```bash
# 必需依赖
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
```

## 使用

### 全局注册（推荐）

```javascript
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');
```

### 局部使用

```javascript
import { SyGraph } from '@syhr/sy-graph';

export default {
  components: {
    SyGraph,
  },
};
```

### 在模板中使用

```vue
<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 类型声明：

```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 配置

```typescript
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 回调

```typescript
const callbacks = {
  onWebSocketMessage: (message) => {
    // 处理WebSocket消息
  },
  onCustomMessage: (msg) => {
    // 处理自定义消息
  },
  onStageLoaded: (stage) => {
    // 图纸加载完成后的处理
  },
  onGraphLoaded: (url) => {
    // 图纸URL加载完成
  },
  onBatchUpdate: (dataList) => {
    // 批量数据更新后的处理
  },
  onLevelChange: (level, isStrict) => {
    // 显示层级变更后的处理
  },
};
```

### CustomCallbacks 回调

```typescript
const devConfig = {
  isDev: false, // 打包后是否是开发环境
  devServerUrl: '', // 打包后的开发环境地址
  devServerPort: 8443, // 打包后的开发环境端口
}
```

## 使用场景

### 1. 基础图纸展示

```vue
<SyGraph :url="'/api/graph/123'" />
```

### 2. 本地图纸文件

```vue
<SyGraph :url="'/assets/graph.json'" :local="true" />
```

### 3. 直接传入数据

```vue
<SyGraph :data="graphData" />
```

### 4. 完整配置示例

```vue
<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

## 开发

```bash
# 安装依赖
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](LICENSE)

## 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解详细的更新记录。

## 贡献

欢迎提交 Issue 和 Pull Request。

## 相关链接

- [Meta2D 官方文档](https://meta2d.com)
- [Vue 3 文档](https://vuejs.org)
- [Element Plus 文档](https://element-plus.org)