npm package: @mx-sose-front/mx-sose-graph
Description: A Vue3 graph visualization plugin library
Author: Your Name
Latest version: 1.2.9

# MX Sose Graph

一个专为体系工程建模设计的Vue3图可视化库，提供丰富的图形组件、交互功能和数据管理能力。

## 特性

- 🎯 **Vue3 原生支持** - 基于Vue3 Composition API和Pinia状态管理
- 🎨 **丰富的图形组件** - 支持体系工程建模、块状图、折角图、分割线等多种图形
- 🖱️ **强大的交互功能** - 支持拖拽、缩放、平移、选择、连接等操作
- 📐 **智能布局管理** - 自动计算图形位置和连接关系
- 🔧 **高度可配置** - 支持自定义样式、图标、标签值等
- 📦 **TypeScript支持** - 完整的类型定义和类型安全
- 🚀 **高性能渲染** - 优化的渲染性能和内存管理
- 🎪 **事件驱动** - 基于事件总线的组件通信机制

## 安装

```bash
npm install mx-sose-graph
# 或
yarn add mx-sose-graph
# 或
pnpm add mx-sose-graph
```

## 快速开始

### 作为插件使用

```typescript
import { createApp } from 'vue'
import MxSoseGraphPlugin from 'mx-sose-graph'
import 'mx-sose-graph/dist/style.css'

const app = createApp(App)
app.use(MxSoseGraphPlugin)
app.mount('#app')
```

### 作为组件使用

```vue
<template>
  <div class="graph-container">
    <GraphView
      :add-shape-data="newShape"
      :connect-shape-data="connectShape"
      @shapes-property="handlePropertyPanel"
      @shapes-edit-name="handleEditName"
      @connect-end="handleConnectEnd"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { GraphView } from 'mx-sose-graph'
import type { Shape } from 'mx-sose-graph'

// 新增图形数据
const newShape = ref<Shape>({
  id: 'shape-1',
  diagramId: 'diagram-1',
  shapeKey: 'Block',
  shapeType: 'shape',
  bounds: { x: 100, y: 100, width: 120, height: 80 },
  keywords: '示例图形',
  modelId: 'model-1',
  modelName: '示例模型',
  names: '{"name": "示例图形"}',
  name: '示例图形',
  showKeywords: true,
  showIcon: true,
  showName: true,
  showTaggedValues: false,
  showComparents: false,
  meta: {}
})

// 连接图形数据
const connectShape = ref<Shape | null>(null)

// 事件处理
const handlePropertyPanel = (data: { selectedShape: Shape, showPropertyPanel: boolean }) => {
  console.log('属性面板:', data)
}

const handleEditName = (data: { shape: Shape, newName: string }) => {
  console.log('编辑名称:', data)
}

const handleConnectEnd = (data: { sourceId: string, targetId: string, sourcePoint: any, targetPoint: any, waypoints: any[] }) => {
  console.log('连接完成:', data)
}
</script>

<style scoped>
.graph-container {
  width: 100%;
  height: 600px;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
}
</style>
```

## 核心组件

### GraphView

主要的图形视图组件，负责渲染整个图形画布。

**Props:**
- `addShapeData: Shape` - 要添加的图形数据
- `connectShapeData: Shape` - 连接操作的图形数据

**Events:**
- `shapes-property` - 图形属性面板事件
- `shapes-edit-name` - 图形名称编辑事件
- `connect-end` - 连接完成事件

### 图形组件

#### StrategicTaxonomyDiagram
体系工程建模图组件，用于创建体系层级的图形表示。

#### Block
块状图形组件，支持自定义样式和内容。

#### DogEar
折角图形组件，常用于标注和提示。

#### DividingLine
分割线组件，用于图形区域的划分。

#### Edge
边连接组件，支持多种连接样式和路径。

## 状态管理

### useGraphStore

基于Pinia的图形状态管理，提供以下功能：

```typescript
import { useGraphStore } from 'mx-sose-graph'

const graphStore = useGraphStore()

// 添加图形
graphStore.addShape(shape)

// 更新图形
graphStore.updateShape(shapeId, updates)

// 选择图形
graphStore.selectShape(shape)

// 删除图形
graphStore.removeShape(shapeId)

// 拖拽操作
graphStore.startDragShape(shapeId, pointer)
graphStore.moveDraggedShape(pointer)
graphStore.endDragShape()
```

## 类型定义

### Shape 接口

```typescript
interface Shape {
  id: string                    // 图形ID
  diagramId: string            // 画布ID
  parenShapeId?: string        // 父图形ID
  shapeKey: string             // 图形类型
  shapeType: 'shape' | 'edge' | 'pin' | 'diagram'
  bounds: Bounds               // 位置和大小
  style?: Style               // 样式配置
  keywords: string            // 关键字
  icon?: string              // 图标
  modelId: string            // 模型ID
  modelName: string          // 模型名称
  names: string              // 名称JSON
  name: string               // 显示名称
  showKeywords: boolean      // 是否显示关键字
  showIcon: boolean          // 是否显示图标
  showName: boolean          // 是否显示名称
  showTaggedValues: boolean  // 是否显示标签值
  showComparents: boolean    // 是否显示隔间组件
  taggedValueLabels?: TaggedValueLabel[]
  comparents?: Comparent[]
  meta: any                  // 元数据
}
```

### Bounds 接口

```typescript
interface Bounds {
  x?: number
  y?: number
  width?: number
  height?: number
}
```

### Style 接口

```typescript
interface Style {
  fontSize?: number
  fontFamily?: string
  fontWeight?: string
  color?: string
  backgroundColor?: string
  borderColor?: string
  borderWidth?: number
  borderRadius?: number
  padding?: number | { top: number; right: number; bottom: number; left: number }
  margin?: number
  zIndex?: number
  // 画布相关样式
  canvasBorderWidth?: number
  canvasBorderColor?: string
  canvasBorderStyle?: 'dashed' | 'solid' | 'dotted'
  canvasNameFontSize?: number
  canvasNameFontFamily?: string
  canvasNameFontColor?: string
  // 渐变相关
  gradientLeftColor?: string
  gradientRightColor?: string
}
```

## 工具函数

### 图形注册

```typescript
import { registerShapes } from 'mx-sose-graph'

registerShapes({
  StrategicTaxonomyDiagram,
  Block,
  DogEar,
  DividingLine,
  Edge
})
```

### 图形渲染

```typescript
import { getShapeComponent, getShapeStyle } from 'mx-sose-graph'

// 获取图形组件
const component = getShapeComponent(shape)

// 获取图形样式
const style = getShapeStyle(shape)
```

## 开发

### 安装依赖

```bash
npm install
```

### 开发服务器

```bash
npm run dev
```

### 构建库

```bash
npm run build:lib
```

### 类型检查

```bash
npm run type-check
```

### 代码检查

```bash
npm run lint
```

### 生产构建

```bash
npm run build:prod
```

## 项目结构

```
src/
├── components/           # 图形组件
│   ├── Diagram/         # 图表组件
│   ├── Shape/           # 图形组件
│   ├── Edge/            # 边组件
│   └── Port/            # 端口组件
├── store/               # 状态管理
│   ├── graphStore.ts    # 图形状态
│   └── eventBus.ts      # 事件总线
├── render/              # 渲染相关
│   ├── shape-registry.ts
│   └── shape-renderer.ts
├── utils/               # 工具函数
│   ├── diagram.ts       # 图表工具
│   ├── drag.ts          # 拖拽工具
│   ├── geom.ts          # 几何计算
│   └── containers.ts    # 容器管理
├── types/               # 类型定义
├── style/               # 样式文件
└── view/                # 视图组件
    └── graph.vue        # 主图形视图
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 支持体系工程建模可视化
- 提供丰富的图形组件和交互功能
- 基于Vue3和Pinia的现代化架构