LeaferJS 文档

概览

LeaferJS 官网

LeaferJS 是一款好用的 Canvas 引擎，革新的开发体验，可用于高效绘图、UI 交互（小游戏、互动应用、组态）、图形编辑。

提供了丰富的 UI 绘图元素，和开箱即用的功能，如自动布局、图形编辑、SVG 导出等，方便与 PS、 Figma、Sketch 等产品进行对接。并为跨平台开发提供了统一的交互事件，如拖拽、旋转、缩放手势等。

易用：API 和文档强调“易学易用”，以 JavaScript / Canvas 思路构建；提供“创建应用/创建元素/事件处理”等循序教程；支持用 tag/JSON 方式组织场景树，适合做编辑器数据结构（可序列化/可回放）。
性能：拥有多种性能优化机制，哪怕同屏渲染十万个图形，操作起来依然像德芙一样丝般顺滑
跨端：同一套核心 API 覆盖多端运行环境，包括 Web、Web Worker 渲染、Node.js 渲染、以及小程序（微信）适配；并提供“跨平台核心包”和插件生态以减少端间差异。

1. 工具介绍

LeaferJS 是一个好用的 Canvas 引擎，专注于提供高性能、易用的 2D 图形绘制能力。它基于 Canvas API 构建，为开发者提供了更简洁、更强大的图形绘制接口，适用于创建各种交互式图形应用、游戏、数据可视化等场景。

主要特性

高性能渲染：优化的 Canvas 渲染引擎，支持大量图形元素的高效绘制
简洁易用的 API：提供直观的面向对象编程接口，降低 Canvas 开发难度
丰富的图形元素：内置多种基本图形（矩形、圆形、路径等）和复合图形
强大的交互能力：支持拖拽、缩放、旋转等交互式操作
响应式设计：支持自适应窗口大小的应用开发
模块化架构：按需引入模块，减少打包体积
TypeScript 支持：提供完整的类型定义，支持 TypeScript 开发

2. 安装

NPM 安装

bash

# 安装核心包
npm install leafer-ui

# 或者使用 yarn
yarn add leafer-ui

CDN 引入

html

<!-- 引入 LeaferJS -->
<script src="https://unpkg.com/leafer-ui@latest/dist/leafer.min.js"></script>

3. 基本使用

创建一个简单的图形

javascript

import { Leafer, Rect } from 'leafer-ui'

// 创建一个自适应窗口的交互应用
const leafer = new Leafer({ view: window })

// 创建一个可以被拖拽的矩形
const rect = new Rect({
  x: 100,
  y: 100,
  width: 200,
  height: 200,
  fill: '#32cd79',
  draggable: true
})

leafer.add(rect)

基本配置选项

创建 Leafer 实例时，可以配置以下选项：

选项	类型	描述	默认值
view	HTMLElement Window	渲染容器	无（必填）
width	number	画布宽度	容器宽度
height	number	画布高度	容器高度
fill	string	背景颜色	透明
interactive	boolean	是否开启交互	true
resize	boolean	是否自动调整大小	true

4. 核心功能

4.1 图形元素

LeaferJS 提供了多种内置图形元素：

Rect：矩形
Circle：圆形
Ellipse：椭圆
Line：线条
Path：路径
Text：文本
Image：图片

4.2 图形属性

所有图形元素都支持以下基本属性：

位置属性：x, y
尺寸属性：width, height, radius（圆形）
样式属性：fill（填充色）, stroke（描边色）, strokeWidth（描边宽度）
变换属性：scale（缩放）, rotate（旋转）, skew（倾斜）
交互属性：draggable（是否可拖拽）, selectable（是否可选择）

4.3 事件系统

LeaferJS 提供了丰富的事件系统，支持以下事件：

鼠标事件：click, dblclick, mousedown, mouseup, mousemove, mouseenter, mouseleave
触摸事件：touchstart, touchmove, touchend
拖拽事件：dragstart, drag, dragend
变换事件：transformstart, transform, transformend

javascript

// 示例：添加点击事件
rect.on('click', function(e) {
  console.log('矩形被点击了', e)
  // 改变矩形颜色
  this.fill = '#ff6b6b'
})

4.4 图层管理

LeaferJS 支持图层管理，可以创建和组织多个图层：

javascript

import { Leafer, Layer, Rect, Circle } from 'leafer-ui'

const leafer = new Leafer({ view: window })

// 创建图层
const layer1 = new Layer()
const layer2 = new Layer()

// 添加图形到不同图层
const rect = new Rect({ x: 100, y: 100, width: 100, height: 100, fill: '#32cd79' })
const circle = new Circle({ x: 150, y: 150, radius: 50, fill: '#ff6b6b' })

layer1.add(rect)
layer2.add(circle)

// 将图层添加到 Leafer 实例
leafer.add(layer1)
leafer.add(layer2)

4.5 动画系统

LeaferJS 内置了动画系统，支持属性动画：

javascript

import { Leafer, Rect, Animate } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
  x: 100,
  y: 100,
  width: 100,
  height: 100,
  fill: '#32cd79'
})

leafer.add(rect)

// 创建动画
Animate.to(rect, {
  duration: 1000,  // 动画持续时间（毫秒）
  x: 300,          // 目标位置 x
  y: 200,          // 目标位置 y
  rotate: 360,     // 目标旋转角度
  scale: 1.5,      // 目标缩放比例
  ease: 'easeOut'  // 缓动函数
})

5. 核心 API 参考

5.1 Leafer 类

Leafer 是 LeaferJS 的核心类，用于创建和管理画布：

javascript

const leafer = new Leafer(options)

// 方法
leafer.add(element)      // 添加元素
leafer.remove(element)   // 移除元素
leafer.clear()           // 清空所有元素
leafer.destroy()         // 销毁实例

// 属性
leafer.width             // 画布宽度
leafer.height            // 画布高度
leafer.interactive       // 是否开启交互

5.2 图形元素类

Rect（矩形）

javascript

const rect = new Rect({
  x: 0,          // 位置 x
  y: 0,          // 位置 y
  width: 100,    // 宽度
  height: 100,   // 高度
  fill: '#000',  // 填充色
  stroke: '#fff', // 描边色
  strokeWidth: 2, // 描边宽度
  draggable: true // 是否可拖拽
})

Circle（圆形）

javascript

const circle = new Circle({
  x: 100,        // 圆心位置 x
  y: 100,        // 圆心位置 y
  radius: 50,    // 半径
  fill: '#000',  // 填充色
  stroke: '#fff', // 描边色
  strokeWidth: 2, // 描边宽度
  draggable: true // 是否可拖拽
})

Text（文本）

javascript

const text = new Text({
  x: 100,        // 位置 x
  y: 100,        // 位置 y
  text: 'Hello', // 文本内容
  fontSize: 20,  // 字体大小
  fontWeight: 'bold', // 字体粗细
  fill: '#000',  // 文本颜色
  draggable: true // 是否可拖拽
})

5.3 事件 API

javascript

// 添加事件监听器
element.on('click', handler)

// 移除事件监听器
element.off('click', handler)

// 触发事件
element.emit('customEvent', data)

6. 示例代码

示例 1：创建交互式图形

javascript

import { Leafer, Rect, Circle, Text } from 'leafer-ui'

const leafer = new Leafer({ view: window, fill: '#f5f5f5' })

// 创建矩形
const rect = new Rect({
  x: 100,
  y: 100,
  width: 150,
  height: 150,
  fill: '#32cd79',
  draggable: true
})

// 创建圆形
const circle = new Circle({
  x: 350,
  y: 175,
  radius: 75,
  fill: '#ff6b6b',
  draggable: true
})

// 创建文本
const text = new Text({
  x: 150,
  y: 270,
  text: 'LeaferJS 示例',
  fontSize: 24,
  fontWeight: 'bold',
  fill: '#333'
})

// 添加点击事件
rect.on('click', function() {
  this.fill = '#4ecdc4'
})

circle.on('click', function() {
  this.fill = '#45b7d1'
})

// 添加到画布
leafer.add(rect)
leafer.add(circle)
leafer.add(text)

示例 2：创建简单动画

javascript

import { Leafer, Rect, Animate } from 'leafer-ui'

const leafer = new Leafer({ view: window, fill: '#f5f5f5' })

// 创建多个矩形
const colors = ['#32cd79', '#ff6b6b', '#45b7d1', '#f9ca24', '#6c5ce7']
const rects = []

for (let i = 0; i < 5; i++) {
  const rect = new Rect({
    x: 50 + i * 120,
    y: 200,
    width: 100,
    height: 100,
    fill: colors[i]
  })
  rects.push(rect)
  leafer.add(rect)
}

// 为每个矩形添加动画
rects.forEach((rect, index) => {
  Animate.to(rect, {
    duration: 1000,
    delay: index * 200,
    y: 100,
    scale: 1.2,
    repeat: -1, // 无限重复
    yoyo: true, // 往返动画
    ease: 'easeInOut'
  })
})

示例 3：响应式布局

javascript

import { Leafer, Rect } from 'leafer-ui'

// 创建响应式画布
const leafer = new Leafer({ view: window, fill: '#f5f5f5' })

// 创建一个始终居中的矩形
const rect = new Rect({
  width: 200,
  height: 200,
  fill: '#32cd79',
  draggable: true
})

leafer.add(rect)

// 更新矩形位置以保持居中
function updateCenter() {
  rect.x = (leafer.width - rect.width) / 2
  rect.y = (leafer.height - rect.height) / 2
}

// 初始居中
updateCenter()

// 监听窗口大小变化
window.addEventListener('resize', updateCenter)

7. 最佳实践

7.1 性能优化

合理使用图层：将相关图形放在同一图层，减少渲染层级
避免频繁重绘：使用批量操作，减少单独修改属性的次数
使用对象池：对于频繁创建和销毁的图形元素，考虑使用对象池
按需渲染：只渲染可见区域内的图形

7.2 代码组织

模块化设计：将不同功能的图形和逻辑分离到不同模块
使用 TypeScript：利用类型系统提高代码可维护性
合理命名：使用有意义的变量和函数名
添加注释：为复杂的图形逻辑添加注释

7.3 交互设计

提供视觉反馈：为交互元素添加 hover、active 等状态效果
支持键盘操作：除了鼠标和触摸，还可以支持键盘操作
合理的拖拽边界：设置拖拽边界，防止元素拖出可视区域
考虑无障碍：为图形元素添加适当的无障碍属性

8. 常见问题与解决方案

问题 1：图形不显示

解决方案：

检查图形是否添加到了 Leafer 实例中
检查图形的位置和尺寸是否正确
检查图形的填充色和描边色是否可见
检查 Leafer 实例是否正确创建并挂载到 DOM 中

问题 2：交互功能不工作

解决方案：

检查 Leafer 实例的 interactive 属性是否为 true
检查图形元素的 draggable、selectable 等属性是否正确设置
检查是否有其他元素遮挡了交互区域
检查事件监听器是否正确添加

问题 3：动画不流畅

解决方案：

减少同时运行的动画数量
简化动画效果，减少复杂计算
检查是否有其他代码阻塞了主线程
考虑使用 requestAnimationFrame 进行自定义动画

问题 4：响应式布局失效

解决方案：

确保 Leafer 实例的 resize 属性为 true
监听窗口 resize 事件，手动调整图形位置和大小
检查 CSS 样式是否影响了画布大小

问题 5：打包体积过大

解决方案：

使用按需引入，只导入需要的模块
配置构建工具，开启 tree-shaking
考虑使用 CDN 引入，利用浏览器缓存

9. 相关资源

10. 版本历史

v1.0.0（初始版本）

核心 Canvas 渲染引擎
基本图形元素（Rect、Circle、Text 等）
基本交互功能（拖拽、点击等）
动画系统

v1.1.0

增加路径（Path）支持
增加图片（Image）支持
优化渲染性能
增加更多事件类型

v1.2.0

增加图层（Layer）支持
增加更多动画效果
改进响应式设计
TypeScript 类型定义优化

通过本文档的学习，你应该能够快速上手 LeaferJS 并创建各种交互式图形应用。如果在使用过程中遇到问题，建议参考官方文档或 GitHub 仓库寻求帮助。

LeaferJS 文档 ​

概览 ​

1. 工具介绍 ​

主要特性 ​

2. 安装 ​

NPM 安装 ​

CDN 引入 ​

3. 基本使用 ​

创建一个简单的图形 ​

基本配置选项 ​

4. 核心功能 ​

4.1 图形元素 ​

4.2 图形属性 ​

4.3 事件系统 ​

4.4 图层管理 ​

4.5 动画系统 ​

5. 核心 API 参考 ​

5.1 Leafer 类 ​

5.2 图形元素类 ​

Rect（矩形） ​

Circle（圆形） ​

Text（文本） ​

5.3 事件 API ​

6. 示例代码 ​

示例 1：创建交互式图形 ​

示例 2：创建简单动画 ​

示例 3：响应式布局 ​

7. 最佳实践 ​

7.1 性能优化 ​

7.2 代码组织 ​

7.3 交互设计 ​

8. 常见问题与解决方案 ​

问题 1：图形不显示 ​

问题 2：交互功能不工作 ​

问题 3：动画不流畅 ​

问题 4：响应式布局失效 ​

问题 5：打包体积过大 ​

9. 相关资源 ​

10. 版本历史 ​

v1.0.0（初始版本） ​

v1.1.0 ​

v1.2.0 ​

LeaferJS 文档

概览

1. 工具介绍

主要特性

2. 安装

NPM 安装

CDN 引入

3. 基本使用

创建一个简单的图形

基本配置选项

4. 核心功能

4.1 图形元素

4.2 图形属性

4.3 事件系统

4.4 图层管理

4.5 动画系统

5. 核心 API 参考

5.1 Leafer 类

5.2 图形元素类

Rect（矩形）

Circle（圆形）

Text（文本）

5.3 事件 API

6. 示例代码

示例 1：创建交互式图形

示例 2：创建简单动画

示例 3：响应式布局

7. 最佳实践

7.1 性能优化

7.2 代码组织

7.3 交互设计

8. 常见问题与解决方案

问题 1：图形不显示

问题 2：交互功能不工作

问题 3：动画不流畅

问题 4：响应式布局失效

问题 5：打包体积过大

9. 相关资源

10. 版本历史

v1.0.0（初始版本）

v1.1.0

v1.2.0