跳到主要内容

useManualRefHistory

分类
导出大小
518 B
上次更改
8 个月前
相关

当使用方调用 commit() 时,手动跟踪 ref 的更改历史,同时提供撤消和重做功能。

演示

计数:0
/

历史(演示限制为 10 条记录)
2025-10-23 06:49:05{ value: 0 }

用法

ts
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 值重置为上一个历史点。

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

可变对象的历史

如果您要修改源,则需要传递一个自定义克隆函数或使用 clone true 作为参数,这是一个最小克隆函数 x => JSON.parse(JSON.stringify(x)) 的快捷方式,该函数将用于 dumpparse

ts
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
()

自定义克隆函数

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

例如,使用 structuredClone

ts
import { 
useManualRefHistory
} from '@vueuse/core'
const
refHistory
=
useManualRefHistory
(target, {
clone
:
structuredClone
})

或者通过使用 lodash 的 cloneDeep

ts
import { 
useManualRefHistory
} from '@vueuse/core'
import {
cloneDeep
} from 'lodash-es'
const
refHistory
=
useManualRefHistory
(target, {
clone
:
cloneDeep
})

或者更轻量级的 klona

ts
import { 
useManualRefHistory
} from '@vueuse/core'
import {
klona
} from 'klona'
const
refHistory
=
useManualRefHistory
(target, {
clone
:
klona
})

自定义转储和解析函数

您可以传递自定义函数来控制序列化和解析,而不是使用 clone 选项。如果您不需要历史值是对象,这可以在撤消时节省额外的克隆。如果您希望将快照已经字符串化以保存到本地存储,这也会很有用。

ts
import { 
useManualRefHistory
} from '@vueuse/core'
const
refHistory
=
useManualRefHistory
(target, {
dump
:
JSON
.
stringify
,
parse
:
JSON
.
parse
,
})

历史容量

默认情况下,我们将保留所有历史记录(无限制),直到您明确清除它们。您可以通过 capacity 选项设置要保留的最大历史记录量。

ts
import { 
useManualRefHistory
} from '@vueuse/core'
const
refHistory
=
useManualRefHistory
(target, {
capacity
: 15, // limit to 15 history records
})
refHistory
.
clear
() // explicitly clear all the history

类型声明

显示类型声明
ts
export interface 
UseRefHistoryRecord
<
T
> {
snapshot
:
T
timestamp
: number
} export interface
UseManualRefHistoryOptions
<
Raw
,
Serialized
=
Raw
> {
/** * Maximum number of history to be kept. Default to unlimited. */
capacity
?: number
/** * Clone when taking a snapshot, shortcut for dump: JSON.parse(JSON.stringify(value)). * Default to false * * @default false */
clone
?: boolean |
CloneFn
<
Raw
>
/** * Serialize data into the history */
dump
?: (
v
:
Raw
) =>
Serialized
/** * Deserialize data from the history */
parse
?: (
v
:
Serialized
) =>
Raw
/** * set data source */
setSource
?: (
source
:
Ref
<
Raw
>,
v
:
Raw
) => void
} export interface
UseManualRefHistoryReturn
<
Raw
,
Serialized
> {
/** * Bypassed tracking ref from the argument */
source
:
Ref
<
Raw
>
/** * An array of history records for undo, newest comes to first */
history
:
Ref
<
UseRefHistoryRecord
<
Serialized
>[]>
/** * Last history point, source can be different if paused */
last
:
Ref
<
UseRefHistoryRecord
<
Serialized
>>
/** * Same as {@link UseManualRefHistoryReturn.history | history} */
undoStack
:
Ref
<
UseRefHistoryRecord
<
Serialized
>[]>
/** * Records array for redo */
redoStack
:
Ref
<
UseRefHistoryRecord
<
Serialized
>[]>
/** * A ref representing if undo is possible (non empty undoStack) */
canUndo
:
ComputedRef
<boolean>
/** * A ref representing if redo is possible (non empty redoStack) */
canRedo
:
ComputedRef
<boolean>
/** * Undo changes */
undo
: () => void
/** * Redo changes */
redo
: () => void
/** * Clear all the history */
clear
: () => void
/** * Create a new history record */
commit
: () => void
/** * Reset ref's value with latest history */
reset
: () => void
} /** * Track the change history of a ref, also provides undo and redo functionality. * * @see https://vueuse.org.cn/useManualRefHistory * @param source * @param options */ export declare function
useManualRefHistory
<
Raw
,
Serialized
=
Raw
>(
source
:
Ref
<
Raw
>,
options
?:
UseManualRefHistoryOptions
<
Raw
,
Serialized
>,
):
UseManualRefHistoryReturn
<
Raw
,
Serialized
>

来源

演示文档

贡献者

Anthony Fu
Matias Capeletto
Anthony Fu
SerKo
Robin
IlyaL
trent
Lov`u`e
Егор
丶远方
azaleta
Eduardo Wesley
Sahin D
vaakian X
Hollis Wu
wheat
Alex Kozack

更新日志

0a9ed - feat!: 放弃对 Vue 2 的支持,优化打包并清理 (#4349)
v11.2.0
b46d2 - fix: canUndocanRedo 类型为计算 ref (#4261)

根据 MIT 许可证发布。