Butterfly项目画布(Canvas)功能详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00104/article/details/148524065

Butterfly项目画布(Canvas)功能详解

butterfly 🦋Butterfly，A JavaScript/React/Vue2 Diagramming library which concentrate on flow layout field. (基于JavaScript/React/Vue2的流程图组件) 项目地址: https://gitcode.com/gh_mirrors/butt/butterfly

概述

Butterfly是一个功能强大的可视化图形库，其中的Canvas（画布）组件是整个可视化系统的核心容器。本文将全面解析Butterfly中Canvas组件的功能特性、配置选项和使用方法，帮助开发者更好地理解和运用这一强大的可视化工具。

基础配置

初始化Canvas

创建一个Canvas实例是使用Butterfly的第一步，以下是基本配置示例：

let canvas = new Canvas({
  root: domElement,  // 必填，DOM容器元素
  zoomable: true,    // 可选，是否可缩放
  moveable: true,    // 可选，是否可平移
  draggable: true,   // 可选，节点是否可拖动
  linkable: true,    // 可选，是否可连接节点
  disLinkable: true, // 可选，是否可断开连接
  theme: {           // 可选，主题配置
    // 详细主题配置见下文
  }
});

核心属性解析

root (必填)
- 类型：DOM元素
- 说明：作为Canvas渲染的容器，必须具有明确的宽高尺寸
交互控制属性
- zoomable：控制画布是否支持缩放操作
- moveable：控制画布是否支持平移操作
- draggable：控制节点是否可拖动
- linkable：控制节点是否可连接
- disLinkable：控制节点连接是否可断开
布局配置
- layout：定义初始布局算法
- layoutOptions：布局算法的参数配置

主题定制

Butterfly提供了丰富的主题定制选项，可以精细控制画布中各个元素的样式和行为。

连线(Edge)配置

theme: {
  edge: {
    shapeType: 'Bezier', // 线条类型：Bezier/Flow/Straight等
    arrow: true,         // 是否显示箭头
    arrowPosition: 0.5,  // 箭头位置(0-1)
    defaultAnimate: false // 是否启用默认动画
  }
}

Butterfly支持多种线条类型，包括：

贝塞尔曲线(Bezier)
折线(Flow)
直线(Straight)
曼哈顿路由线(Manhattan)
高级贝塞尔曲线(AdvancedBezier)

锚点(Endpoint)配置

theme: {
  endpoint: {
    limitNum: 10,       // 单个锚点最大连接数
    expandArea: {       // 扩大连线热区
      left: 10, right: 10, 
      top: 10, bottom: 10
    }
  }
}

画布行为配置

theme: {
  autoFixCanvas: {      // 边缘自动延展
    enable: false,
    autoMovePadding: [20, 20, 20, 20]
  },
  zoomGap: 0.001        // 缩放灵敏度
}

核心API详解

数据渲染

draw(data, callback)
- 异步渲染画布数据
- 参数：包含节点、连线、分组的数据对象
- 回调函数在渲染完成后执行
redraw(data, callback)
- 清空画布后重新渲染
- 适用于数据完全更新的场景

布局控制

autoLayout(type, options)

手动触发自动布局
支持多种布局算法
可通过options参数自定义布局行为

元素操作

节点操作
- addNode() / addNodes()：添加单个/多个节点
- removeNode() / removeNodes()：删除节点
- getNode()：根据ID获取节点
连线操作
- addEdge() / addEdges()：添加连线
- removeEdge() / removeEdges()：删除连线
- getNeighborEdges()：获取相邻连线
分组操作
- addGroup()：添加分组
- removeGroup()：删除分组
- getGroup()：获取分组

视图控制

缩放与平移
- zoom(scale)：手动设置缩放级别
- move(position)：手动设置画布位置
- setZoomable() / setMoveable()：动态控制交互
聚焦功能
- focusNodeWithAnimate()：聚焦特定节点
- focusCenterWithAnimate()：聚焦整个画布

实用工具

坐标转换
- terminal2canvas()：屏幕坐标转画布坐标
- canvas2terminal()：画布坐标转屏幕坐标
历史记录
- undo() / redo()：撤销/重做操作
- 支持自定义操作队列管理

高级功能

框选模式

canvas.setSelectMode(true, ['node'], 'include');

支持三种框选模式：

include：完全包含才选中
touch：触碰即选中
senior：智能识别选择方向

网格与辅助线

网格背景

canvas.setGridMode(true, {
  isAdsorb: true,  // 启用吸附功能
  theme: {
    shapeType: 'line',
    gap: 20
  }
});

辅助线

canvas.setGuideLine(true, {
  adsorp: { enable: true, gap: 5 }
});

缩略图与导出

缩略图
```
canvas.setMinimap(true, options);
```

导出图片

canvas.save2img({type: 'png'})
  .then(dataUrl => {
    // 处理导出的图片数据
  });

事件系统

Butterfly提供了完善的事件系统，可以监听画布上的各种交互行为：

canvas.on('system.node.click', (data) => {
  console.log('节点被点击', data);
});

canvas.on('system.link.connect', (data) => {
  console.log('连线建立', data);
});

主要事件类型包括：

画布交互：点击、缩放
节点操作：添加、删除、移动
连线操作：连接、断开、重连
分组操作：创建、删除、成员变更
拖拽事件：开始、移动、结束

最佳实践

性能优化
- 批量操作使用addNodes()/addEdges()而非单个添加
- 复杂场景考虑使用requestAnimationFrame分批渲染
交互设计
- 合理设置锚点连接限制，避免过度连接
- 使用聚焦功能引导用户注意力
可视化增强
- 利用主题配置统一视觉风格
- 适当启用动画效果提升用户体验