@dragon-x/bpmn-viewer

@dragon-x/bpmn-viewer

A Vue 3 BPMN diagram viewer component with preset viewer and token simulation support.

Built on top of bpmn-js, providing rich diagram interaction and process simulation capabilities.

✨ Features

• 🎨 BpmnViewer — Basic BPMN diagram viewer with toolbar (zoom, download, fullscreen)
• 🔄 BpmnPresetViewer — Preset viewer that auto-loads diagrams by process instance / model key
• 🎭 BpmnMocker — Token simulation for process validation
• 🌓 Dark / Light Theme — Built-in theme switching
• 🌍 i18n — Chinese and English support out of the box

📦 Installation

npm install @dragon-x/bpmn-viewer
# or
pnpm add @dragon-x/bpmn-viewer
# or
yarn add @dragon-x/bpmn-viewer

🚀 Quick Start

<template>
  <BpmnViewer
    :xml="xmlStr"
    theme="light"
    local="zh_CN"
    :toolbar="true"
    @viewer-init="handleInit"
    @element-hover="handleHover"
  />
</template>

<script setup>
import { BpmnViewer } from '@dragon-x/bpmn-viewer';
import '@dragon-x/bpmn-viewer/lib/bpmn-viewer.css';

const xmlStr = `<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
  <!-- Your BPMN XML content -->
</definitions>`;

function handleInit() {
  console.log('Viewer initialized');
}

function handleHover(element) {
  console.log('Element hovered:', element.id);
}
</script>

📖 Components

BpmnViewer

BpmnPresetViewer

Note: At least one of procInstId, modelKey, or defId must be provided. Priority: procInstId > defId > modelKey.

BpmnMocker

TippyPopover

A tooltip popover component based on Tippy.js, used internally by the viewer components for node detail tooltips.

🤝 Peer Dependencies

Ensure these are installed in your project:

{
  "vue": "^3.2.0",
  "vue-i18n": "^9.0.0",
  "bpmn-js": "^18.0.0",
  "bpmn-js-i18n-zh": "^1.0.0",
  "diagram-js-grid-bg": "^1.0.0"
}

Note: vue-i18n, bpmn-js-i18n-zh, and diagram-js-grid-bg are optional — they can be omitted if their features are not needed.

🛠️ Development

git clone https://github.com/xietongjian/bpmn-viewer.git
cd bpmn-viewer
pnpm install
pnpm dev     # Development with hot-reload
pnpm build   # Build for production demo
pnpm build:compo   # Build library bundle (for npm publish)
pnpm lint    # Lint and format

📄 License

MIT