节点成组与子流程 (NodeGroupPlugin)

createNodeGroupPlugin 允许将多个节点一键分组为带父子关系的容器节点，支持折叠展开与解组还原。 对于 AI Agent 编排、BPMN 子流程、多阶段数据管道等复杂场景极为实用。

快速上手

import { createNodeGroupPlugin } from '@yh-ui/flow'

// onMounted 中安装插件
// usePlugin 会调用 plugin.install(flowInstance)
// 从而在 flowRef.value 上挂载 groupSelectedNodes / ungroupNodes 等方法
onMounted(() => {
  flowRef.value?.usePlugin(
    createNodeGroupPlugin({
      groupIdPrefix: 'grp', // 自动生成分组 ID 时的前缀
      paddingX: 40, // 分组容器水平内边距（px）
      paddingY: 50 // 分组容器垂直内边距（px）
    })
  )
})

// 然后即可调用：
flowRef.value?.groupSelectedNodes('我的分组') // → 分组并返回 groupId
flowRef.value?.ungroupNodes(groupId) // → 解组
flowRef.value?.toggleGroupCollapse(groupId) // → 折叠/展开

框选成组 / 解组

选中 2+ 节点：

节点 A

节点 B

节点 C

节点 D

输出节点

💡 点击节点可选中，Shift 多选，再点击"成组"

框选节点后一键成组，支持自定义分组名称

折叠 / 展开分组

子节点已显示

数据处理组

清洗节点

转换节点

输出

折叠分组可隐藏所有子节点，展开恢复

API

安装插件

import { createNodeGroupPlugin } from '@yh-ui/flow'

onMounted(() => {
  flowRef.value?.usePlugin(createNodeGroupPlugin(options))
})

FlowInstance 扩展方法

插件安装后，以下方法自动挂载到 flowRef.value 上

方法	签名	说明
groupSelectedNodes	(label?: string) => string | null	将所有 selected 节点分组，返回分组 ID，不足 2 个时返回 null
ungroupNodes	(groupId: string) => void	解组：子节点恢复绝对坐标并提升为顶层节点
toggleGroupCollapse	(groupId: string) => void	切换分组折叠/展开状态（同时隐藏/显示相关边）
isGroupCollapsed	(groupId: string) => boolean	查询分组当前是否已折叠
getGroupChildren	(groupId: string) => Node[]	获取分组的所有子节点
getGroupRegistry	() => Map<string, GroupInfo>	获取完整分组注册表（调试用）

NodeGroupOptions

属性	类型	默认值	说明
enabled	boolean	true	是否启用插件
groupNodeType	string	'group'	分组节点渲染类型，需在 nodeTypes 中注册
paddingX	number	40	分组容器水平内边距（px）
paddingY	number	50	分组容器垂直内边距（px）
groupIdPrefix	string	'group'	自动生成分组 ID 的前缀（如 'grp' → 生成 'grp-1'）
collapseMode	'collapse' | 'hide'	'hide'	折叠行为：'hide' 直接隐藏子节点

GroupInfo 类型

interface GroupInfo {
  groupId: string
  childIds: string[]
  collapsed: boolean
  originalPositions: Record<string, { x: number; y: number }>
}

NOTE

分组节点会自动设置 zIndex: -1，确保位于子节点之下形成正确的视觉层次。 子节点通过 parentId 和 extent: 'parent' 约束在父容器内。

下一步

• 历史撤销/重做
• 数据流光效边
• 自动布局