leafer-x-history

Leafer.js 撤销/重做历史记录管理插件。遵循 leafer-x 第三方插件规范开发。

特性

• ✅ 完整的撤销/重做功能
• ✅ 支持最大历史记录限制
• ✅ 支持历史记录持久化 (IndexedDB)
• ✅ 事件订阅机制
• ✅ TypeScript 类型支持
• ✅ 框架无关，可与 Vue/React/原生 JS 配合使用

安装

npm install leafer-x-history

# 或
pnpm add leafer-x-history

# 或
yarn add leafer-x-history

快速开始

1. 注册插件

import { usePlugin, Leafer } from 'leafer-ui'
import { historyPlugin } from 'leafer-x-history'

// 注册插件（全局生效）
usePlugin(historyPlugin, {
  maxSize: 50, // 最大历史记录数量
})

// 创建 Leafer 实例
const leafer = new Leafer({ view: 'app' })

2. 创建快照

import { createSnapshot } from 'leafer-x-history'

// 在需要保存历史记录时调用
createSnapshot(leafer)

3. 撤销/重做

import { undoLeafer, redoLeafer } from 'leafer-x-history'

// 撤销
undoLeafer(leafer)

// 重做
redoLeafer(leafer)

4. 获取 HistoryManager 实例

import { getHistoryManager } from 'leafer-x-history'

const manager = getHistoryManager(leafer)

if (manager) {
  console.log('canUndo:', manager.canUndo)
  console.log('canRedo:', manager.canRedo)
  console.log('history size:', manager.size)
}

API 文档

插件配置 (HistoryPluginConfig)

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | maxSize | number | 50 | 最大历史记录数量 | | type | string | - | 指定 Leafer 类型，只有该类型的实例才会启用插件 | | storage | HistoryStorage | - | 持久化存储实例 | | serializerOptions | LeaferSerializerOptions | - | 序列化器配置 |

LeaferSerializerOptions

| 选项 | 类型 | 说明 | |------|------|------| | getZoom | () => number | 获取画布缩放比例的函数 | | setZoom | (zoom: number) => void | 设置画布缩放比例的函数 | | canvasStyles | LeaferCanvasStyles | 画布样式配置 | | setCanvasStyles | (styles: LeaferCanvasStyles) => void | 设置画布样式的函数 | | createElement | (tag: string, props: Record<string, unknown>) => IUI \| null | 自定义元素创建函数 | | ignoreTags | string[] | 忽略的元素标签列表 | | serializeProps | string[] | 需要序列化的属性列表 | | deserializeProps | string[] | 需要反序列化的属性列表 |

导出函数

createSnapshot(leafer: ILeafer): void

为指定 Leafer 实例创建历史快照。

undoLeafer(leafer: ILeafer): boolean

对指定 Leafer 实例执行撤销操作。返回是否成功。

redoLeafer(leafer: ILeafer): boolean

对指定 Leafer 实例执行重做操作。返回是否成功。

clearHistory(leafer: ILeafer): Promise<void>

清空指定 Leafer 实例的历史记录。

getHistoryManager(leafer: ILeafer): HistoryManager | undefined

获取指定 Leafer 实例的 HistoryManager。

HistoryManager 类

class HistoryManager<T> {
  // 属性
  readonly canUndo: boolean
  readonly canRedo: boolean
  readonly size: number
  readonly index: number

  // 方法
  init(): Promise<void>  // 初始化，从存储加载快照
  getCurrent(): T | null
  push(snapshot: T): Promise<void>
  undo(): T | null
  redo(): T | null
  clear(): Promise<void>

  // 事件
  on(event: HistoryEventType, listener: HistoryEventListener<T>): () => void
  off(event: HistoryEventType, listener: HistoryEventListener<T>): void
}

事件类型

| 事件 | 说明 | 数据 | |------|------|------| | push | 快照被添加 | { snapshot, index } | | undo | 执行撤销 | { snapshot, index } | | redo | 执行重做 | { snapshot, index } | | clear | 历史被清空 | {} | | error | 发生错误 | { error } |

IndexedDB 持久化

import { IndexedDBStorage } from 'leafer-x-history'

const storage = new IndexedDBStorage({
  dbName: 'my-app-history',
  storeName: 'snapshots',
})

usePlugin(historyPlugin, {
  storage,
})

IndexedDBStorage 类

class IndexedDBStorage<T> implements HistoryStorage<T> {
  // 静态方法
  static isSupported(): boolean  // 检查 IndexedDB 是否支持

  // 实例方法
  constructor(options: IndexedDBStorageOptions)
  load(): Promise<T[]>
  save(snapshots: T[]): Promise<void>
  clear(): Promise<void>
  close(): void  // 关闭数据库连接
}

IndexedDBStorageOptions

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | dbName | string | 'leafer-x-history' | 数据库名称 | | storeName | string | 'snapshots' | 存储名称 |

示例

配合键盘快捷键

import { usePlugin, Leafer } from 'leafer-ui'
import { historyPlugin, createSnapshot, undoLeafer, redoLeafer } from 'leafer-x-history'

usePlugin(historyPlugin)

const leafer = new Leafer({ view: 'app' })

// 键盘快捷键
document.addEventListener('keydown', (e) => {
  if ((e.ctrlKey || e.metaKey) && e.key === 'z') {
    e.preventDefault()
    if (e.shiftKey) {
      redoLeafer(leafer) // Ctrl+Shift+Z 重做
    } else {
      undoLeafer(leafer) // Ctrl+Z 撤销
    }
  }
})

// 在操作后创建快照
function onObjectAdded() {
  createSnapshot(leafer)
}

仅对特定 Leafer 实例启用

import { usePlugin, Leafer } from 'leafer-ui'
import { historyPlugin } from 'leafer-x-history'

// 使用 type 选项
usePlugin(historyPlugin, {
  type: 'with-history',
})

// 只有 type 为 'with-history' 的 Leafer 实例才会启用历史记录
const leafer1 = new Leafer({ view: 'app1', type: 'with-history' }) // 启用
const leafer2 = new Leafer({ view: 'app2' }) // 不启用

开发

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 构建
pnpm build

License

MIT