vueuse-core-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vueuse/vueuse

@vueuse/core

vueuse/vueuse

@vueuse/core

Version: 14.2.1 (Feb 2026) Deps: @types/web-bluetooth@^0.0.21, @vueuse/metadata@14.2.1, @vueuse/shared@14.2.1 Tags: vue2: 2.0.35 (Jul 2020), vue3: 3.0.35 (Jul 2020), demi: 4.0.0-alpha.0 (Jul 2020), alpha: 14.0.0-alpha.3 (Sep 2025), beta: 14.0.0-beta.1 (Sep 2025), latest: 14.2.1 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

**版本：**14.2.1（2026年2月） 依赖：@types/web-bluetooth@^0.0.21, @vueuse/metadata@14.2.1, @vueuse/shared@14.2.1 **标签：**vue2: 2.0.35（2020年7月）, vue3: 3.0.35（2020年7月）, demi: 4.0.0-alpha.0（2020年7月）, alpha: 14.0.0-alpha.3（2025年9月）, beta: 14.0.0-beta.1（2025年9月）, latest: 14.2.1（2026年2月）

参考链接：文档 — API参考、指南 • GitHub问题 — bug、解决方案、边缘情况 • GitHub讨论 — 问答、模式、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING:
```
computedAsync
```
— default
```
flush
```
changed from
```
pre
```
to
```
sync
```
in v14.0.0; code relying on deferred evaluation now runs synchronously by default source
BREAKING:
```
useThrottleFn
```
— aligned with traditional throttle behavior in v14.0.0 (trailing call behavior changed); previously called on both leading and trailing by default, verify options match expected behavior source
BREAKING:
```
createSharedComposable
```
— on client side, now returns only the shared composable (single value) instead of a tuple/object in v14.0.0 source
BREAKING:
```
useAsyncState
```
— in v13.7.0,
```
globalThis.reportError
```
is now the default
```
onError
```
handler; previously errors were silently swallowed if no handler was provided source
BREAKING: CJS build dropped in v13.0.0 —
```
@vueuse/core
```
is now ESM-only;
```
require('@vueuse/core')
```
no longer works source
BREAKING: Vue 3.5 is now required as a minimum peer dependency since v14.0.0 source
DEPRECATED:
```
watchPausable
```
— will be removed in a future version; Vue 3.5 native
```
watch()
```
now returns
```
{ stop, pause, resume }
```
directly; use
```
const { pause, resume } = watch(src, cb)
```
instead source
DEPRECATED:
```
computedEager
```
— will be removed in a future version; Vue 3.4+
```
computed()
```
no longer triggers dependents when the value does not change, making this unnecessary source
DEPRECATED:
```
templateRef(key)
```
— deprecated in v13.6.0; use Vue's built-in
```
useTemplateRef()
```
instead source
DEPRECATED:
```
executeTransition()
```
— use the new
```
transition()
```
function instead;
```
UseTransitionOptions.transition
```
option also deprecated, use
```
easing
```
source

DEPRECATED:

breakpointsVuetify

— was an alias for

breakpointsVuetifyV2

; now deprecated, explicitly use

breakpointsVuetifyV2

breakpointsVuetifyV3

source

DEPRECATED:
```
asyncComputed
```
— alias for
```
computedAsync
```
, removed from v14 alias exports; import as
```
computedAsync
```
source
NEW:
```
refManualReset(defaultValue)
```
— added in v14.0.0; creates a ref with a
```
.reset()
```
method that restores the initial value source

NEW:

useCssSupports(property, value)

useCssSupports(conditionText)

— added in v14.2.0; reactive wrapper for

CSS.supports()

source

NEW:
```
useTimeAgoIntl(time, options)
```
— added in v13.7.0; Intl-based time-ago formatting using
```
Intl.RelativeTimeFormat
```
, supports custom units source
NEW:
```
transition(source, from, to, options)
```
— added in v14.0.0 as the non-deprecated replacement for
```
executeTransition
```
; also adds
```
interpolation
```
option for custom interpolator functions source

NEW:

ConfigurableScheduler

interface +

scheduler

option — added in v14.2.0 to timed composables (

useCountdown

useNow

useTimestamp

useTimeAgo

useTimeAgoIntl

useElementByPoint

useMemory

useVibrate

); replaces deprecated per-composable

interval

immediate

options source

NEW:
```
useIdle
```
— now implements
```
Stoppable
```
interface (v14.0.0), returns
```
{ pause, resume, stop }
```
in addition to previous return values source

Also changed:

useIntersectionObserver

rootMargin is now reactive (v14.2.0) ·

useElementVisibility

gains

initialValue

option (v14.1.0) and inherits reactive

rootMargin

(v14.2.0) ·

useDropZone

gains

checkValidity

function (v14.1.0) ·

useRefHistory

gains

shouldCommit

option (v13.4.0) ·

useUrlSearchParams

gains

stringify

option (v13.4.0) ·

watchAtMost

now returns

{ pause, resume }

(v14.0.0) ·

useStorageAsync

gains

onReady

option and Promise return (v13.6.0) ·

useAsyncState

initial value can now be a ref (v14.0.0) ·

useSortable

gains

watchElement

option (v14.2.0) ·

useWebSocket

autoConnect.delay

accepts a function (v14.1.0) ·

useClipboardItems

exposes

read()

method (v13.7.0) ·

useDraggable

gains auto-scroll with container-restricted dragging (v14.2.0) ·

useEventSource

gains

serializer

option (v13.8.0) ·

onLongPress

delay

can now be a function (v14.0.0) ·

onClickOutside

target can now be a getter function (v14.0.0)

本节记录各版本特有的API变更 — 优先关注近期的大版本/小版本更新。

破坏性变更：
```
computedAsync
```
— 在v14.0.0版本中，默认的
```
flush
```
选项从
```
pre
```
改为
```
sync
```
；依赖延迟求值的代码现在默认会同步执行来源
破坏性变更：
```
useThrottleFn
```
— 在v14.0.0版本中对齐了传统节流行为（尾部调用逻辑变更）；之前默认同时调用首部和尾部函数，请验证选项是否符合预期行为来源
破坏性变更：
```
createSharedComposable
```
— 在客户端，v14.0.0版本现在仅返回共享的组合式函数（单个值），而非元组/对象来源
破坏性变更：
```
useAsyncState
```
— 在v13.7.0版本中，
```
globalThis.reportError
```
成为默认的
```
onError
```
处理器；之前如果未提供处理器，错误会被静默忽略来源
**破坏性变更：**v13.0.0版本移除了CJS构建 —
```
@vueuse/core
```
现在仅支持ESM；
```
require('@vueuse/core')
```
不再生效来源
**破坏性变更：**从v14.0.0版本开始，最低peer依赖要求升级为Vue 3.5 来源
已废弃：
```
watchPausable
```
— 会在未来版本移除；Vue 3.5原生
```
watch()
```
现在直接返回
```
{ stop, pause, resume }
```
；请改用
```
const { pause, resume } = watch(src, cb)
```
来源
已废弃：
```
computedEager
```
— 会在未来版本移除；Vue 3.4+的
```
computed()
```
现在仅在值变化时触发依赖更新，因此该API已无必要来源
已废弃：
```
templateRef(key)
```
— 在v13.6.0版本中废弃；请改用Vue内置的
```
useTemplateRef()
```
来源
已废弃：
```
executeTransition()
```
— 请改用新的
```
transition()
```
函数；
```
UseTransitionOptions.transition
```
选项也已废弃，请使用
```
easing
```
来源

已废弃：

breakpointsVuetify

— 曾是

breakpointsVuetifyV2

的别名；现已废弃，请显式使用

breakpointsVuetifyV2

或

breakpointsVuetifyV3

来源

已废弃：
```
asyncComputed
```
— 作为
```
computedAsync
```
的别名，已从v14版本的别名导出中移除；请直接导入
```
computedAsync
```
来源
新增：
```
refManualReset(defaultValue)
```
— 在v14.0.0版本中添加；创建一个带有
```
.reset()
```
方法的ref，可恢复初始值来源

新增：

useCssSupports(property, value)

useCssSupports(conditionText)

— 在v14.2.0版本中添加；

CSS.supports()

的响应式封装来源

新增：
```
useTimeAgoIntl(time, options)
```
— 在v13.7.0版本中添加；基于Intl的相对时间格式化，使用
```
Intl.RelativeTimeFormat
```
，支持自定义单位来源
新增：
```
transition(source, from, to, options)
```
— 在v14.0.0版本中添加，作为
```
executeTransition
```
的非废弃替代方案；还新增了
```
interpolation
```
选项支持自定义插值函数来源
新增：
```
ConfigurableScheduler
```
接口 +
```
scheduler
```
选项 — 在v14.2.0版本中添加到定时类组合式函数（
```
useCountdown
```
,
```
useNow
```
,
```
useTimestamp
```
,
```
useTimeAgo
```
,
```
useTimeAgoIntl
```
,
```
useElementByPoint
```
,
```
useMemory
```
,
```
useVibrate
```
）；替代了每个组合式函数中已废弃的
```
interval
```
/
```
immediate
```
选项来源
新增：
```
useIdle
```
— 现在实现了
```
Stoppable
```
接口（v14.0.0），除原有返回值外，还返回
```
{ pause, resume, stop }
```
来源

其他变更：

useIntersectionObserver

的rootMargin现在支持响应式（v14.2.0） ·

useElementVisibility

新增

initialValue

选项（v14.1.0）并继承了响应式

rootMargin

（v14.2.0） ·

useDropZone

新增

checkValidity

函数（v14.1.0） ·

useRefHistory

新增

shouldCommit

选项（v13.4.0） ·

useUrlSearchParams

新增

stringify

选项（v13.4.0） ·

watchAtMost

现在返回

{ pause, resume }

（v14.0.0） ·

useStorageAsync

新增

onReady

选项并返回Promise（v13.6.0） ·

useAsyncState

的初始值现在可以是ref（v14.0.0） ·

useSortable

新增

watchElement

选项（v14.2.0） ·

useWebSocket

的

autoConnect.delay

支持传入函数（v14.1.0） ·

useClipboardItems

暴露

read()

方法（v13.7.0） ·

useDraggable

新增容器限制拖拽时的自动滚动功能（v14.2.0） ·

useEventSource

新增

serializer

选项（v13.8.0） ·

onLongPress

的

delay

现在可以是函数（v14.0.0） ·

onClickOutside

的目标现在可以是getter函数（v14.0.0）

Best Practices

最佳实践

Pass reactive getters (
```
() => value
```
) as arguments instead of plain refs where possible — VueUse 9+ supports getter arguments, enabling derived reactive values without an intermediate
```
computed
```
(e.g.
```
useTitle(() => isDark.value ? 'Night' : 'Day')
```
) source
Wrap
```
useFetch
```
calls in
```
createFetch
```
for app-wide config — sets base URL, auth headers, and CORS mode once; individual call sites inherit it without re-specifying options source
Use
```
eventFilter
```
option with
```
throttleFilter
```
/
```
debounceFilter
```
instead of manually wrapping callbacks — applies rate-limiting at the composable level for
```
useLocalStorage
```
,
```
useMouse
```
, and other event-driven composables source
Enable
```
mergeDefaults: true
```
(or pass a custom merge function) on
```
useStorage
```
when evolving stored object schemas — without it, new default keys are
```
undefined
```
if absent from existing storage data source
Use
```
StorageSerializers
```
from
```
@vueuse/core
```
when the
```
useStorage
```
default value is
```
null
```
— without a serializer hint, the type cannot be inferred and serialization falls back to raw string source
Use
```
createSharedComposable
```
to share a single composable instance across components — avoids duplicate event listeners and state. Note: in SSR it automatically falls back to a non-shared instance per call to prevent cross-request pollution source
Use
```
computedWithControl
```
when a computed value should only update on specific sources, not all its reactive dependencies —
```
computed
```
cannot opt out of automatic dependency tracking, but
```
computedWithControl
```
decouples the watch source from the getter source
Wrap VueUse calls outside component scope with
```
effectScope()
```
and call
```
scope.stop()
```
for cleanup — not all composables return a stop handle;
```
effectScope
```
is the universal escape hatch when composables are used in stores or non-component contexts source
Pass
```
window
```
option to browser composables like
```
useMouse
```
or
```
useScroll
```
to target iframes or mock globals in tests — all browser API composables accept configurable global dependencies via options source
Pass a custom
```
scheduler
```
to time-based composables (
```
useNow
```
,
```
useCountdown
```
, etc.) to align them with
```
useRafFn
```
or throttle their update rate — introduced in v14.1.0 / v14.2.0; without it, timed composables run on their own internal interval independent of animation frames source

尽可能将响应式 getter（
```
() => value
```
）作为参数传递，而非普通的ref — VueUse 9+ 支持getter参数，无需中间
```
computed
```
即可实现派生响应式值（例如
```
useTitle(() => isDark.value ? '夜间模式' : '日间模式')
```
）来源
将
```
useFetch
```
调用包裹在
```
createFetch
```
中实现应用级配置 — 一次性设置基础URL、认证头和CORS模式；各个调用站点无需重复指定选项即可继承配置来源
对
```
useLocalStorage
```
、
```
useMouse
```
等事件驱动的组合式函数，使用
```
eventFilter
```
选项搭配
```
throttleFilter
```
/
```
debounceFilter
```
，而非手动包裹回调 — 在组合式函数层面实现速率限制来源
当演进存储对象的 schema 时，在
```
useStorage
```
上启用
```
mergeDefaults: true
```
（或传入自定义合并函数） — 否则，如果现有存储数据中缺少新的默认键，这些键的值会是
```
undefined
```
来源
当
```
useStorage
```
的默认值为
```
null
```
时，使用
```
@vueuse/core
```
中的
```
StorageSerializers
```
— 没有序列化器提示的话，类型无法被推断，序列化会回退到原始字符串来源
使用
```
createSharedComposable
```
在多个组件间共享单个组合式函数实例 — 避免重复的事件监听器和状态。注意：在SSR中会自动回退为每次调用创建非共享实例，防止跨请求污染来源
当计算属性仅需在特定源更新，而非所有响应式依赖更新时，使用
```
computedWithControl
```
—
```
computed
```
无法退出自动依赖追踪，但
```
computedWithControl
```
可以将监听源与getter解耦来源
在组件作用域外调用VueUse时，用
```
effectScope()
```
包裹并调用
```
scope.stop()
```
进行清理 — 并非所有组合式函数都会返回停止句柄；在状态管理或非组件上下文中使用组合式函数时，
```
effectScope
```
是通用的解决方案来源
为
```
useMouse
```
或
```
useScroll
```
等浏览器组合式函数传递
```
window
```
选项，以针对iframe或在测试中模拟全局对象 — 所有浏览器API组合式函数都支持通过选项配置全局依赖来源
为基于时间的组合式函数（
```
useNow
```
、
```
useCountdown
```
等）传递自定义
```
scheduler
```
，使其与
```
useRafFn
```
对齐或限制更新速率 — 该特性在v14.1.0/v14.2.0版本引入；不设置的话，定时组合式函数会独立于动画帧运行自己的内部定时器来源

vueuse-core-skilld

Original

Translation

vueuse/vueuse
`@vueuse/core`

vueuse/vueuse
`@vueuse/core`

API Changes

API变更

Best Practices

最佳实践