LeaferJS (leaferjs/ai-docs)

Leafer AI

https://github.com/leaferjs/ai-docs
Admin
LeaferJS is a Canvas engine for efficient 2D drawing, UI interaction, and graphic editing with rich...

Tokens:563,725
Snippets:2,577
Trust Score:8.8
Update:6 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# LeaferJS Canvas 引擎

LeaferJS 是一款革新、高性能的 Canvas 2D 图形引擎，专注于图形编辑、图形交互和复杂 UI 构建。它能够瞬间创建 100 万个图形，提供接近浏览器级的排版能力和专业设计工具级的编辑功能。LeaferJS 支持 Web、Web Worker、Node.js 和微信小程序等多端运行环境，采用统一的核心 API。

该引擎特别适合开发图形编辑器（如 Figma、Canva 类工具）、在线白板、可视化系统、工业组态软件、2D 小游戏、互动应用以及图片/短视频生成等场景。相比 Fabric.js、Konva.js、PixiJS 等框架，LeaferJS 在编辑器能力、复杂 UI 构建和交互系统上提供更完整的原生支持。

---

## 安装与初始化

安装 LeaferJS 并创建基础画布应用。

```bash
# 使用 npm 安装
npm install leafer-ui

# 需要使用插件时，推荐同时安装核心包
npm install leafer-ui @leafer-ui/core @leafer-ui/draw

# 安装编辑器插件
npm install @leafer-in/editor @leafer-in/resize

# 安装动画插件
npm install @leafer-in/animate

# 安装视口插件
npm install @leafer-in/viewport
```

```typescript
// 创建自适应窗口的 Leafer 引擎
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',
    cornerRadius: [50, 80, 0, 80],
    draggable: true
})

leafer.add(rect)
```

---

## Rect 矩形元素

绘制矩形和圆角矩形，支持各种填充和描边样式。

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

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

// 标准创建方式
const rect = new Rect({
    x: 100,
    y: 100,
    width: 100,
    height: 100,
    fill: '#32cd79',
    cornerRadius: [0, 40, 20, 40], // 不同圆角
    stroke: '#000',
    strokeWidth: 2,
    draggable: true
})

leafer.add(rect)

// 简洁创建方式: Rect.one(data, x, y, width, height)
const rect2 = Rect.one({ fill: '#FEB027' }, 250, 100, 100, 100)
leafer.add(rect2)
```

---

## Ellipse 椭圆元素

绘制圆、椭圆、圆环、扇形和弧线。

```typescript
import { Leafer, Ellipse } from 'leafer-ui'

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

// 绘制圆
const circle = new Ellipse({
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    fill: '#32cd79'
})
leafer.add(circle)

// 绘制扇形圆环
const sectorRing = new Ellipse({
    x: 200,
    y: 50,
    width: 100,
    height: 100,
    startAngle: -60,
    endAngle: 180,
    innerRadius: 0.5, // 内径比例
    fill: '#FEB027'
})
leafer.add(sectorRing)
```

---

## Line 线条元素

绘制直线、斜线、折线和平滑曲线。

```typescript
import { Leafer, Line } from 'leafer-ui'

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

// 绘制虚线
const line = new Line({
    x: 50,
    y: 50,
    width: 100,
    rotation: 45,
    strokeWidth: 5,
    stroke: '#32cd79',
    dashPattern: [10, 10] // 虚线模式
})
leafer.add(line)

// 绘制折线
const polyline = new Line({
    x: 200,
    y: 50,
    points: [0, 0, 50, 80, 100, 20, 150, 100],
    stroke: '#FEB027',
    strokeWidth: 3
})
leafer.add(polyline)
```

---

## Polygon 多边形元素

绘制三角形、菱形、正多边形等。

```typescript
import { Leafer, Polygon } from 'leafer-ui'

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

// 绘制圆角六边形
const hexagon = new Polygon({
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    sides: 6,
    cornerRadius: 10,
    fill: '#32cd79'
})
leafer.add(hexagon)
```

---

## Star 星形元素

绘制五角星、多角星和车标图形。

```typescript
import { Leafer, Star } from 'leafer-ui'

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

// 绘制圆角八角星
const star = new Star({
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    corners: 8,
    innerRadius: 0.5,
    cornerRadius: 5,
    fill: '#32cd79'
})
leafer.add(star)
```

---

## Path 路径元素

使用 SVG 路径字符串绘制任意形状。

```typescript
import { Leafer, Path } from 'leafer-ui'

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

// 使用 SVG path 字符串绘制咖啡杯图标
const coffeeCup = new Path({
    x: 50,
    y: 50,
    scale: 0.1,
    path: 'M945.344 586.304c-13.056-93.44-132.48-98.048-132.48-98.048 0-29.888-39.808-47.424-39.808-47.424L201.664 440.832c-36.736 0-42.112 51.264-42.112 51.264 7.68 288 181.44 382.976 181.44 382.976l299.456 0...',
    fill: '#32cd79'
})
leafer.add(coffeeCup)
```

---

## Text 文本元素

绘制文本，支持多行和样式设置。

```typescript
import { Leafer, Text } from 'leafer-ui'

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

const text = new Text({
    x: 100,
    y: 100,
    fill: '#32cd79',
    text: 'Welcome to LeaferJS',
    fontSize: 24,
    fontWeight: 'bold'
})
leafer.add(text)
```

---

## Image 图片元素

加载和显示图片，支持 SVG 格式。

```typescript
import { Leafer, Image } from 'leafer-ui'

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

const image = new Image({
    x: 100,
    y: 100,
    url: '/image/leafer.jpg',
    draggable: true
})
leafer.add(image)
```

---

## Group 分组元素

组合多个子元素，实现层级管理。

```typescript
import { Leafer, Group, Rect, Ellipse } from 'leafer-ui'

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

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

const ellipse = new Ellipse({
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    innerRadius: 0.5,
    fill: '#FEB027'
})

const group = new Group({ x: 100, y: 100 })
group.add([rect, ellipse])
leafer.add(group)
```

---

## Box 容器元素

类似 HTML DIV，支持背景色和子元素裁剪。

```typescript
import { Leafer, Box, Ellipse } from 'leafer-ui'

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

const box = new Box({
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    fill: '#FF4B4B',
    overflow: 'hide' // 裁剪超出内容
})

const circle = new Ellipse({
    x: 60,
    y: 60,
    width: 50,
    height: 50,
    fill: '#FEB027',
    draggable: true
})

leafer.add(box)
box.add(circle)
```

---

## Frame 画板元素

设计软件中的画板容器，默认白色背景并裁剪超出内容。

```typescript
import { Leafer, Frame, Ellipse } from 'leafer-ui'

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

const frame = new Frame({
    x: 50,
    y: 50,
    width: 100,
    height: 100
})

const circle = new Ellipse({
    x: 60,
    y: 60,
    width: 50,
    height: 50,
    fill: '#32cd79',
    draggable: true
})

leafer.add(frame)
frame.add(circle)
```

---

## Pen 画笔元素

像绘画一样快速绑定不同样式的路径组合。

```typescript
import { Leafer, DragEvent, Pen } from 'leafer-ui'
import '@leafer-in/viewport'

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

const pen = new Pen()
leafer.add(pen)

// 画出不同颜色的形状
pen.setStyle({ fill: '#FF4B4B', windingRule: 'evenodd' })
pen.roundRect(0, 0, 100, 100, 30).arc(50, 50, 25)

pen.setStyle({ x: 50, y: 50, fill: '#FEB027' })
pen.arc(0, 0, 20)

// 自由绑定示例：按下鼠标拖动开始画线
leafer.on(DragEvent.START, (e: DragEvent) => {
    const point = e.getPagePoint()
    pen.setStyle({ stroke: '#32cd79', strokeWidth: 10, strokeCap: 'round', strokeJoin: 'round' })
    pen.moveTo(point.x, point.y)
})

leafer.on(DragEvent.DRAG, (e: DragEvent) => {
    const point = e.getPagePoint()
    pen.lineTo(point.x, point.y)
})
```

---

## 渐变填充

支持线性渐变、径向渐变、角度渐变和图案填充。

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

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

// 线性渐变
const linearRect = new Rect({
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    fill: {
        type: 'linear',
        stops: ['#FF4B4B', '#FEB027']
    }
})
leafer.add(linearRect)

// 图案填充
const imageRect = new Rect({
    x: 200,
    y: 50,
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'cover' // cover, fit, clip, repeat
    }
})
leafer.add(imageRect)

// 多重填充叠加
const multiRect = new Rect({
    x: 350,
    y: 50,
    width: 100,
    height: 100,
    fill: [
        { type: 'linear', stops: ['#FF4B4B', '#FEB027'] },
        { type: 'image', url: '/image/leafer.jpg', mode: 'cover', opacity: 0.2 }
    ]
})
leafer.add(multiRect)
```

---

## 事件监听

支持指针事件、拖拽事件、手势事件等完整的交互系统。

```typescript
import { Leafer, Rect, PointerEvent, DragEvent } 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)

// 点击事件
rect.on(PointerEvent.TAP, () => {
    console.log('tap')
})

// 双击事件
rect.on(PointerEvent.DOUBLE_TAP, () => {
    console.log('double_tap')
})

// 长按事件
rect.on(PointerEvent.LONG_TAP, () => {
    console.log('long_tap')
})

// 悬停效果
rect.on(PointerEvent.ENTER, (e: PointerEvent) => {
    (e.current as Rect).fill = '#42dd89'
})

rect.on(PointerEvent.LEAVE, (e: PointerEvent) => {
    (e.current as Rect).fill = '#32cd79'
})

// 拖拽事件
rect.on(DragEvent.DRAG, (e: DragEvent) => {
    e.current.moveWorld(e.moveX, e.moveY)
})
```

---

## 动画系统

支持过渡动画、关键帧动画、摇摆循环动画。

```typescript
import { Leafer, Rect } from 'leafer-ui'
import '@leafer-in/animate' // 导入动画插件

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

const rect = new Rect({
    x: 50,
    y: 100,
    width: 100,
    height: 100,
    cornerRadius: 50,
    fill: '#32cd79',
    around: 'center'
})
leafer.add(rect)

// 摇摆循环动画
rect.animate(
    { x: 500, cornerRadius: 0, fill: '#ffcd00' },
    {
        duration: 1,
        swing: true // 摇摆循环播放
    }
)

// 关键帧动画
rect.animate(
    [
        { style: { x: 150, scaleX: 2, fill: '#ffcd00' }, duration: 0.5 },
        { style: { x: 50, scaleX: 1, fill: '#ffcd00' }, duration: 0.2 },
        { style: { x: 550, cornerRadius: 0, fill: '#ffcd00' }, delay: 0.1, easing: 'bounce-out' },
        { x: 50, rotation: -720, cornerRadius: 50 }
    ],
    {
        duration: 3,
        loop: true,
        join: true // 加入动画前的元素状态作为 from 关键帧
    }
)
```

---

## 交互状态

支持 hover、press、focus、disabled 等交互状态和自定义状态切换。

```typescript
import { Leafer, Rect } from 'leafer-ui'
import '@leafer-in/state' // 导入交互状态插件
import '@leafer-in/animate' // 导入动画插件

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

const rect = new Rect({
    width: 100,
    height: 100,
    fill: '#32cd79',
    cornerRadius: 30,
    origin: 'center',
    states: {
        color: { fill: '#FEB027' },
        rotate: {
            animation: {
                keyframes: [{ rotation: 45 }, { rotation: 135, scale: 1.2 }],
                duration: 1,
                swing: true
            }
        }
    },
    state: 'color', // 设置初始状态
    transition: 1 // 过渡时间
})
leafer.add(rect)

// 点击切换状态
rect.on('click', () => {
    rect.state = rect.state === 'color' ? 'rotate' : 'color'
})
```

---

## 图形编辑器

创建专业级图形编辑器，支持多选、框选、旋转、缩放、编组等功能。

```typescript
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件

const app = new App({
    view: window,
    editor: {} // 配置 editor 自动创建编辑器实例
})

// 添加可编辑元素
const rect1 = Rect.one({ editable: true, fill: '#FEB027', cornerRadius: [20, 0, 0, 20] }, 100, 100)
const rect2 = Rect.one({ editable: true, fill: '#FFE04B', cornerRadius: [0, 20, 20, 0] }, 300, 100)

app.tree.add(rect1)
app.tree.add(rect2)

// 手动选中元素
app.editor.select(rect1)

// 监听选择事件
import { EditorEvent } from '@leafer-in/editor'
app.editor.on(EditorEvent.SELECT, (e: EditorEvent) => {
    console.log('选中的元素:', e.editor.list)
})

// 手动旋转元素
setTimeout(() => {
    app.editor.rotateOf('center', 45 - rect1.rotation)
}, 2000)
```

---

## 视口交互

支持画布缩放、平移和无限画布功能。

```typescript
import { Leafer, Rect } from 'leafer-ui'
import '@leafer-in/viewport' // 导入视口插件

const leafer = new Leafer({
    view: window,
    type: 'design' // 启用视口交互
})

leafer.add(Rect.one({ fill: '#32cd79', draggable: true }, 100, 100, 200, 200))

// 滚轮缩放、拖拽平移画布
// 可通过 leafer.zoomLayer 访问缩放层
// leafer.zoomLayer.scale = 2 // 设置缩放
// leafer.zoomLayer.x = 100 // 设置平移
```

---

## JSON 导入导出

支持将画布内容导出为 JSON 或从 JSON 恢复。

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

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

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

// 导出 JSON
const json = leafer.toJSON()
console.log(json)
// 输出: {"tag":"Leafer","width":1273,"height":877,"pixelRatio":2,"hittable":true,"children":[{"tag":"Rect","x":100,"y":100,"width":100,"height":100,"fill":"#32cd79","draggable":true}]}

// 使用 JSON 创建元素
const jsonData = {
    tag: 'Group',
    x: 20,
    y: 20,
    children: [
        { tag: 'Rect', x: 100, y: 100, width: 100, height: 100, fill: '#32cd79', draggable: true }
    ]
}
leafer.add(jsonData)
```

---

## 使用场景与集成模式

LeaferJS 主要适用于以下场景：**图形编辑器开发**（在线画图工具、UI 设计工具、流程图编辑器、思维导图）、**可视化系统**（数据大屏、监控系统、设备拓扑图）、**2D 游戏开发**（小游戏、游戏 UI）、**互动应用**（H5 互动页面、教育互动应用）以及**内容生成**（海报生成、AI 图片生成、短视频内容生成）。

集成时推荐使用 App 结构来构建复杂应用，它自动管理 tree 层（内容层）和 sky 层（编辑器层）的分离。对于简单场景使用 Leafer 即可；需要编辑功能时使用 App + Editor 插件；需要视口交互时添加 viewport 插件；需要动画时添加 animate 插件。LeaferJS 采用模块化设计，按需加载插件可以有效控制包体积。所有元素都支持 draggable 属性实现拖拽，editable 属性实现编辑器选取，通过事件系统可以实现任意复杂的交互逻辑。