@leadal/flowstream-ui-plus 0.0.2 → 0.0.3

package/README.md

@@ -670,7 +670,7 @@ const firstHandleNodes: FlowNode[] = result.data || []
 import flowstream from '@leadal/flowstream-ui-plus'
 
 async function submitBusiness() {
-  await flowstream.getRuntimeService().start({
+  const result = await flowstream.getRuntimeService().start({
     processDefinitionId,
     draftUserId: currentUser.id,
     draftUserName: currentUser.name,
@@ -679,6 +679,17 @@ async function submitBusiness() {
       name: borrowTitle,
     },
     variables,
+    async onBeforeStart(startArgs) {
+      // 可执行同步校验，也可以 await 业务项目自己的表单弹窗。
+      const formData = await openBusinessForm()
+      if (!formData) return false
+      startArgs.variables = { ...startArgs.variables, ...formData }
+      return true
+    },
+    async onBeforeSend(context) {
+      // false：实例已经创建，但不打开审批人选择弹窗。
+      return validateBeforeSend(context)
+    },
     onStarted(result) {
       saveFlowRelation(result.processInstanceId)
     },
@@ -687,15 +698,52 @@ async function submitBusiness() {
       refreshBusinessList()
     },
     onClose() {
-      // 关闭发送弹窗不会撤销已经启动的流程。
+      // 未发送就关闭弹窗时，运行时服务会撤销刚创建的流程实例。
     },
     onError(error) {
       console.error(error.phase, error.message)
     },
   })
+  if (result === false) return
 }
 ```
 
-`start()` 返回 `processInstanceId`、`processDefinitionId` 和起草人当前 `workId`。当前流程的发送弹窗关闭后，可调用 `flowstream.getRuntimeService().open()` 重新打开；调用 `close()` 只关闭弹窗，不撤销流程实例。`singleAssignee` 默认为 `true`，也可在启动参数中传入 `dialogTitle`、`dialogWidth`、`defaultOpinion` 和 `bpmnXml`。
+`onBeforeStart` 在首办节点查询和 `quickStart` 之前执行；返回 `false` 时 `start()` 返回 `false`，不会创建流程实例。`onBeforeSend` 在实例创建成功后、发送弹窗打开前执行；返回 `false` 时 `start()` 仍返回流程实例结果，但不会弹窗，并保留当前会话。之后调用 `await flowstream.getRuntimeService().open()` 会重新执行 `onBeforeSend`，通过后才打开弹窗；若决定放弃，调用 `close()` 会撤销该实例并释放会话。
+
+两个前置钩子都支持 `boolean | Promise<boolean>`。因此业务项目需要“弹表单、校验通过后再启动”时，应让业务弹窗封装成 Promise，而不是由流程组件识别业务字段：
+
+```ts
+let finishBeforeStart: ((allowed: boolean) => void) | undefined
+
+function waitForBusinessForm() {
+  businessDialogVisible.value = true
+  return new Promise<boolean>(resolve => {
+    finishBeforeStart = resolve
+  })
+}
+
+async function confirmBusinessForm() {
+  const valid = await businessFormRef.value?.validate().catch(() => false)
+  if (!valid) return
+  businessDialogVisible.value = false
+  finishBeforeStart?.(true)
+  finishBeforeStart = undefined
+}
+
+function cancelBusinessForm() {
+  businessDialogVisible.value = false
+  finishBeforeStart?.(false)
+  finishBeforeStart = undefined
+}
+
+await flowstream.getRuntimeService().start({
+  processDefinitionId,
+  draftUserId: currentUser.id,
+  draftUserName: currentUser.name,
+  onBeforeStart: waitForBusinessForm,
+})
+```
+
+业务弹窗通过右上角关闭、路由离开或组件卸载时也必须 `resolve(false)`，避免 `start()` 一直处于等待状态。`singleAssignee` 默认为 `true`，也可在启动参数中传入 `dialogTitle`、`dialogWidth`、`defaultOpinion` 和 `bpmnXml`。
 
 `quickStart()`、`getFirstHandleNodes()`、`nextSendNode()`、`nodeAssistant()` 和 `sendTask()` 仍作为底层 API 导出，供组件内部及高级扩展使用；普通业务项目应优先调用 `flowstream.getRuntimeService().start()`，不要自行复制流程编排。