@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/workflow-bpmn.md

@@ -0,0 +1,206 @@
+# BPMN 工作流查看器
+
+## 依赖
+
+`bpmn-js/lib/Viewer` — BPMN 流程图的只读查看器（不含建模器）。
+
+## 类型定义
+
+```typescript
+// src/views/workflow/types/bpmn.ts
+
+export type BpmnElementType =
+  | 'bpmn:StartEvent' | 'bpmn:EndEvent'
+  | 'bpmn:UserTask' | 'bpmn:ServiceTask'
+  | 'bpmn:ExclusiveGateway' | 'bpmn:SequenceFlow' | 'bpmn:Process'
+
+export interface BpmnElement {
+  id: string
+  type: string | BpmnElementType
+  name?: string
+  businessObject?: any
+}
+
+export interface ProcessInfo {
+  finishedTasks?: string[]
+  finishedTaskSet?: Set<string>
+  activeTasks?: string[]
+  activeTaskSet?: Set<string>
+  unfinishedTasks?: string[]
+  unfinishedTaskSet?: Set<string>
+  finishedSequenceFlows?: string[]
+  finishedSequenceFlowSet?: Set<string>
+}
+
+export interface BpmnWorkflowData {
+  xml: string
+  processInfo?: ProcessInfo
+}
+
+export interface WorkflowViewerProps {
+  xml?: string
+  processInfo?: ProcessInfo
+  height?: string | number
+  showToolbar?: boolean
+  allowExport?: boolean
+}
+```
+
+## 组件结构
+
+```vue
+<!-- src/views/workflow/components/WorkflowViewer.vue -->
+<script setup lang="ts">
+import Viewer from 'bpmn-js/lib/Viewer'
+import type { BpmnWorkflowData, ProcessInfo } from '../types/bpmn'
+
+defineOptions({ name: 'WorkflowViewer' })
+
+const props = withDefaults(defineProps<WorkflowViewerProps>(), {
+  height: '500px',
+  showToolbar: true,
+  allowExport: false,
+})
+
+const containerRef = ref<HTMLElement>()
+let viewer: Viewer | null = null
+
+// 初始化查看器
+const initViewer = async () => {
+  if (!containerRef.value) return
+  viewer = new Viewer({ container: containerRef.value })
+}
+
+// 导入 BPMN XML
+const importXml = async (xml: string) => {
+  if (!viewer) return
+  try {
+    await viewer.importXML(xml)
+    // 缩放适配
+    const canvas = viewer.get('canvas') as any
+    canvas.zoom('fit-viewport')
+  } catch (err) {
+    console.error('BPMN XML 导入失败', err)
+  }
+}
+
+// 高亮已完成/活动节点
+const highlightProcess = (processInfo: ProcessInfo) => {
+  if (!viewer) return
+  const canvas = viewer.get('canvas') as any
+  const elementRegistry = viewer.get('elementRegistry') as any
+
+  // 高亮已完成任务
+  processInfo.finishedTaskSet?.forEach((id: string) => {
+    const element = elementRegistry.get(id)
+    if (element) canvas.addMarker(id, 'bpmn-finished')
+  })
+
+  // 高亮当前活动任务
+  processInfo.activeTaskSet?.forEach((id: string) => {
+    const element = elementRegistry.get(id)
+    if (element) canvas.addMarker(id, 'bpmn-active')
+  })
+
+  // 高亮已完成序列流
+  processInfo.finishedSequenceFlowSet?.forEach((id: string) => {
+    const element = elementRegistry.get(id)
+    if (element) canvas.addMarker(id, 'bpmn-flow-finished')
+  })
+}
+
+// 导出 SVG
+const exportSvg = async () => {
+  if (!viewer) return null
+  const svgResult = await viewer.saveSVG()
+  return svgResult.svg
+}
+
+onMounted(async () => {
+  await initViewer()
+  if (props.xml) await importXml(props.xml)
+  if (props.processInfo) highlightProcess(props.processInfo)
+})
+
+onBeforeUnmount(() => {
+  viewer?.destroy()
+  viewer = null
+})
+</script>
+
+<template>
+  <div class="workflow-viewer">
+    <div v-if="showToolbar" class="viewer-toolbar">
+      <el-button size="small" @click="handleZoomIn">放大</el-button>
+      <el-button size="small" @click="handleZoomOut">缩小</el-button>
+      <el-button size="small" @click="handleFitView">适配</el-button>
+      <el-button v-if="allowExport" size="small" @click="handleExportSvg">导出 SVG</el-button>
+    </div>
+    <div ref="containerRef" :style="{ height: typeof height === 'number' ? height + 'px' : height }" />
+  </div>
+</template>
+
+<style>
+/* BPMN 高亮样式（全局，不加 scoped） */
+:deep(.bpmn-active) .djs-visual > :nth-child(1) {
+  fill: #409eff !important;
+  stroke: #409eff !important;
+}
+:deep(.bpmn-finished) .djs-visual > :nth-child(1) {
+  fill: #67c23a !important;
+  stroke: #67c23a !important;
+}
+:deep(.bpmn-flow-finished) .djs-visual > :nth-child(1) {
+  stroke: #67c23a !important;
+}
+</style>
+```
+
+## 页面调用
+
+```vue
+<!-- src/views/workflow/bpmn/index.vue -->
+<script setup lang="ts">
+import { ReDialog } from '@/components/ReDialog'
+import WorkflowViewer from '../components/WorkflowViewer.vue'
+
+defineOptions({ name: 'WorkflowBpmn' })
+const showDialog = ref(false)
+</script>
+
+<template>
+  <el-button type="primary" size="large" @click="showDialog = true">查看流程图</el-button>
+  <ReDialog v-model="showDialog" title="BPMN流程图查看器">
+    <WorkflowViewer />
+    <template #footer>
+      <el-button @click="showDialog = false">关闭</el-button>
+    </template>
+  </ReDialog>
+</template>
+```
+
+## 数据获取
+
+```typescript
+// API 返回格式
+interface WorkflowApiResponse {
+  data: BpmnWorkflowData  // { xml: string, processInfo?: ProcessInfo }
+  code?: number
+  message?: string
+}
+```
+
+## 关键约定
+
+1. 使用 `bpmn-js/lib/Viewer`（只读），不使用 `Modeler`（可编辑）除非有流程设计需求。
+2. 组件销毁时必须调用 `viewer.destroy()` 释放资源。
+3. 高亮通过 `canvas.addMarker(id, className)` 实现，CSS 使用 `:deep()` 穿透 BPMN 内部 SVG。
+4. 流程数据（已完成/活动任务）由后端接口统一返回，前端只负责渲染。
+5. 弹窗内使用时注意容器高度，BPMN 需要明确的宽高才能正确渲染。
+6. `canvas.zoom('fit-viewport')` 自动缩放适配视口。
+
+## 关联文件
+
+- [src/views/workflow/bpmn/index.vue](file:///e:/work/vue3-web-temp/src/views/workflow/bpmn/index.vue)
+- [src/views/workflow/components/WorkflowViewer.vue](file:///e:/work/vue3-web-temp/src/views/workflow/components/WorkflowViewer.vue)
+- [src/views/workflow/types/bpmn.ts](file:///e:/work/vue3-web-temp/src/views/workflow/types/bpmn.ts)