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

# @knotx/plugins-background

背景插件，为 KnotX 画布提供可视化背景模式。

## 安装

```bash
npm install @knotx/plugins-background
```

## 概述

Background 插件为 KnotX 画布提供了多种背景模式，包括点状、线状和交叉模式。该插件可以增强用户体验，提供网格化的视觉参考。

## 实现原理

Background 插件通过 SVG 模式定义和重复平铺的方式实现背景效果。插件在 Background 层渲染，位于所有其他元素之下。主要原理：

1. **SVG 模式生成**：使用 SVG `<defs>` 和 `<pattern>` 创建可重复的背景图案
2. **动态样式计算**：根据画布变换状态（缩放、平移）动态调整背景的偏移和间隙
3. **图案类型支持**：支持点状（dots）、线状（lines）和交叉（cross）三种图案

## 依赖关系

### 核心依赖
- `@knotx/core`：提供基础插件架构
- `@knotx/decorators`：提供装饰器支持
- `@knotx/jsx`：提供 JSX 支持

### 插件依赖
- `@knotx/plugins-canvas`：获取画布变换状态和容器信息

## API 文档

### 主要类

#### Background

背景插件的主要类，继承自 `BasePlugin`。

```typescript
export class Background extends BasePlugin<'background', BackgroundConfig> {
  name = 'background' as const
}
```

### 配置选项

#### BackgroundConfig

```typescript
export type BackgroundConfig = Omit<BackgroundProps, 'id'>

export interface BackgroundProps {
  /** 背景颜色 */
  color?: string
  /** 背景的底色 */
  bgColor?: string
  /** 图案重复之间的间隙 */
  gap?: number | [number, number]
  /** 单个图案元素的大小 */
  size?: number
  /** 图案的偏移量 */
  offset?: number | [number, number]
  /** 线条模式的线宽 */
  lineWidth?: number
  /** 图案变体类型 */
  variant?: BackgroundVariant
  /** 应用于容器的样式 */
  style?: Record<string, any>
}
```

#### BackgroundVariant

```typescript
export enum BackgroundVariant {
  Lines = 'lines',
  Dots = 'dots',
  Cross = 'cross',
}
```

## 使用示例

### 基本用法

```typescript
import { Background, BackgroundVariant } from '@knotx/plugins-background'

const engine = new Engine({
  plugins: [Background],
  pluginConfig: {
    background: {
      variant: BackgroundVariant.Dots,
      color: '#ddd',
      gap: 20,
    },
  },
})
```

### 点状背景

```typescript
const engine = new Engine({
  plugins: [Background],
  pluginConfig: {
    background: {
      variant: BackgroundVariant.Dots,
      color: '#999',
      bgColor: '#f5f5f5',
      gap: 20,
      size: 2,
    },
  },
})
```

### 线条背景

```typescript
const engine = new Engine({
  plugins: [Background],
  pluginConfig: {
    background: {
      variant: BackgroundVariant.Lines,
      color: '#ddd',
      lineWidth: 1,
      gap: 20,
    },
  },
})
```

### 交叉背景

```typescript
const engine = new Engine({
  plugins: [Background],
  pluginConfig: {
    background: {
      variant: BackgroundVariant.Cross,
      color: '#ddd',
      lineWidth: 1,
      gap: 20,
      size: 10,
    },
  },
})
```

### 自定义样式

```typescript
const engine = new Engine({
  plugins: [Background],
  pluginConfig: {
    background: {
      variant: BackgroundVariant.Dots,
      color: '#4A90E2',
      bgColor: '#F0F4F8',
      gap: [30, 20], // 不同的水平和垂直间隙
      offset: [10, 5], // 偏移量
      style: {
        opacity: 0.8,
      },
    },
  },
})
```

## 与其他插件的集成

### 与 Canvas 插件集成

Background 插件依赖 Canvas 插件提供的变换状态和容器信息：

```typescript
import { Background, BackgroundVariant } from '@knotx/plugins-background'
import { Canvas } from '@knotx/plugins-canvas'

const engine = new Engine({
  plugins: [Canvas, Background],
  pluginConfig: {
    canvas: {
      // canvas 配置
    },
    background: {
      variant: BackgroundVariant.Dots,
      color: '#ddd',
    },
  },
})
```

## 文件目录结构

```
packages/plugins-background/
├── src/
│   ├── background.tsx          # 主要实现文件
│   └── index.ts               # 导出文件
├── dist/                      # 构建输出目录
├── package.json              # 包配置文件
├── build.config.ts           # 构建配置
├── tsconfig.json             # TypeScript 配置
├── eslint.config.mjs         # ESLint 配置
└── CHANGELOG.md              # 更新日志
```

### 核心文件说明

- **background.tsx**：包含 Background 插件的主要实现，包括 SVG 模式生成、样式计算和渲染逻辑
- **index.ts**：导出 Background 类和相关类型定义

## 注意事项

1. **性能优化**：Background 插件使用 SVG 模式，性能良好，但在极大的画布上可能需要考虑性能优化
2. **浏览器兼容性**：依赖 SVG 特性，需要考虑目标浏览器的兼容性
3. **样式层级**：Background 插件渲染在 Background 层，确保在所有其他元素之下
4. **响应式设计**：背景会根据画布的变换状态自动调整，无需手动处理

## 许可证

MIT