@leadal/flowstream-ui-plus 0.0.10 → 0.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +73 -7
  2. package/dist/flowstream-ui-plus.js +5229 -4711
  3. package/dist/flowstream-ui-plus.umd.cjs +15 -15
  4. package/dist/index.d.ts +84 -57
  5. package/dist/style.css +1 -1
  6. package/docs//346/216/245/345/205/245/346/226/207/346/241/243.md +3 -3
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  FlowStream 前端运行时组件库的 npm 包名统一为 **`@leadal/flowstream-ui-plus`**。组件库基于 Vue 3 和 Element Plus，封装流程发起、工作项列表、流程操作、任务发送、任务跳转、流程图及办理轨迹等能力。
4
4
 
5
- 组件库公开 **5 个主组件 + 1 个子组件**，以及命令式服务 `flowstream.runtimeService`。流程设计与 Editor 由工作流程引擎内部提供，不在本组件库中导出。
5
+ 组件库公开流程操作、列表、发送、跳转、流程实例图和流程定义预览等组件，以及命令式运行时服务。流程设计与 Editor 由工作流程引擎内部提供，不在本组件库中导出。
6
6
 
7
7
  > 目录
8
8
  >
@@ -14,6 +14,7 @@ FlowStream 前端运行时组件库的 npm 包名统一为 **`@leadal/flowstream
14
14
  > 4. [ui-flow-send](#24-ui-flow-send)
15
15
  > 5. [ui-flow-jump](#25-ui-flow-jump)
16
16
  > 6. [ui-flow-diagram](#26-ui-flow-diagram)
17
+ > 7. [ui-flow-definition-preview](#27-ui-flow-definition-preview)
17
18
  > 3. [请求与错误处理](#3-请求与错误处理)
18
19
  > 4. [获取第一个办理节点](#4-获取第一个办理节点)
19
20
  > 5. [快速启动流程](#5-快速启动流程)
@@ -59,7 +60,7 @@ app.use(FlowstreamUIPlus, {
59
60
  app.mount('#app')
60
61
  ```
61
62
 
62
- 全量注册后，可直接使用 `ui-flow-buttons`、`ui-flow-button`、`ui-flow-grid`、`ui-flow-send`、`ui-flow-jump` 和 `ui-flow-diagram` 全局标签。流程发起调用默认导出的 `flowstream.getRuntimeService().start()`。
63
+ 全量注册后，可直接使用 `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()`。
63
64
 
64
65
  ### 1.4 按需引入
65
66
 
@@ -67,6 +68,7 @@ app.mount('#app')
67
68
  import {
68
69
  FlowButton,
69
70
  FlowButtons,
71
+ FlowDefinitionPreview,
70
72
  FlowDiagram,
71
73
  FlowGrid,
72
74
  FlowJump,
@@ -107,6 +109,7 @@ configureWorkflow({
107
109
  | `UiFlowSend` | `ui-flow-send` | 完整任务发送弹窗 |
108
110
  | `UiFlowJump` | `ui-flow-jump` | 流程任务跳转能力 |
109
111
  | `UiFlowDiagram` | `ui-flow-diagram` | BPMN 流程图、运行状态和办理轨迹 |
112
+ | `UiFlowDefinitionPreview` | `ui-flow-definition-preview` | BPMN 流程定义预览，不查询流程实例数据 |
110
113
 
111
114
  除组件外，包入口还导出 `configureWorkflow`、请求实例 `workflowHttp`、类型定义以及流程 API 方法（例如 `startDraft`、`quickStart`、`getFirstHandleNodes`、`startNodes`）。
112
115
 
@@ -347,14 +350,18 @@ function handleWork({ action, workData }: {
347
350
 
348
351
  `ui-flow-send` 是完整的任务发送弹窗，不只是一个“发送”按钮。组件内置以下交互：
349
352
 
353
+ - 发送前调用 `checkSend`，完全按后端 `matched` 判断是否需要选择办理人；
354
+ - `matched=true` 时展示下一节点、办理人确认框，用户确认后直接发送；
355
+ - `matched=false` 时打开完整发送弹窗；
350
356
  - 根据当前流程定义、节点、工作项和变量计算下一环节；
351
357
  - 按下一环节加载候选办理人，支持列表和懒加载树；
352
358
  - 选择各下一环节的办理人；
353
359
  - 新增、删除和转换流程变量，并重新计算下一环节；
360
+ - 通过普通页签维护扩展参数，按“参数名称、参数类型、参数值”组装后传入办理人查询；
354
361
  - 填写审批意见；
355
362
  - 确认后调用任务发送接口，成功后关闭弹窗并提示“发送成功”。
356
363
 
357
- 办理人候选数据通过 `POST /flowstream/server/assignment/event/query` 加载。业务路由需要额外上下文时，可通过 `assignmentQueryParams` 传入任意数量的扩展参数，也可以不传；组件会将其整体放入请求体的 `extendParams`。请求根对象中的 `processDefinitionId`、`activityId`、`userId`、`parentId` 和 `ntype` 始终由组件维护。
364
+ 办理人候选数据通过 `POST /flowstream/server/assignment/event/query` 加载。业务路由需要额外上下文时，可通过 `assignmentQueryParams` 传入任意数量的扩展参数，也可以不传；用户还能在“扩展参数”页签继续编辑。组件校验参数名称、类型和值后将其整体放入请求体的 `extendParams`，参数变化时会清空旧办理人并重新加载候选人。请求根对象中的 `processDefinitionId`、`processInstanceId`、`activityId`、`userId`、`parentId` 和 `ntype` 始终由组件维护。动态路由配置为“流程启动者”时，后端通过 `processInstanceId` 读取该实例的起草人。
358
365
 
359
366
  #### 1) 属性定义（Properties）
360
367
 
@@ -364,7 +371,7 @@ function handleWork({ action, workData }: {
364
371
  | `processDefinitionId` | 流程定义 ID | `string \| number` | 是 | — |
365
372
  | `activity` | 当前节点，至少包含 `activityId`，可带 `activityName` | `object` | 是 | — |
366
373
  | `workId` | 当前工作项 ID | `string \| number` | 是 | — |
367
- | `processInstanceId` | 流程实例 ID | `string \| number` | 否 | `''` |
374
+ | `processInstanceId` | 流程实例 ID；动态路由以流程启动者为基准时必需 | `string \| number` | 条件 | `''` |
368
375
  | `variables` | 当前业务流程变量 | `Record<string, unknown>` | 否 | `{}` |
369
376
  | `assignmentQueryParams` | 通过 `extendParams` 转发给扩展路由的查询参数 | `Record<string, unknown>` | 否 | `{}` |
370
377
  | `dealUser` | 当前用户，可传 `id` 或 `userId` | `object` | 否 | `{}` |
@@ -382,7 +389,7 @@ function handleWork({ action, workData }: {
382
389
  | --------------------- | --------------------- | -------------------------------------------------- |
383
390
  | `update:modelValue` | `visible: boolean` | `v-model` 更新 |
384
391
  | `click` | — | 点击组件自身发送按钮时触发，随后组件会自行打开弹窗 |
385
- | `open` | — | 弹窗开始打开并解析下一环节 |
392
+ | `open` | — | 开始执行发送前检查；未命中时继续打开完整弹窗 |
386
393
  | `close` | — | 弹窗完成关闭 |
387
394
  | `next-nodes-resolved` | `nodes: FlowNode[]` | 下一环节解析成功 |
388
395
  | `before-send` | `data` | 请求发送前触发，参数是即将提交的数据 |
@@ -393,13 +400,14 @@ function handleWork({ action, workData }: {
393
400
 
394
401
  | 名称 | 类型 | 说明 |
395
402
  | ------------------------- | ------ | -------------------------------------------------------- |
396
- | `open()` | Method | 打开弹窗、重置意见与变量、解析下一环节 |
403
+ | `open()` | Method | 执行发送前检查；未命中时打开弹窗并解析下一环节 |
397
404
  | `close()` | Method | 关闭弹窗 |
398
405
  | `getNextNode(variables?)` | Method | 根据变量重新解析下一环节 |
399
406
  | `assembleData()` | Method | 组装 `{ workId, flowNodeAssignees, variables, opinion }` |
400
407
  | `send(formData?)` | Method | 提交发送；不传参数时使用 `assembleData()` |
401
408
  | `visible` | Ref | 内部弹窗状态 |
402
409
  | `loading` | Ref | 发送状态 |
410
+ | `checkingSend` | Ref | 发送前检查状态 |
403
411
  | `nodeLoading` | Ref | 下一环节计算状态 |
404
412
  | `nodeResolved` | Ref | 下一环节是否已完成计算 |
405
413
  | `nextNodes` | Ref | 下一环节列表 |
@@ -471,7 +479,7 @@ function handleAfterSend() {
471
479
  | --------------------- | ------------------------------------- | ------------------ | ------------ |
472
480
  | `processDefinitionId` | 流程定义 ID | `string \| number` | 是 |
473
481
  | `workId` | 当前待办工作项 ID | `string \| number` | 确认跳转时是 |
474
- | `processInstanceId` | 流程实例 ID（预留上下文） | `string \| number` | 否 |
482
+ | `processInstanceId` | 流程实例 ID；动态路由以流程启动者为基准时必需 | `string \| number` | 条件 |
475
483
  | `dealUser` | 当前用户，支持 `{ id, userId, name }` | `object` | 否 |
476
484
  | `assignmentQueryParams` | 通过 `extendParams` 转发给扩展路由的查询参数 | `Record<string, unknown>` | 否 |
477
485
  | `modelValue` | 弹窗显示状态，支持 `v-model` | `boolean` | 否 |
@@ -603,6 +611,64 @@ const diagramRef = ref<InstanceType<typeof FlowDiagram>>()
603
611
 
604
612
  ---
605
613
 
614
+ ### 2.7 ui-flow-definition-preview
615
+
616
+ `ui-flow-definition-preview` 用于只读预览流程定义。组件只获取并渲染 BPMN XML，不查询流程实例状态和办理轨迹。父容器必须有明确高度。
617
+
618
+ #### 1) 属性定义（Properties）
619
+
620
+ | 参数 | 说明 | 类型 | 默认值 |
621
+ | --------------------- | ------------------------------------------------------ | --------- | ------ |
622
+ | `processDefinitionId` | 已发布的流程定义 ID；未传 `bpmnXml` 时必填 | `string` | `''` |
623
+ | `bpmnXml` | 直接预览 BPMN XML，传入后优先于 `processDefinitionId` | `string` | `''` |
624
+ | `fitViewport` | 加载及容器尺寸变化后是否自动适应可视区域 | `boolean` | `true` |
625
+
626
+ #### 2) 事件定义（Events）
627
+
628
+ | 事件名称 | 回调参数 | 说明 |
629
+ | -------- | ---------------- | ---------------------------- |
630
+ | `loaded` | — | BPMN XML 加载并渲染完成 |
631
+ | `error` | `error: unknown` | 下载或渲染流程定义失败 |
632
+
633
+ #### 3) 方法定义（Methods）
634
+
635
+ | 名称 | 说明 |
636
+ | --------------- | ----------------------------------------- |
637
+ | `refresh()` | 重新下载或读取 XML 并渲染流程定义 |
638
+ | `fitViewport()` | 立即将流程图缩放到适合当前容器 |
639
+ | `viewer` | bpmn-js Viewer 实例 |
640
+
641
+ #### 4) 已发布流程定义示例
642
+
643
+ ```vue
644
+ <template>
645
+ <div class="preview-container">
646
+ <ui-flow-definition-preview
647
+ :process-definition-id="processDefinitionId"
648
+ @loaded="handleLoaded"
649
+ @error="handleError"
650
+ />
651
+ </div>
652
+ </template>
653
+
654
+ <style scoped>
655
+ .preview-container {
656
+ width: 100%;
657
+ height: 600px;
658
+ }
659
+ </style>
660
+ ```
661
+
662
+ #### 5) 未发布 XML 预览示例
663
+
664
+ ```vue
665
+ <ui-flow-definition-preview :bpmn-xml="modelerXml" />
666
+ ```
667
+
668
+ 同时传入 `bpmnXml` 和 `processDefinitionId` 时，组件直接渲染 `bpmnXml`，不会调用 BPMN 下载接口。
669
+
670
+ ---
671
+
606
672
  ## 3. 请求与错误处理
607
673
 
608
674
  ### 3.1 成功响应