@knotx/plugins-canvas-scrollbar

画布滚动条插件，为画布提供自定义滚动条功能。

安装

npm install @knotx/plugins-canvas-scrollbar

基本概述

@knotx/plugins-canvas-scrollbar 是 KnotX 框架的画布滚动条插件，为画布提供自定义的滚动条功能。当画布内容超出可视区域时，会自动显示滚动条，用户可以通过拖拽滚动条来快速导航到画布的不同区域。

实现原理

该插件通过监听画布的变换状态和内容尺寸，动态计算滚动条的位置和大小：

1. 滚动条计算：基于画布内容尺寸、可视区域和变换状态计算滚动条的位置和大小
2. 交互处理：支持点击滚动条轨道和拖拽滚动条滑块
3. 自动隐藏：支持配置滚动条的自动隐藏延迟时间
4. 样式定制：支持自定义滚动条的样式和尺寸

依赖插件

该插件依赖以下包：

• @knotx/core - 核心功能
• @knotx/decorators - 装饰器支持
• @knotx/plugins-canvas - 画布插件（peer dependency）
• @knotx/jsx - JSX 支持（peer dependency）
• react - React 框架（peer dependency）

API 使用

基本使用

import { CanvasScrollbar } from '@knotx/plugins-canvas-scrollbar'

// 创建滚动条插件实例
const scrollbar = new CanvasScrollbar()

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

配置选项

const scrollbar = new CanvasScrollbar().init({
  style: {
    track: {
      backgroundColor: '#f0f0f0',
      borderRadius: '4px'
    },
    thumb: {
      backgroundColor: '#999',
      borderRadius: '4px'
    }
  },
  size: 12,
  offset: 5,
  minThumbSize: 40,
  hideTimeout: 2000
})

完整示例

import { Engine } from '@knotx/core'
import { Canvas } from '@knotx/plugins-canvas'
import { CanvasScrollbar } from '@knotx/plugins-canvas-scrollbar'

const engine = new Engine()

// 注册画布插件
engine.use(new Canvas())

// 注册滚动条插件
engine.use(new CanvasScrollbar().init({
  style: {
    track: {
      backgroundColor: 'rgba(0, 0, 0, 0.1)',
      borderRadius: '6px'
    },
    thumb: {
      backgroundColor: 'rgba(0, 0, 0, 0.3)',
      borderRadius: '6px'
    }
  },
  size: 10,
  offset: 8,
  minThumbSize: 50,
  hideTimeout: 3000
}))

配置接口

CanvasScrollbarConfig

interface CanvasScrollbarConfig {
  /**
   * 轨道以及滑块的css样式
   */
  style?: ScrollbarStyle
  /**
   * 轨道以及滑块的宽度/高度
   */
  size?: number
  /**
   * 距离边界的距离
   */
  offset?: number
  /**
   * 滑块的最小宽度/高度
   */
  minThumbSize?: number
  /**
   * 滚动条消失延迟
   */
  hideTimeout?: number
}

ScrollbarStyle

interface ScrollbarStyle {
  track: CSSProperties
  thumb: CSSProperties
}

默认配置

const defaultConfig = {
  style: {
    track: {},
    thumb: {}
  },
  offset: 3,
  size: 8,
  minThumbSize: 30,
  hideTimeout: 0
}

交互功能

滚动条拖拽

• 支持拖拽水平和垂直滚动条滑块
• 实时更新画布视图位置
• 平滑的拖拽体验

轨道点击

• 支持点击滚动条轨道快速跳转
• 自动计算目标位置
• 平滑的滚动动画

自动显示/隐藏

• 鼠标进入画布区域时显示滚动条
• 鼠标离开画布区域时延迟隐藏滚动条
• 支持配置隐藏延迟时间

文件目录结构

packages/plugins-canvas-scrollbar/
├── src/
│   ├── canvas-scrollbar.tsx  # 画布滚动条插件主文件
│   └── index.ts             # 导出文件
├── dist/                    # 编译输出目录
├── CHANGELOG.md            # 变更日志
├── package.json            # 包配置
├── build.config.ts         # 构建配置
├── eslint.config.mjs       # ESLint 配置
└── tsconfig.json           # TypeScript 配置

许可证

MIT