Leafer Js

为 Claude 提供 LeaferJS Canvas 图形引擎的全面支持。当用户需要创建、开发或调试 LeaferJS 应用时，请立即使用此 Skill。 LeaferJS 是一个现代化的 Canvas 引擎，专注于图形编辑、复杂 UI 构建和交互应用开发。支持瞬间创建100万个图形，性能卓越。适用于以下场景： - 创建图形编辑器（如 Figma、Canva 类工具） - 开发互动应用、小游戏 - 构建可视化系统、数据大屏 - 开发 AI 无限画布应用 - 生成图片与短视频内容 - 创建组态软件、工业监控当用户提到以下关键词时触发：LeaferJS、Leafer、Canvas 引擎、图形编辑、画布应用、可视化、图形交互、动画系统、UI 布局、图形编辑器即使用户没有明确说"Skill"，只要涉及 LeaferJS 相关开发，都应该使用此 Skill。

ZhenYangze@zhenyangze

Install

openclaw skills install @zhenyangze/leafer-js-skill

LeaferJS 开发 Skill

核心能力

LeaferJS 是一款革新、好用的 Canvas 引擎，轻松实现专业图形编辑。

主要特点

超高性能：瞬间创建100万个图形
完整图形编辑：多选、框选、编组、变换、吸附等专业能力
强大动画系统：CSS风格过渡、关键帧、路径动画、精灵帧
丰富交互系统：手势识别、拖拽、缩放、旋转、事件捕获/冒泡
多端统一：Web、Worker、Node.js、小程序一套 API
自动布局：类似 Flex 的 Flow 布局系统

适用场景

图形编辑应用：在线画图、图片编辑器、设计工具、流程图、思维导图
小游戏：2D游戏、游戏UI、动画界面
互动应用：教育互动、可视化页面、产品演示、H5互动
组态软件：工业组态、监控大屏、设备拓扑
图片/视频生成：海报生成、AI图片生成、短视频封面

快速开始

安装

bash

# 基础 UI 包（推荐，70KB min+gzip）
npm install leafer-ui

# 全量包（含所有插件）
npm install leafer

创建第一个应用

typescript

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

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

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

leafer.add(rect)

使用 App 结构（推荐编辑器场景）

typescript

import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor'
import '@leafer-in/viewport'

const app = new App({
    view: window,
    editor: {}  // 自动创建 tree 层、sky 层、editor
})

app.tree.add(Rect.one({ 
    editable: true, 
    fill: '#32cd79' 
}, 100, 100))

运行环境配置

Web 浏览器

ES Module 导入（推荐）:

typescript

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

CDN Script 引入:

html

<!-- 生产环境 -->
<script src="https://unpkg.com/leafer-ui@2.1.0/dist/web.min.js"></script>
<!-- 开发环境 -->
<script src="https://unpkg.com/leafer-ui@2.1.0/dist/web.js"></script>
<!-- ES Module -->
<script type="module">
  import { Leafer } from 'https://unpkg.com/leafer-ui@2.1.0/dist/web.module.min.js'
</script>

<script>
  const { Leafer, Rect } = LeaferUI
  // 注意：Image、PointerEvent、DragEvent 需使用别名
  const { MyImage, MyPointerEvent, MyDragEvent } = LeaferUI
</script>

Vue 3 集成

vue

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { Leafer, Rect } from 'leafer-ui'

let leafer: Leafer

onMounted(() => {
  leafer = new Leafer({ view: 'leafer-view' })
  
  leafer.add(new Rect({
    x: 100, y: 100,
    width: 200, height: 200,
    fill: '#32cd79',
    draggable: true
  }))
})

onUnmounted(() => {
  leafer?.destroy()  // 必须销毁
})
</script>

<template>
  <div id="leafer-view"></div>
</template>

<style scoped>
#leafer-view {
  position: absolute;
  top: 0; left: 0;
  width: 100%;
  height: 100%;
}
</style>

注意事项：leafer 及元素不能直接挂载到响应式数据上，会造成内部层层代理，拖慢运行速度。

React 集成

tsx

import { useEffect, useRef } from 'react'
import { Leafer, Rect } from 'leafer-ui'

export default function LeaferCanvas() {
  const leaferRef = useRef<Leafer | null>(null)

  useEffect(() => {
    let isDestroy = false
    
    import('leafer-ui').then(({ Leafer, Rect }) => {
      if (isDestroy) return
      
      leaferRef.current = new Leafer({ view: 'leafer-view' })
      
      leaferRef.current.add(new Rect({
        x: 100, y: 100,
        width: 200, height: 200,
        fill: '#32cd79',
        draggable: true
      }))
    })

    return () => {
      leaferRef.current?.destroy()  // 必须销毁
      isDestroy = true
    }
  }, [])

  return (
    <div 
      id="leafer-view" 
      style={{ 
        position: 'absolute', 
        top: 0, left: 0, 
        width: '100%', 
        height: '100%' 
      }} 
    />
  )
}

Next.js 集成

tsx

'use client'  // 标识为客户端组件

import { useEffect, useRef, useState } from 'react'

export default function LeaferView() {
  const leaferRef = useRef<any>(null)
  
  useEffect(() => {
    let isDestroy = false
    
    import('leafer-ui').then(({ Leafer, Rect }) => {
      if (isDestroy) return
      
      leaferRef.current = new Leafer({ view: 'leafer-view' })
      
      leaferRef.current.add(new Rect({
        x: 100, y: 100,
        width: 200, height: 200,
        fill: '#32cd79',
        draggable: true
      }))
    })
    
    return () => {
      leaferRef.current?.destroy()
      isDestroy = true
    }
  }, [])

  return <div id="leafer-view" style={{ width: '100%', height: '100%' }} />
}

Web Worker

bash

npm install @leafer-ui/worker

// main.js
const worker = new Worker('./worker.js')

worker.onmessage = (e) => {
  const image = new Image()
  image.src = e.data
  document.body.appendChild(image)
}

// worker.js
importScripts('https://unpkg.com/@leafer-ui/worker@2.1.0/dist/worker.min.js')

const { Leafer, Rect } = LeaferUI

const leafer = new Leafer({ width: 800, height: 600 })
leafer.add(Rect.one({ fill: '#32cd79' }, 100, 100))

leafer.export('jpg').then((result) => {
  self.postMessage(result.data)
})

Node.js 服务端

bash

npm install @leafer-ui/node skia-canvas

typescript

import { Leafer, Rect, useCanvas } from '@leafer-ui/node'
import skia from 'skia-canvas'

useCanvas('skia', skia)  // 必须

const leafer = new Leafer({ width: 800, height: 600 })
leafer.add(Rect.one({ fill: '#32cd79' }, 100, 100))

// 生成图片
const result = await leafer.export('png')
// result.data 是 base64 图片数据

// HTTP 服务示例
import http from 'http'

http.createServer(async (req, res) => {
  const leafer = new Leafer({ width: 800, height: 600 })
  leafer.add(Rect.one({ fill: '#32cd79' }, 100, 100))
  
  const result = await leafer.export('png')
  
  res.writeHead(200, { 'Content-Type': 'text/html' })
  res.write(`<img src="${result.data}" />`)
  res.end()
}).listen(3000)

微信小程序

bash

npm install @leafer-ui/miniapp

typescript

// index.ts
import { Leafer, Rect } from '@leafer-ui/miniapp'

Page({
  onReady() {
    const leafer = new Leafer({
      view: 'leafer',
      eventer: this
    })
    
    leafer.add(new Rect({
      x: 100, y: 100,
      width: 100, height: 100,
      fill: '#32cd79',
      draggable: true
    }))
  },
  receiveEvent() {}  // 约定接收交互事件的方法名
})

xml

<!-- index.wxml -->
<canvas
  id="leafer"
  type="2d"
  catchtouchstart="receiveEvent"
  catchtouchmove="receiveEvent"
  catchtouchend="receiveEvent"
  catchtouchcancel="receiveEvent"
/>

css

/* index.wxss */
page { height: 100%; }
#leafer { width: 100%; height: 100%; }

小程序环境要求：微信小程序基础库 >= 3.6.0

项目初始化

使用 create-leafer 命令行工具

bash

# 创建 Vue + Leafer 项目
npm create leafer@latest my-vue-app -- --template vue

# 创建 React + Leafer 项目
npm create leafer@latest my-react-app -- --template react

# 创建纯 Leafer 项目
npm create leafer@latest my-app

# 使用 pnpm
pnpm create leafer@latest my-app

# 在现有项目中安装 Leafer
npm create leafer@latest -- --init

在现有项目中集成

bash

# 安装基础包
npm install leafer-ui

# 安装插件（按需）
npm install @leafer-in/animate @leafer-in/editor @leafer-in/viewport

# 安装类型支持
npm install -D @types/node

项目结构

text

examples/       # 完整可运行示例代码
guide/          # 教程文档
reference/      # API 参考文档
plugin/         # 插件文档
src/            # TypeScript 源码（用于理解类结构）

关键文档位置

显示对象：reference/display/ - 所有图形元素
属性方法：reference/property/ - UI 属性和方法
事件类型：reference/event/ - 所有事件
插件中心：plugin/in/ - 官方插件使用文档
快速入门：guide/basic/ - 分步骤教程

核心概念

1. 显示对象层次

text

App
├── tree (Leafer) - 设计层，存放主要内容
│   ├── Group/Box/Frame - 容器
│   │   ├── Rect/Ellipse/Text/Image/Path - 图形元素
│   └── Editor - 编辑器
└── sky (Leafer) - 天空层，放置UI控件

关键元素：

App：应用容器，管理多层结构
Leafer：渲染层，可独立运行
Group：基础容器
Box：带背景的容器，支持 padding
Frame：固定尺寸的容器，支持滚动
UI：所有可视元素的基类

图形元素：

Rect：矩形、圆角矩形
Ellipse：椭圆、圆形
Line：直线、带箭头
Polygon：多边形
Star：星形
Path：路径
Pen：画笔，自由绘制
Text：文本
Image：图片
SVG：SVG 图形
Canvas：Canvas 元素

2. 核心插件

必需插件（通过 leafer 全量包自动安装）：

@leafer-in/animate - 动画系统
@leafer-in/editor - 图形编辑器
@leafer-in/viewport - 视口控制
@leafer-in/scroll - 滚动条
@leafer-in/arrow - 箭头
@leafer-in/html - HTML 渲染
@leafer-in/state - 交互状态
@leafer-in/flow - 自动布局
@leafer-in/text-editor - 文本编辑
@leafer-in/robot - 游戏精灵
@leafer-in/find - 查找
@leafer-in/filter - 滤镜
@leafer-in/export - 导出
@leafer-in/resize - 调整大小
@leafer-in/color - 颜色处理
@leafer-in/motion-path - 路径动画
@leafer-in/scale-fixed - 固定缩放
@leafer-in/corner - 圆角
@leafer-in/bright - 亮度

3. 坐标系统

世界坐标系 (World)：全局绝对坐标
本地坐标系 (Local)：相对于父元素
Box 坐标系：相对于元素自身的包围盒
页面坐标系 (Page)：考虑视口偏移

4. 事件系统

UI 事件：

PointerEvent - 指针事件（DOWN, UP, TAP, MOVE, ENTER, LEAVE）
DragEvent - 拖拽事件（START, DRAG, STOP）
DropEvent - 放置事件
SwipeEvent - 滑动手势
MoveEvent - 移动事件
ZoomEvent - 缩放事件
RotateEvent - 旋转事件
KeyEvent - 键盘事件

生命周期事件：

LeaferEvent - 引擎生命周期（READY, VIEW_READY）
RenderEvent - 渲染事件（START, END）
LayoutEvent - 布局事件
ResizeEvent - 尺寸变化
WatchEvent - 数据监听

编辑器事件：

EditorEvent - 选择变化
EditorMoveEvent - 移动
EditorScaleEvent - 缩放
EditorRotateEvent - 旋转
EditorSkewEvent - 倾斜
EditorGroupEvent - 编组
InnerEditorEvent - 内部编辑

动画事件：

AnimateEvent - 动画事件（PLAY, UPDATE, COMPLETED）

详细参考文档

显示对象

所有图形元素的完整参考，包括：

容器：App, Leafer, Group, Box, Frame
图形：Rect, Ellipse, Line, Polygon, Star, Path, Pen
媒体：Image, SVG, Canvas
文本：Text

插件系统

所有官方插件的使用方法：

安装方式
配置选项
使用示例
事件监听

动画系统

完整的动画功能：

基础动画
关键帧动画
过渡动画
路径动画
摇摆循环

事件系统

所有事件类型的详细说明：

UI 交互事件
编辑器事件
动画事件
生命周期事件

样式系统

视觉样式完整参考：

填充（纯色、渐变、图案）
描边
阴影（外阴影、内阴影、Box阴影）
滤镜效果
混合模式

编辑器系统

图形编辑器完整指南：

配置与创建
选择与框选
变换操作
编组与解组
自定义编辑工具

框架集成

前端框架集成指南：

Vue 3 - 组件封装、Pinia 状态管理、注意事项
React - Hooks、异步加载、SSR 处理
Next.js - 客户端组件、动态导入、配置优化
Nuxt - 客户端插件、配置选项

运行环境

各运行环境配置：

Web 浏览器 - CDN、ESM、响应式、高清屏适配
Web Worker - 后台渲染、批量生成
Node.js - 服务端渲染、HTTP 服务、Express 集成
微信小程序 - 基础用法、图形编辑器、性能优化

实用示例

实际应用场景示例：

图形编辑器 - 完整画板、流程图编辑器
小游戏 - 打砖块、贪吃蛇
数据可视化 - 柱状图、饼图
海报生成 - 社交媒体海报、证书生成器
思维导图、无限画布、图片编辑器

调试指南

调试和性能优化：

Debug 工具 - 调试级别、性能监控
性能测试 - 基准测试、内存分析
常见问题排查 - 画布不显示、事件不响应、动画问题
框架集成问题、渲染诊断、内存泄漏排查

自定义元素

创建自定义 UI 元素和扩展：

自定义 UI 基础 - 继承 UI 基类、装饰器
自定义容器 - 特殊布局、虚拟列表
自定义渲染 - 自定义绘制、离屏渲染
自定义插件 - 创建插件、缓动函数、编辑工具
扩展 Leafer 类、自定义事件

常用代码模式

创建可编辑的图形

typescript

import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor'

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: '#32cd79',
    editable: true  // 关键：使元素可被编辑
})

app.tree.add(rect)

添加动画

typescript

import { Animate } from '@leafer-in/animate'

// 方式1：使用 Animate 类
new Animate(rect, 
    { x: 500, rotation: 360 },  // 目标状态
    { duration: 2, loop: true }  // 选项
)

// 方式2：使用 animate() 方法
rect.animate(
    { x: 500 },
    { duration: 2, easing: 'ease-out' }
)

// 方式3：使用 transition 属性
rect.transition = { duration: 0.5 }
rect.x = 500  // 自动动画

监听事件

typescript

import { PointerEvent, DragEvent } from 'leafer-ui'

rect.on(PointerEvent.TAP, (e) => {
    console.log('点击了矩形')
})

rect.on(DragEvent.DRAG, (e) => {
    console.log('拖拽中:', e.x, e.y)
})

使用 Flow 自动布局

typescript

import { Box } from 'leafer-ui'
import '@leafer-in/flow'

const container = new Box({
    flow: 'x',           // 水平排列
    gap: 10,             // 间距
    padding: 20,         // 内边距
    fill: '#333'
})

// 子元素自动排列
container.add(new Rect({ fill: 'red', width: 50, height: 50 }))
container.add(new Rect({ fill: 'blue', width: 50, height: 50 }))

状态样式

typescript

import '@leafer-in/state'

const rect = new Rect({
    fill: '#32cd79',
    hoverStyle: { fill: '#ffcd00' },      // 悬停状态
    pressStyle: { fill: '#ff6b6b' },      // 按下状态
    selectedStyle: { stroke: '#0066ff' }  // 选中状态
})

导出图片

typescript

import '@leafer-in/export'

// 导出整个画布
const blob = await app.tree.export('png')

// 导出指定元素
const blob2 = await rect.export('png', { 
    pixelRatio: 2  // 高分辨率
})

性能优化

创建大量图形

typescript

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

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

// 启用调试
Debug.enable = true
Debug.filter = 'RunTime'

const startTime = Date.now()

// 使用 addMany 批量添加
const rects = []
for (let i = 0; i < 100000; i++) {
    rects.push(new Rect({
        x: (i % 100) * 12,
        y: Math.floor(i / 100) * 12,
        width: 10, height: 10,
        fill: `hsl(${(i * 3) % 360}, 70%, 60%)`,
        draggable: true
    }))
}

leafer.addMany(rects)  // 批量添加，性能更好

console.log('创建10万个矩形用时：', Date.now() - startTime, '毫秒')

批量操作

typescript

// 使用 set() 批量设置属性
rect.set({
    x: 100,
    y: 100,
    fill: '#ff0000'
})

// 避免频繁更新
rect.x = 100  // ❌ 触发渲染
rect.y = 100  // ❌ 触发渲染
rect.fill = 'red'  // ❌ 触发渲染

rect.set({ x: 100, y: 100, fill: 'red' })  // ✅ 只触发一次渲染

最佳实践

性能优化
- 大量图形时使用 leafer.addMany() 批量添加
- 避免频繁更新单个属性，使用 set() 批量设置
- 使用 visible: false 隐藏而非销毁暂时不用的元素
内存管理
- 及时销毁不再使用的元素 element.destroy()
- 移除事件监听 off() 避免内存泄漏
- Vue/React 组件卸载时必须调用 leafer.destroy()
编辑器开发
- 使用 App 结构而非单独 Leafer
- 设置 editable: true 使元素可被选择编辑
- 使用 app.tree 添加主要内容，app.sky 添加 UI 控件
动画性能
- 优先使用 CSS 风格 transition 属性
- 复杂动画使用 willReadFrequently 优化
- 使用 Animate 实例控制精细动画
框架集成注意事项
- leafer 及元素不能直接挂载到响应式数据上
- 异步加载 leafer-ui 确保 canvas context 环境
- 开发环境 useEffect 会执行多次，必须及时销毁

学习路径

入门：阅读 guide/basic/leafer.md 快速入门教程
进阶：学习 guide/basic/ 目录下的交互、动画、布局教程
深入：研究 examples/ 中的完整示例代码
精通：查阅 reference/ 和 plugin/ 完整 API 文档

在线资源

官网：https://www.leaferjs.com
在线 Playground：https://www.leaferjs.com/playground/
在线示例：https://www.leaferjs.com/examples/
GitHub：https://github.com/leaferjs/leafer-ui

注意事项

LeaferJS 可简称为 Leafer
插件需要先安装再导入使用
编辑器功能必须在 App 中使用
版本号请使用 2.1.0 或最新版本
view 参数为 id 字符串时不加 # 号
浏览器要求：Chrome >= 51, Firefox >= 53, Safari >= 10, Edge >= 79, IE 不支持