npm package: @knotx/plugins-group
Description: Group Plugin for Knotx
Author: boenfu
Latest version: 0.5.10

# @knotx/plugins-group

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

## 安装

```bash
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 使用

### 基本使用

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

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

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

### 创建分组

```typescript
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: '自定义分组' }
})
```

### 分组操作

```typescript
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)
```

### 完整示例

```typescript
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

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

### GroupStyle

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

### GroupAPI

```typescript
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
}
```

## 节点类型扩展

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

## 默认配置

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

## 分组渲染

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

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

```tsx
// 分组节点会自动使用 '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