历史记录与撤销重做 (HistoryPlugin)

createHistoryPlugin 基于纯快照栈实现完整的操作历史管理，支持 Ctrl+Z 撤销 / Ctrl+Y 重做 键盘快捷键，以及跳转到任意历史步骤的时间旅行功能。

快速上手

有以下两种方式启用历史记录功能：

方式一：通过组件属性启用 (最简便)

你可以直接在 <yh-flow> 组件上设置 history 属性。组件内部会自动注册并管理历史记录插件，且支持快捷键。

<template>
  <yh-flow ref="flowRef" :history="true" :max-history="100" @history-change="handleHistoryChange" />
</template>

<script setup lang="ts">
const flowRef = ref()

const handleHistoryChange = ({ canUndo, canRedo }) => {
  console.log('是否可撤销:', canUndo, '是否可重做:', canRedo)
}

// 依然可以通过 flowRef 调用方法
const undo = () => flowRef.value?.undo?.()
const redo = () => flowRef.value?.redo?.()
const saveSnapshot = () => flowRef.value?.saveSnapshot?.('手动保存快照')
</script>

方式二：手动注册插件 (高度定制)

如果你需要更高级的参数控制（例如通过组件外部或特定事件自定义回调等），可以手动创建并安装插件：

import { createHistoryPlugin } from '@yh-ui/flow'

onMounted(() => {
  // 1. 创建并安装插件
  const plugin = createHistoryPlugin({
    maxHistory: 100, // 最多保存 100 步历史
    enableKeyboard: true, // 启用 Ctrl+Z / Ctrl+Y 快捷键
    onHistoryChange: (canUndo, canRedo, length) => {
      // 根据状态更新 UI（按钮禁/启用）
    }
  })
  flowRef.value?.usePlugin(plugin)
})

// 2. 撤销/重做
const undo = () => flowRef.value?.undo?.()
const redo = () => flowRef.value?.redo?.()

IMPORTANT

无论使用哪种方式，saveSnapshot、undo、redo 等扩展方法都是在组件/插件加载就绪后动态挂载到 flowRef.value 上的，请确保在 onMounted 或事件回调中调用它们。

基础用法演示

撤销/重做 — 保存快照后可撤销/重做节点位置

API

HistoryPluginOptions

属性	类型	默认值	说明
enabled	boolean	true	是否启用插件
maxHistory	number	100	最大历史记录步数（超出则自动丢弃最旧步骤）
enableKeyboard	boolean	true	是否注册 Ctrl+Z/Y 键盘快捷键（全局 window 级）
onHistoryChange	(canUndo, canRedo, length) => void	—	历史变化时的回调，用于更新按钮状态

插件安装后的 FlowInstance 扩展方法

通过 flowRef.value?.usePlugin(plugin) 安装后，以下方法/属性自动挂载到 flowRef.value

方法/属性	类型	说明
undo()	() => void	撤销到上一快照
redo()	() => void	重做到下一快照
saveSnapshot(desc?)	(description?: string) => void	手动保存当前 nodes + edges 快照
clearHistory()	() => void	清空所有历史记录
jumpToStep(index)	(index: number) => void	跳转到指定历史步骤（时间旅行）
getHistory()	() => FlowHistorySnapshot[]	获取完整历史列表
canUndo	Ref<boolean>	是否可撤销（响应式）
canRedo	Ref<boolean>	是否可重做（响应式）
historyLength	Ref<number>	当前历史条数（响应式）

FlowHistorySnapshot 类型

interface FlowHistorySnapshot {
  nodes: Node[]
  edges: Edge[]
  timestamp: number
  description?: string
}

键盘快捷键

快捷键	说明
Ctrl + Z / ⌘ + Z	撤销
Ctrl + Y / ⌘ + Y	重做
Ctrl + Shift + Z / ⌘ + ⇧ + Z	重做（macOS 兼容）

最佳实践

TIP

不推荐开启 autoCapture（自动捕获所有变化），建议在业务操作的关键时机手动调用 saveSnapshot：

// ✅ 推荐：在关键时机手动保存，精确控制历史粒度
flowRef.value?.on('node:dragend', () => flowRef.value?.saveSnapshot?.('拖动节点'))

// 连线创建后保存
// 删除操作前保存
// 用户手动点击"保存"按钮时保存

下一步

• 节点成组
• 数据流光效边
• 自动布局