Canvas Plugin for Knotx
npm install @knotx/plugins-canvas画布插件,为 KnotX 提供画布容器、变换控制和交互功能。
``bash`
npm install @knotx/plugins-canvas
Canvas 插件是 KnotX 的核心插件之一,提供了画布容器、缩放、平移、滚动等基础功能。该插件基于 react-zoom-pan-pinch 库实现,为其他插件提供了变换状态和容器信息。
Canvas 插件通过以下方式实现画布功能:
1. 变换管理:使用 react-zoom-pan-pinch 库管理画布的缩放和平移
2. 事件系统:提供画布级别的事件监听和处理
3. 边缘滚动:支持拖拽到边缘时的自动滚动
4. 内容尺寸管理:跟踪和管理画布内容的尺寸
:提供基础插件架构
- @knotx/decorators:提供装饰器支持
- @knotx/react-zoom-pan-pinch:提供缩放和平移功能
- lodash-es:提供工具函数
- rxjs:提供响应式编程支持$3
- @knotx/plugins-history:提供历史记录功能
- react:React 框架支持API 文档
$3
#### Canvas
画布插件的主要类,继承自
BasePlugin。`typescript
export class Canvas extends BasePlugin<'canvas', CanvasConfig> {
name = 'canvas' as const
}
`$3
#### CanvasConfig
`typescript
export type CanvasConfig = ReactZoomPanPinchProps & {
defaultLocated?: DefaultLocatedOptions
}
`继承自
react-zoom-pan-pinch 的所有配置选项,并添加了:-
defaultLocated:默认定位选项$3
Canvas 插件向其他插件提供以下数据:
`typescript
interface PluginData {
canvas: {
transform: CanvasTransformState
rootElement: Element | null
contentSize: CanvasContentSize | undefined
updateContentSize: (contentSize: CanvasContentSize) => void
addListener: (event: CanvasEventType, listener: CanvasEventListener) => void
removeListener: (event: CanvasEventType, listener: CanvasEventListener) => void
edgeScroll: {
config: EdgeScrollConfig
setConfig: (config: Partial) => void
}
}
}
`$3
Canvas 插件提供以下工具方法:
`typescript
interface PluginTools {
canvas: {
scrollNodeIntoView: (params: ScrollNodeIntoViewOptions) => void
zoomIn: (params: { step?: number, animationTime?: number }) => void
zoomOut: (params: { step?: number, animationTime?: number }) => void
setTransform: (params: {
positionX: number
positionY: number
scale: number
animationTime?: number
}) => void
resetTransform: (params: { animationTime?: number }) => void
}
}
`$3
#### CanvasTransformState
`typescript
interface CanvasTransformState {
positionX: number
positionY: number
scale: number
previousScale: number
}
`#### CanvasContentSize
`typescript
interface CanvasContentSize {
width: number
height: number
}
`#### EdgeScrollConfig
`typescript
interface EdgeScrollConfig {
enabled: boolean
edgeSize: number
maxSpeed: number
}
`使用示例
$3
`typescript
import { Canvas } from '@knotx/plugins-canvas'const engine = new Engine({
plugins: [Canvas],
pluginConfig: {
canvas: {
minScale: 0.1,
maxScale: 3,
limitToBounds: false,
},
},
})
`$3
`typescript
const engine = new Engine({
plugins: [Canvas],
pluginConfig: {
canvas: {
minScale: 0.2,
maxScale: 5,
wheel: {
step: 0.1,
smoothStep: 0.006,
},
panning: {
allowLeftClickPan: false,
allowRightClickPan: true,
wheelPanning: true,
},
zoomAnimation: {
size: 0.1,
},
},
},
})
`$3
`typescript
const engine = new Engine({
plugins: [Canvas],
pluginConfig: {
canvas: {
// 基础配置
},
},
})// 启用边缘滚动
engine.callTool('canvas', 'edgeScroll.setConfig', {
enabled: true,
edgeSize: 100,
maxSpeed: 10,
})
`$3
`typescript
// 放大
engine.callTool('canvas', 'zoomIn', { step: 0.2, animationTime: 300 })// 缩小
engine.callTool('canvas', 'zoomOut', { step: 0.2, animationTime: 300 })
// 设置变换
engine.callTool('canvas', 'setTransform', {
positionX: 100,
positionY: 100,
scale: 1.5,
animationTime: 500,
})
// 重置变换
engine.callTool('canvas', 'resetTransform', { animationTime: 300 })
// 滚动节点到视野内
engine.callTool('canvas', 'scrollNodeIntoView', {
nodeId: 'node-1',
scale: 1.2,
block: 'center',
inline: 'center',
})
`$3
`typescript
// 获取画布数据
const canvasData = engine.getPluginData('canvas')// 添加点击事件监听
function handleClick(event: MouseEvent) {
console.log('Canvas clicked:', event)
}
canvasData.addListener('click', handleClick)
// 移除监听
canvasData.removeListener('click', handleClick)
`$3
`typescript
// 在其他插件中获取变换状态
class MyPlugin extends BasePlugin {
@inject.canvas.transform()
transform!: CanvasTransformState someMethod() {
console.log('Current scale:', this.transform.scale)
console.log('Position:', this.transform.positionX, this.transform.positionY)
}
}
`与其他插件的集成
$3
`typescript
import { Canvas } from '@knotx/plugins-canvas'
import { History } from '@knotx/plugins-history'const engine = new Engine({
plugins: [Canvas, History],
pluginConfig: {
canvas: {
minScale: 0.1,
maxScale: 3,
},
history: {
maxHistory: 50,
},
},
})
`$3
`typescript
import { Background } from '@knotx/plugins-background'
import { Canvas } from '@knotx/plugins-canvas'const engine = new Engine({
plugins: [Canvas, Background],
pluginConfig: {
canvas: {
minScale: 0.1,
maxScale: 3,
},
background: {
variant: 'dots',
color: '#ddd',
},
},
})
`文件目录结构
`
packages/plugins-canvas/
├── src/
│ ├── canvas.tsx # 主要实现文件
│ ├── transform.ts # 变换计算工具
│ ├── types.ts # 类型定义
│ └── index.ts # 导出文件
├── dist/ # 构建输出目录
├── package.json # 包配置文件
├── build.config.ts # 构建配置
├── tsconfig.json # TypeScript 配置
├── eslint.config.mjs # ESLint 配置
└── CHANGELOG.md # 更新日志
`$3
- canvas.tsx:包含 Canvas 插件的主要实现,包括变换管理、事件处理和工具方法
- transform.ts:变换计算相关的工具函数
- types.ts:TypeScript 类型定义
- index.ts:导出 Canvas 类和相关类型定义
高级功能
$3
`typescript
// 使用 transform.ts 中的工具函数
import { calculateTransform } from '@knotx/plugins-canvas/transform'const result = calculateTransform({
// 变换参数
})
`$3
`typescript
// 在插件中动态更新内容尺寸
class MyPlugin extends BasePlugin {
@inject.canvas.updateContentSize()
updateContentSize!: (size: CanvasContentSize) => void updateSize() {
this.updateContentSize({
width: 2000,
height: 1500,
})
}
}
`注意事项
1. 性能优化:Canvas 插件会频繁触发重渲染,建议在需要时才监听变换状态
2. 事件冒泡:Canvas 事件可能会与其他事件冲突,注意事件处理的优先级
3. 内存管理:及时移除不需要的事件监听器,避免内存泄漏
4. React 版本:确保 React 版本与
react-zoom-pan-pinch` 兼容MIT