@knotx/plugins-background

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

安装

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

概述

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

实现原理

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

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

依赖关系

$3


- @knotx/core：提供基础插件架构
- @knotx/decorators：提供装饰器支持
- @knotx/jsx：提供 JSX 支持

$3

- @knotx/plugins-canvas：获取画布变换状态和容器信息

API 文档

$3

#### Background

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

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

$3

#### BackgroundConfig

`typescript
export type BackgroundConfig = Omit

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

#### BackgroundVariant

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

使用示例

$3

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

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

$3

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

$3

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

$3

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

$3

`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,
},
},
},
})
`

与其他插件的集成

$3

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 # 更新日志
``

$3

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

注意事项

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

许可证

MIT