@knotx/plugins-group

分组插件，提供节点分组管理功能。

安装

npm install @knotx/plugins-group

基本概述

@knotx/plugins-group 是 KnotX 框架的分组插件，提供节点分组管理功能。支持创建、解散、删除分组，以及向分组中添加或移除节点。分组节点可以自动计算边界，支持分层渲染和样式定制。

实现原理

该插件通过双向关系管理实现分组功能：

1. 分组关系管理：使用 DualRelation 维护父子节点关系
2. 边界计算：自动计算分组边界并支持自定义内边距
3. 分层渲染：集成节点层级获取器，确保分组节点在正确的层级渲染
4. 操作管道：通过操作管道处理分组相关的节点操作

依赖插件

该插件依赖以下包：

• @knotx/core - 核心功能
• @knotx/decorators - 装饰器支持
• @knotx/plugins-base-render - 基础渲染插件（peer dependency）
• @knotx/jsx - JSX 支持（peer dependency）
• rxjs - 响应式编程

API 使用

基本使用

import { Group } from '@knotx/plugins-group'

// 创建分组插件实例
const group = new Group()

// 在引擎中注册插件
engine.use(group)

创建分组

const { createGroup } = useKnotX().group

// 创建基础分组
const groupId = createGroup({
  id: 'group-1',
  nodeIds: ['node-1', 'node-2', 'node-3'],
  data: { label: '我的分组' }
})

// 创建带配置的分组
const groupId = createGroup({
  id: 'group-2',
  nodeIds: ['node-4', 'node-5'],
  config: {
    autoBounds: true,
    padding: 20,
    style: {
      backgroundColor: 'rgba(59, 130, 246, 0.1)',
      borderColor: '#3b82f6',
      borderWidth: 2,
      borderStyle: 'dashed',
      borderRadius: 8
    }
  },
  data: { label: '自定义分组' }
})

分组操作

const { dissolveGroup, deleteGroup, addNodesToGroup, removeNodesFromGroup, moveGroup } = useKnotX().group

// 解散分组
dissolveGroup('group-1')

// 删除分组
deleteGroup('group-1')

// 向分组添加节点
addNodesToGroup('group-1', ['node-6', 'node-7'])

// 从分组移除节点
removeNodesFromGroup('group-1', ['node-1'])

// 移动分组
moveGroup('group-1', { x: 100, y: 100 })

// 增量移动分组
moveGroup('group-1', { x: 50, y: 50 }, true)

完整示例

import { Engine } from '@knotx/core'
import { BaseRender } from '@knotx/plugins-base-render'
import { Group } from '@knotx/plugins-group'

const engine = new Engine()

// 注册依赖插件
engine.use(new BaseRender())

// 注册分组插件
engine.use(new Group())

// 创建节点
engine.dispatchNodeOperation({
  type: 'batch',
  operations: [
    { type: 'add', node: { id: 'node-1', type: 'default', position: { x: 100, y: 100 }, data: { label: '节点1' } } },
    { type: 'add', node: { id: 'node-2', type: 'default', position: { x: 200, y: 100 }, data: { label: '节点2' } } },
    { type: 'add', node: { id: 'node-3', type: 'default', position: { x: 150, y: 200 }, data: { label: '节点3' } } }
  ]
})

// 创建分组
const groupPlugin = engine.getPlugin('group')
const groupId = groupPlugin.createGroup({
  id: 'my-group',
  nodeIds: ['node-1', 'node-2', 'node-3'],
  config: {
    autoBounds: true,
    padding: 15,
    style: {
      backgroundColor: 'rgba(34, 197, 94, 0.1)',
      borderColor: '#22c55e',
      borderWidth: 1,
      borderStyle: 'solid',
      borderRadius: 6
    }
  },
  data: { label: '我的分组' }
})

配置接口

GroupConfig

interface GroupConfig {
  /**
   * 是否自动计算边界
   * @default true
   */
  autoBounds?: boolean
  /**
   * 内边距
   * @default 10
   */
  padding?: number
  /**
   * 分组样式
   */
  style?: GroupStyle
}

GroupStyle

interface GroupStyle {
  /**
   * 背景颜色
   */
  backgroundColor?: string
  /**
   * 边框颜色
   */
  borderColor?: string
  /**
   * 边框宽度
   */
  borderWidth?: number
  /**
   * 边框样式
   */
  borderStyle?: string
  /**
   * 边框圆角
   */
  borderRadius?: number
}

GroupAPI

interface GroupAPI {
  createGroup: (params: {
    id: string
    nodeIds: string[]
    config?: GroupConfig
    data?: Record<string, any>
  }) => string
  dissolveGroup: (groupId: string, recursive?: boolean) => boolean
  deleteGroup: (groupId: string) => boolean
  addNodesToGroup: (groupId: string, nodeIds: string[]) => boolean
  removeNodesFromGroup: (groupId: string, nodeIds: string[]) => boolean
  moveGroup: (groupId: string, position: NodePosition, isDelta?: boolean) => boolean
}

节点类型扩展

declare module '@knotx/core' {
  interface Node {
    /**
     * 所处的组
     */
    group?: string
    /**
     * type='group' 时，当前组配置
     */
    groupConfig?: GroupConfig
  }
}

默认配置

const DEFAULT_GROUP_PADDING = 10
const DEFAULT_GROUP_STYLE = {
  backgroundColor: 'rgba(100, 100, 100, 0.1)',
  borderColor: '#666',
  borderWidth: 1,
  borderStyle: 'solid',
  borderRadius: 4
}

分组渲染

插件提供了默认的分组渲染器，支持：

• 自动边界计算
• 自定义样式
• 递归分组支持
• 分层渲染

// 分组节点会自动使用 'group' 类型
function GroupNode({ node }) {
  // 自动渲染分组边界和样式
  return <div className="group-node">{/* 分组内容 */}</div>
}

层级管理

插件自动集成了层级管理功能：

• 分组节点渲染在子节点后面
• 支持嵌套分组的正确层级
• 自动计算节点层级

文件目录结构

packages/plugins-group/
├── src/
│   ├── group.tsx            # 分组插件主文件
│   └── index.ts             # 导出文件
├── dist/                    # 编译输出目录
├── CHANGELOG.md            # 变更日志
├── package.json            # 包配置
├── build.config.ts         # 构建配置
├── eslint.config.mjs       # ESLint 配置
└── tsconfig.json           # TypeScript 配置

许可证

MIT