useManualRefHistory

类别

State

导出大小

505 B

最近修改

2 days ago

相关

useRefHistory

在使用 commit() 调用时手动跟踪 ref 的变更历史，同时提供撤销和重做功能

🌐 Manually track the change history of a ref when the using calls commit(), also provides undo and redo functionality

示例

源代码在线运行

Count: 0

/

History (limited to 10 records for demo)

2026-02-07 22:39:38{ value: 0 }

用法

🌐 Usage

import { useManualRefHistory } from '@vueuse/core'
import { shallowRef } from 'vue'

const counter = shallowRef(0)
const { history, commit, undo, redo } = useManualRefHistory(counter)

counter.value += 1
commit()

console.log(history.value)
/* [
  { snapshot: 1, timestamp: 1601912898062 },
  { snapshot: 0, timestamp: 1601912898061 }
] */

你可以使用 undo 将 ref 值重置到上一次的历史点。

🌐 You can use undo to reset the ref value to the last history point.

console.log(counter.value) // 1
undo()
console.log(counter.value) // 0

可变对象的历史

🌐 History of mutable objects

如果你打算修改源代码，你需要传递一个自定义的克隆函数，或者将 clone true 作为参数使用，这相当于一个最小克隆函数 x => JSON.parse(JSON.stringify(x)) 的快捷方式，该函数将在 dump 和 parse 中使用。

🌐 If you are going to mutate the source, you need to pass a custom clone function or use clone true as a param, that is a shortcut for a minimal clone function x => JSON.parse(JSON.stringify(x)) that will be used in both dump and parse.

import { useManualRefHistory } from '@vueuse/core'
import { ref } from 'vue'

const counter = ref({ foo: 1, bar: 2 })
const { history, commit, undo, redo } = useManualRefHistory(counter, { clone: true })

counter.value.foo += 1
commit()

自定义克隆函数

🌐 Custom Clone Function

要使用功能齐全或自定义的克隆函数，你可以通过 clone 选项进行设置。

🌐 To use a full featured or custom clone function, you can set up via the clone options.

例如，使用 structuredClone ：

🌐 For example, using structuredClone:

import { useManualRefHistory } from '@vueuse/core'

const refHistory = useManualRefHistory(target, { clone: structuredClone })

或者使用 lodash 的 cloneDeep:

🌐 Or by using lodash's cloneDeep:

import { useManualRefHistory } from '@vueuse/core'
import { cloneDeep } from 'lodash-es'

const refHistory = useManualRefHistory(target, { clone: cloneDeep })

或者一个更轻量的 klona：

🌐 Or a more lightweight klona:

import { useManualRefHistory } from '@vueuse/core'
import { klona } from 'klona'

const refHistory = useManualRefHistory(target, { clone: klona })

自定义转储和解析函数

🌐 Custom Dump and Parse Function

你可以不用 clone 选项，而是传入自定义函数来控制序列化和解析。如果你不需要将历史值作为对象，这样在撤销时可以节省一次额外的克隆操作。如果你希望快照已经是字符串格式以便例如保存到本地存储，这也非常有用。

🌐 Instead of using the clone options, you can pass custom functions to control the serialization and parsing. In case you do not need history values to be objects, this can save an extra clone when undoing. It is also useful in case you want to have the snapshots already stringified to be saved to local storage for example.

import { useManualRefHistory } from '@vueuse/core'

const refHistory = useManualRefHistory(target, {
  dump: JSON.stringify,
  parse: JSON.parse,
})

历史容量

🌐 History Capacity

我们默认会保留所有历史记录（无限制），直到你明确清除为止，你可以通过 capacity 选项设置要保留的历史记录的最大数量。

🌐 We will keep all the history by default (unlimited) until you explicitly clear them up, you can set the maximal amount of history to be kept by capacity options.

import { useManualRefHistory } from '@vueuse/core'

const refHistory = useManualRefHistory(target, {
  capacity: 15, // limit to 15 history records
})

refHistory.clear() // explicitly clear all the history