@mx-sose-front/mx-sose-graph

MX Sose Graph

开发规范

所有后续开发必须遵循 架构规范 与 贡献约定。提交前运行 npm run verify；目录归属、依赖边界、命名和历史大文件预算会被自动检查。

一个专为体系工程建模设计的Vue3图可视化库，提供丰富的图形组件、交互功能和数据管理能力。

特性

• 🎯 Vue3 原生支持 - 基于Vue3 Composition API和Pinia状态管理
• 🎨 丰富的图形组件 - 支持体系工程建模、块状图、折角图、分割线等多种图形
• 🖱️ 强大的交互功能 - 支持拖拽、缩放、平移、选择、连接等操作
• 📐 智能布局管理 - 自动计算图形位置和连接关系
• 🔧 高度可配置 - 支持自定义样式、图标、标签值等
• 📦 TypeScript支持 - 完整的类型定义和类型安全
• 🚀 高性能渲染 - 优化的渲染性能和内存管理
• 🎪 事件驱动 - 基于事件总线的组件通信机制

安装

npm install mx-sose-graph
# 或
yarn add mx-sose-graph
# 或
pnpm add mx-sose-graph

快速开始

作为插件使用

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

作为组件使用

<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的图形状态管理，提供以下功能：

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

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

interface Bounds {
  x?: number
  y?: number
  width?: number
  height?: number
}

Style 接口

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
}

工具函数

图形注册

import { registerShapes } from 'mx-sose-graph'

registerShapes({
  StrategicTaxonomyDiagram,
  Block,
  DogEar,
  DividingLine,
  Edge
})

图形渲染

import { getShapeComponent, getShapeStyle } from 'mx-sose-graph'

// 获取图形组件
const component = getShapeComponent(shape)

// 获取图形样式
const style = getShapeStyle(shape)

开发

安装依赖

npm install

开发服务器

npm run dev

构建库

npm run build:lib

类型检查

npm run type-check

代码检查

npm run lint

生产构建

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的现代化架构