@knotx/plugins-background

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

安装

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。

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

配置选项

BackgroundConfig

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

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

使用示例

基本用法

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

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

点状背景

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

线条背景

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

交叉背景

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

自定义样式

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 插件提供的变换状态和容器信息：

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