@leadal/flowstream-ui-plus 0.0.9 → 0.0.11

package/README.md

@@ -2,7 +2,7 @@
 
 FlowStream 前端运行时组件库的 npm 包名统一为 **`@leadal/flowstream-ui-plus`**。组件库基于 Vue 3 和 Element Plus，封装流程发起、工作项列表、流程操作、任务发送、任务跳转、流程图及办理轨迹等能力。
 
-组件库公开 **5 个主组件 + 1 个子组件**，以及命令式服务 `flowstream.runtimeService`。流程设计与 Editor 由工作流程引擎内部提供，不在本组件库中导出。
+组件库公开流程操作、列表、发送、跳转、流程实例图和流程定义预览等组件，以及命令式运行时服务。流程设计与 Editor 由工作流程引擎内部提供，不在本组件库中导出。
 
 > 目录
 >
@@ -14,6 +14,7 @@ FlowStream 前端运行时组件库的 npm 包名统一为 **`@leadal/flowstream
 >    4. [ui-flow-send](#24-ui-flow-send)
 >    5. [ui-flow-jump](#25-ui-flow-jump)
 >    6. [ui-flow-diagram](#26-ui-flow-diagram)
+>    7. [ui-flow-definition-preview](#27-ui-flow-definition-preview)
 > 3. [请求与错误处理](#3-请求与错误处理)
 > 4. [获取第一个办理节点](#4-获取第一个办理节点)
 > 5. [快速启动流程](#5-快速启动流程)
@@ -59,7 +60,7 @@ app.use(FlowstreamUIPlus, {
 app.mount('#app')
 ```
 
-全量注册后，可直接使用 `ui-flow-buttons`、`ui-flow-button`、`ui-flow-grid`、`ui-flow-send`、`ui-flow-jump` 和 `ui-flow-diagram` 全局标签。流程发起调用默认导出的 `flowstream.getRuntimeService().start()`。
+全量注册后，可直接使用 `ui-flow-buttons`、`ui-flow-button`、`ui-flow-grid`、`ui-flow-send`、`ui-flow-jump`、`ui-flow-diagram` 和 `ui-flow-definition-preview` 全局标签。流程发起调用默认导出的 `flowstream.getRuntimeService().start()`。
 
 ### 1.4 按需引入
 
@@ -67,6 +68,7 @@ app.mount('#app')
 import {
   FlowButton,
   FlowButtons,
+  FlowDefinitionPreview,
   FlowDiagram,
   FlowGrid,
   FlowJump,
@@ -107,6 +109,7 @@ configureWorkflow({
 | `UiFlowSend`    | `ui-flow-send`    | 完整任务发送弹窗                                      |
 | `UiFlowJump`    | `ui-flow-jump`    | 流程任务跳转能力                                      |
 | `UiFlowDiagram` | `ui-flow-diagram` | BPMN 流程图、运行状态和办理轨迹                       |
+| `UiFlowDefinitionPreview` | `ui-flow-definition-preview` | BPMN 流程定义预览，不查询流程实例数据      |
 
 除组件外，包入口还导出 `configureWorkflow`、请求实例 `workflowHttp`、类型定义以及流程 API 方法（例如 `startDraft`、`quickStart`、`getFirstHandleNodes`、`startNodes`）。
 
@@ -603,6 +606,64 @@ const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
 
 ---
 
+### 2.7 ui-flow-definition-preview
+
+`ui-flow-definition-preview` 用于只读预览流程定义。组件只获取并渲染 BPMN XML，不查询流程实例状态和办理轨迹。父容器必须有明确高度。
+
+#### 1) 属性定义（Properties）
+
+| 参数                  | 说明                                                   | 类型      | 默认值 |
+| --------------------- | ------------------------------------------------------ | --------- | ------ |
+| `processDefinitionId` | 已发布的流程定义 ID；未传 `bpmnXml` 时必填             | `string`  | `''`   |
+| `bpmnXml`             | 直接预览 BPMN XML，传入后优先于 `processDefinitionId`  | `string`  | `''`   |
+| `fitViewport`         | 加载及容器尺寸变化后是否自动适应可视区域               | `boolean` | `true` |
+
+#### 2) 事件定义（Events）
+
+| 事件名称 | 回调参数         | 说明                         |
+| -------- | ---------------- | ---------------------------- |
+| `loaded` | —                | BPMN XML 加载并渲染完成      |
+| `error`  | `error: unknown` | 下载或渲染流程定义失败       |
+
+#### 3) 方法定义（Methods）
+
+| 名称            | 说明                                      |
+| --------------- | ----------------------------------------- |
+| `refresh()`     | 重新下载或读取 XML 并渲染流程定义         |
+| `fitViewport()` | 立即将流程图缩放到适合当前容器            |
+| `viewer`        | bpmn-js Viewer 实例                       |
+
+#### 4) 已发布流程定义示例
+
+```vue
+<template>
+  <div class="preview-container">
+    <ui-flow-definition-preview
+      :process-definition-id="processDefinitionId"
+      @loaded="handleLoaded"
+      @error="handleError"
+    />
+  </div>
+</template>
+
+<style scoped>
+.preview-container {
+  width: 100%;
+  height: 600px;
+}
+</style>
+```
+
+#### 5) 未发布 XML 预览示例
+
+```vue
+<ui-flow-definition-preview :bpmn-xml="modelerXml" />
+```
+
+同时传入 `bpmnXml` 和 `processDefinitionId` 时，组件直接渲染 `bpmnXml`，不会调用 BPMN 下载接口。
+
+---
+
 ## 3. 请求与错误处理
 
 ### 3.1 成功响应