ICanvas - 入门教程
画布属性方法
ICanvas是画布的核心类，负责管理画布上下文、图形元素、事件处理等。
属性
基础属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
canvas | CanvasContext | null | null | Canvas上下文对象 |
ctx | CanvasRenderingContext2D | null | null | Canvas 2D渲染上下文 |
canvasNode | NodeInfo | null | null | Canvas节点信息 |
width | number | 0 | 画布宽度 |
height | number | 0 | 画布高度 |
boxWidth | number | 0 | 画布容器宽度 |
boxHeight | number | 0 | 画布容器高度 |
dpr | number | 1 | 设备像素比 |
id | string | random | 画布唯一标识符 |
component | any | null | null | 组件实例,选项式传this,组合式传proxy |
canvasId | string | - | Canvas元素ID |
事件配置属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
checkPointInHitEvents | CanvasEventType[] | ['click'] | 命中检测事件范围 |
注意
checkPointInHitEvents用于控制哪些事件会进行命中检测，默认只对click事件进行检测，全放开会有性能风险。
私有属性
| 属性名 | 类型 | 说明 |
|---|---|---|
touch_x | number | 触摸起始X坐标 |
touch_y | number | 触摸起始Y坐标 |
touch_move_x | number | 触摸移动X坐标 |
touch_move_y | number | 触摸移动Y坐标 |
touch_end_x | number | 触摸结束X坐标 |
touch_end_y | number | 触摸结束Y坐标 |
touch_end_len_x | number | 触摸结束相对起始X距离 |
touch_end_len_y | number | 触摸结束相对起始Y距离 |
touch_move_len_x | number | 触摸移动相对上次X距离 |
touch_move_len_y | number | 触摸移动相对上次Y距离 |
touchStartTime | number | 触摸开始时间 |
touchEndTime | number | 触摸结束时间 |
方法
构造函数
constructor(config: ICanvasOptional)
创建画布实例
config: 画布配置对象canvasId: Canvas元素IDcomponent: 组件实例
初始化方法
init(): Promise<any | null>
初始化画布，获取Canvas上下文和尺寸信息
- 返回值: Promise，resolve时返回画布实例
图形管理方法
addShape(shape: ShapeType): ICanvas
添加图形到画布
shape: 要添加的图形实例- 返回值: 当前画布实例
removeShape(shape: ShapeType): ICanvas
从画布移除图形
shape: 要移除的图形实例- 返回值: 当前画布实例
渲染方法
clear(): ICanvas
清空画布
- 返回值: 当前画布实例
render(): ICanvas
渲染所有图形到画布
- 返回值: 当前画布实例
update(): ICanvas
更新画布，只渲染需要更新的图形
- 返回值: 当前画布实例
图像导出方法
getImage(): Promise<string>
导出画布为图片
- 返回值:
Promise<string>，图片路径或URL
平台差异
- WEB/H5: 返回Blob URL
- APP: 返回临时文件路径
- 小程序: 返回临时文件路径
事件处理方法
bindEvent(eventType: any): void
绑定外部事件到画布，实现事件分发
eventType: 事件对象
支持的事件类型
- 触摸事件: touchstart, touchmove, touchend, touchcancel
- 鼠标事件: mousedown, mousemove, mouseup, mouseleave
- 转换事件: down, move, up, click, dbclick, longpress, cancel
addEventListener(eventName: CanvasEventType, listener: IEventListener): ICanvas
添加画布事件监听器
eventName: 事件类型listener: 事件处理函数- 返回值: 当前画布实例
removeEventListener(eventName: CanvasEventType, listener: IEventListener): ICanvas
移除画布事件监听器
eventName: 事件类型listener: 事件处理函数- 返回值: 当前画布实例
事件处理流程
- 事件绑定: 通过
bindEvent方法绑定外部事件 - 事件转换: 将触摸/鼠标事件转换为统一的事件格式
- 命中检测: 根据
checkPointInHitEvents配置进行命中检测 - 事件分发: 将事件分发给相应的图形元素
- 拖拽处理: 自动处理可拖拽图形的移动
注意事项
- 画布初始化是异步的，需要等待
init()完成 - 命中检测会影响性能，建议只对必要的事件开启
- 拖拽功能会自动处理，无需手动实现
- 图片导出在不同平台返回格式不同
- 事件系统支持冒泡机制
- 画布会自动处理设备像素比适配