# canvas-designer

**Repository Path**: swzj/canvas-designer

## Basic Information

- **Project Name**: canvas-designer
- **Description**: 一个扩展 Canvas 2D 上下文的 HTML5 Canvas JavaScript 框架
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 3
- **Created**: 2023-03-16
- **Last Updated**: 2024-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Canvas

## README

# Canvas-Designer 画布设计器引擎

一个扩展 [Canvas 2D 上下文](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D) 的 HTML5 Canvas JavaScript 框架

支持画布的拖动、缩放、自适应、1:1、历史状态记录（撤销，回退）、导出图片；  
画布可添加节点并支持对节点的选择、拖动、缩放、旋转、编组、添加事件监听器、导出图片等操作。

## 安装及使用

```bash
npm i @xsyx/canvas-designer@latest

import Designer from "@xsyx/canvas-designer";
```

```js
// 创建画布（除了 container 其他属性皆为可选，示例值为默认值）
const stage = new Designer.Stage({
  container: '#container', // container 元素选择器或 dom 元素
  width: 300,
  height: 150,
  fps: 144, // 每秒帧数（绘制函数每秒调用最大次数），默认 144
  autoSize: true, // 根据 container 元素自动设置画布宽高
  scaleRatio: 1.1, // 缩放比率
  minScale: 0.02, // 最小缩放比例
  maxScale: 256, // 最大缩放比例
  padding: null, // 内边距（控制视口）[上, 右, 下, 左]
  scrollbar: true, // 画布是否有滚动条
  eventEnabled: true, // 画布是否启用事件
  draggable: true, // 画布是否可拖动
  scaleable: true, // 画布是否可缩放
  selectable: true, // 是否可选择节点
  regionable: true, // 是否可框选节点
  transformable: true, // 是否可转换节点
  stackable: true, // 是否可堆叠节点，仅对拖动节点有效，有编组节点时慎用！
  recordable: true, // 是否开启内置历史状态记录（撤销，回退）
  guidesable: true, // 是否开启内置辅助线功能
  edgeable: true, // 是否开启节点连线功能

  // 网格配置
  grid: false, // 布尔开关
  // grid: {
  //   size: 20, // 网格大小
  //   type: 'dot', // 网格类型：dot 点状 | line 线状
  //   color: '#ababab', // 网格颜色
  //   radius: 2, // 点状圆形半径  
  // },

  // 节点连线默认配置
  edgeConfig: {
    type: 'bezier', // 类型 默认：贝塞尔曲线
    color: '#9CA3AF', // 颜色
    dangerColor: '#EF4444', // 警告颜色
    disabledColor: '#D1D5DB', // 禁用颜色
    lineWidth: 2, // 线宽
    lineDash: [], // 描述虚线模式的线和间隙的交替长度
    effect: undefined, // 效果 默认：无
  },

  // 开发者模式配置
  devMode: false, // 布尔开关
  // devMode: {
  //   // 画布轮廓配置 支持布尔开关
  //   outline: {
  //     showReal: true, // 画布实际绘制区域轮廓
  //     showGrid: true, // 画布网格坐标轮廓
  //     showView: true, // 画布视口轮廓
  //   },
  // },
});

// 画布绘制事件
stage.on('draw', function () {
  // todo...
});
// 节点选择事件
stage.on('select', function (nodes) {
  console.log('nodes: ', nodes); // 已选节点
});
// 鼠标移动事件
stage.on('mousemove', function (evt) {});
// 键盘按下事件
stage.on('keydown', function (evt) {});
// 客户端键盘按下事件
stage.on('window.keydown', function (e) {});
// ...

// 画布自适应
stage.adaptive();

// 创建一个图片节点
const image = new Designer.Image({
  x: 0,
  y: 0,
  autoSize: true, // 根据图片原始尺寸设置宽高属性
  name: 'swzj', // 节点名
  src: 'https://blog.swzj.fun/logo.png', // 图片src
  draggable: true, // 可拖动
});
// 将图片节点添加到画布
stage.add(image);

// 查找节点（根据name）（类似css选择器：#id, .name）
const swzj = stage.findOne('.swzj');
// 节点转换事件：缩放、旋转
swzj.on('transform', function () {
  // todo...
});
// 鼠标移动事件
swzj.on('mousemove', function (evt) {});
// ...

// 画布转换为 data URI
console.log('data URI：', stage.toDataURL());
// 画布转换为 Blob 对象
setTimeout(async () => {
  const blob = await stage.toBlob();
  const image = document.createElement('img');
  const url = URL.createObjectURL(blob);
  image.onload = () => URL.revokeObjectURL(url);
  image.src = url;
  document.body.appendChild(image);
}, 0);

// 节点转换为 data URI
console.log('data URI：', swzj.toDataURL());
// 节点转换为 Blob 对象
await swzj.toBlob();
```

## 更新日志

### xxxx-xx-xx vx.x.x

- 新增
  - XXX 功能
- 优化
  - XXX 功能
- 修复
  - XXX BUG

### 2023-11-23 v0.1.7-6

- 优化
  - 若干性能优化
- 修复
  - 节点连线预检修改节点信息无效 BUG

### 2023-11-17 v0.1.7-5

- 新增
  - 画布 devMode 配置：开发者模式
    - 布尔类型控制开关
    - 配置对象：
      ```js
      devMode: {
        // 画布轮廓配置 支持布尔开关
        outline: {
          showReal: true, // 画布实际绘制区域轮廓
          showGrid: true, // 画布网格坐标轮廓
          showView: true, // 画布视口轮廓
        },
      },
      ```

### 2023-11-16 v0.1.7-4

- 新增
  - 画布 节点选择事件: select 及 节点连线选择事件: edgeSelect 第二个参数: event 事件源
    - stage.on('select', function (nodes, event) {})
    - stage.on('edgeSelect', function (edges, event) {})
    - event 可能的值有: 'select', 'region', 'setSelected', 'setSchema', 'createStage'

### 2023-11-16 v0.1.7-2~v0.1.7-3

- 优化
  - 拖动画布滚动条时保留拖动开始时的长度，提升用户交互体验

### 2023-11-15 v0.1.7-1

- 修复
  - 不存在画布实际绘制区域时异常 BUG

### 2023-11-15 v0.1.7-0

- 新增
  - 画布 padding 配置：内边距（控制视口），默认无内边距
    - 数字数组类型，[上, 右, 下, 左]
  - 画布 scrollbar 配置：画布是否有滚动条，默认 true
    - 布尔类型
  - 画布 setConfig 方法：画布配置更新
    - 内部会调用画布数据保存方法，避免画布重绘等逻辑负担
    - 谨慎使用，可对 stage 实例所有属性进行覆写，如修改了关键属性可能会导致画布数据出错影响绘制
- 优化
  - 画布框选交互体验优化
    - 框选时鼠标临近或超出画布边缘将向该边方向移动画布

### 2023-11-10 v0.1.6

- KOKOMI 逻辑编排一期

### 2023-11-07 v0.1.6-37

- 优化
  - 画布 handleMove 移动时，优化画布数据更新及绘制
    - 触发 hover 事件
    - 框选中状态 触发框选事件
    - 转换器旋转中状态 触发选择器旋转事件
    - 转换器调整大小状态 触发选择器调整大小事件
    - 鼠标左键按下 且 有可拖动节点 触发节点拖动事件

### 2023-11-07 v0.1.6-36

- 修复
  - 节点 setZIndex 方法：设置层级关系，没有兄弟节点时异常 BUG

### 2023-11-06 v0.1.6-35

- 新增
  - 画布 original 方法：原始像素显示，第一个参数：fitPixelRatio: 适配设备像素比，默认 false

### 2023-11-06 v0.1.6-34

- 优化
  - 框选中状态进行画布移动时，优化框选矩形及框选节点的绘制

### 2023-11-06 v0.1.6-33

- 修复
  - 删除节点且节点有连线时，已选节点 selectedNodes 数据异常 BUG

### 2023-11-03 v0.1.6-32

- 新增
  - Logic 类静态方法 measureWidth 第二个配置参数: { diffSide = true }
    - diffSide 宽度计算区分不同边的宽度

### 2023-11-03 v0.1.6-31

- 优化
  - 文本绘制超出省略号始终保留首字
  - 不可堆叠节点状态，可拖动节点拖动时就已重叠时忽略拖动节点

### 2023-11-01 v0.1.6-29~v0.1.6-30

- 优化
  - 若干交互优化

### 2023-11-01 v0.1.6-28

- 优化
  - 触控板缩放体感优化

### 2023-10-31 v0.1.6-27

- 新增
  - Logic 类静态方法 measureWidth: 测量逻辑块宽度

### 2023-10-31 v0.1.6-24~v0.1.6-26

- 优化
  - 拖拽放置节点时的性能优化

### 2023-10-30 v0.1.6-23

- 优化
  - 画布拖动和缩放体感优化

### 2023-10-28 v0.1.6-22

- 调整
  - 规范化坐标体系
    - offsetCoord: 画布相对坐标，相对于 canvas 节点中的坐标
    - gridCoord: 画布网格坐标，在 canvas 坐标系中的坐标
    - absoluteCoord: 画布绝对坐标，以父级 designer-container 元素为基准的绝对坐标
    - fixedCoord: 相对于浏览器窗口的坐标

### 2023-10-27 v0.1.6-21

- 新增
  - 画布网格配置 radius: 点状圆形半径，默认 2

### 2023-10-27 v0.1.6-19~v0.1.6-20

- 优化
  - 画布绘制考虑 devicePixelRatio: 当前显示设备的物理像素分辨率与 CSS 像素分辨率之比
    - 解决高分辨率屏幕画布绘制模糊问题

### 2023-10-25 v0.1.6-18

- 新增
  - 画布 save 方法：画布数据保存（触发转换器更新、画布重绘、记录画布历史状态）
    - 使用场景：使用非画布提供的方法对画布内节点数据进行处理后，执行此方法来保存画布数据
  - 画布 edgeNodeGroups getter：获取节点连线关联的节点分组
    - 二维数组，每个数组中的节点是有连线进行关联的节点集合，若有没有被连线的节点，将存在于最后一项中
- 修复
  - 自定义 edgePrecheck 节点连线预检函数内部异常时导致画布动画失效 BUG

### 2023-10-21 v0.1.6-17

- 优化
  - Logic 节点锚点 visible 为 false 时，绘制表现为透明

### 2023-10-21 v0.1.6-12~v0.1.6-16

- 调整
  - 节点、节点连线、锚点绘制层级及判定优先级
    - 节点（最高优先级）
    - 节点连线（高优先级）
    - 锚点（低优先级）
- 修复
  - 若干 BUG

### 2023-10-19 v0.1.6-11

- 优化
  - 节点 customData 属性不再担心数据丢失问题，可正常使用 events, image, parent 三个内置属性
  - 节点区分 是否带锚点状态 与 空锚点状态

### 2023-10-18 v0.1.6-10

- 修复
  - 节点连线删除时画布渲染出现问题 BUG
  - 内置粘贴功能不触发 select 事件 BUG

### 2023-10-16 v0.1.6-9

- 新增
  - 画布 setEdge(edgeId, overrideConfig) 方法：设置节点连线
- 优化
  - 获取节点连线集数据性能优化

### 2023-10-16 v0.1.6-8

- 修复
  - 画布 clearSelect 方法不触发 select 及 edgeSelect 事件 BUG

### 2023-10-16 v0.1.6-7

- 优化
  - 图片渲染错误捕获，防止影响画布正常绘制及操作

### 2023-10-14 v0.1.6-6

- 新增
  - 画布 stackable 属性：是否可堆叠节点，默认为 true，仅对拖动节点有效，有编组节点时慎用！
    - 为 false 时拖动节点时节点与画布可见子节点有堆叠时，节点拖动结束时将会恢复到拖动开始时的位置
  - 画布 clearSelect 方法：清理画布已选节点及连线

### 2023-10-14 v0.1.6-5

- 新增
  - 画布 allAction 事件监听，可监听所有画布行为，原有 action 监听范围不包括画布拖动、缩放、移动、节点拖动
    - stage.on('allAction', function (stage) {});

### 2023-10-12 v0.1.6-4

- 新增
  - 主动触发画布快捷键行为 action: 'undo'|'redo'|'delete'|'selectAll'|'increaseScale'|'decreaseScale'
    - stage.actionHotkey(action);
  - 快捷键行为预检 stage.hotkeyPrecheck = function (action, ...args) {};
    - action: 'undo'|'redo'|'delete'|'selectAll'|'increaseScale'|'decreaseScale'|'copy'|'cut'|'paste'
    - 支持 Promise，返回值为 false 将阻断内置快捷键行为
    - paste 行为剩余参数为 nodes
  - 画布 hotkey 事件监听
    - action: 'undo'|'redo'|'delete'|'selectAll'|'increaseScale'|'decreaseScale'|'copy'|'cut'|'paste'
    - stage.on('hotkey', function (action) {});

### 2023-10-10 v0.1.6-3

- 新增
  - 节点连线添加效果类型选项 effect 属性
    - ant: 蚂蚁爬行效果
    - dashed: 虚线效果
    - arrows: 箭头效果
    - blink: 闪烁效果
  - 逻辑块节点无锚点状态占位文本
- 优化
  - 逻辑块节点名称样式优化

### 2023-10-04 v0.1.6-2

- 优化
  - 平滑节点连线的锚点出入
  - 节点与连线的 hover 判定精准度
  - 逻辑块节点样式优化

### 2023-09-11 v0.1.6-1

- 新增
  - Logic 节点锚点数据添加 logicType 属性
    - port: 端口（默认）
    - event: 事件
    - listener: 监听

### 2023-09-09 v0.1.6-0

- 新增
  - 全局配置节点轮廓线宽：Designer.outlineLineWidth = 1

### 2023-09-09 v0.1.5

- 优化
  - 扩大锚点 hover 判定范围，重叠时取与当前鼠标坐标距离最近的锚点