vueuse-shared-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vueuse/vueuse

@vueuse/shared

vueuse/vueuse

@vueuse/shared

Version: 14.2.1 (Feb 2026) Tags: next: 5.0.0 (Jun 2021), 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月） **标签：**next: 5.0.0（2021年6月），alpha: 14.0.0-alpha.3（2025年9月），beta: 14.0.0-beta.1（2025年9月），latest: 14.2.1（2026年2月）

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

API Changes

API变更

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

BREAKING: Requires Vue 3.5 — v14 now requires Vue 3.5+ for native performance optimizations source
BREAKING:
```
useThrottleFn
```
alignment — v14 aligned with traditional throttle behavior (leading: true, trailing: false by default) source
BREAKING: ESM-only — v13 dropped CJS build support, package is now ESM-only source
BREAKING:
```
createSharedComposable
```
return — v14 now returns only the sharedComposable instance on the client side source
NEW:
```
refManualReset
```
— new function in v14 for creating refs with an explicit
```
reset()
```
method source
NEW:
```
watchAtMost
```
controls — v14 added
```
pause
```
,
```
resume
```
, and
```
count
```
to the return value source
NEW:
```
tryOnScopeDispose
```
— v14 added optional
```
failSilently
```
parameter to suppress errors outside of scope source
NEW:
```
useArrayReduce
```
type — v14.1.0 now exports the
```
UseArrayReduceReturn
```
type source
NEW:
```
computedWithControl
```
sources — v14.1.0 allows different types in watch sources array source
DEPRECATED:
```
computedEager
```
— v14 deprecated in favor of Vue 3.5's native
```
computed
```
optimizations source
DEPRECATED:
```
watchPausable
```
— v14 deprecated in favor of Vue's built-in
```
watch
```
or
```
pausableFilter
```
source
DEPRECATED: Alias exports — v14 deprecated secondary names like
```
ignorableWatch
```
in favor of primary
```
watchIgnorable
```
source
DEPRECATED:
```
eagerComputed
```
— v14 deprecated alias in favor of
```
computedEager
```
source
DEPRECATED:
```
controlledComputed
```
— v14 deprecated alias in favor of
```
computedWithControl
```
source

Also changed:

createReactiveFn

DEPRECATED ·

autoResetRef

DEPRECATED ·

debouncedRef

DEPRECATED ·

useDebounce

DEPRECATED ·

throttledRef

DEPRECATED ·

useThrottle

DEPRECATED ·

controlledRef

DEPRECATED ·

debouncedWatch

DEPRECATED ·

ignorableWatch

DEPRECATED ·

pausableWatch

DEPRECATED ·

throttledWatch

DEPRECATED

本节记录特定版本的API变更——优先关注近期的主版本/次版本更新。

破坏性变更：要求Vue 3.5 — v14版本为了原生性能优化，现在要求Vue 3.5或更高版本来源
破坏性变更：
```
useThrottleFn
```
行为对齐 — v14版本将
```
useThrottleFn
```
与传统节流行为对齐（默认leading: true，trailing: false）来源
破坏性变更：仅支持ESM — v13版本移除了CJS构建支持，包现在仅为ESM格式来源
破坏性变更：
```
createSharedComposable
```
返回值 — v14版本在客户端现在仅返回sharedComposable实例来源
新增：
```
refManualReset
```
— v14版本新增函数，用于创建带有显式
```
reset()
```
方法的ref 来源
新增：
```
watchAtMost
```
控制项 — v14版本为返回值添加了
```
pause
```
、
```
resume
```
和
```
count
```
方法来源
新增：
```
tryOnScopeDispose
```
— v14版本添加了可选的
```
failSilently
```
参数，用于抑制作用域外的错误来源
新增：
```
useArrayReduce
```
类型 — v14.1.0版本现在导出
```
UseArrayReduceReturn
```
类型来源
新增：
```
computedWithControl
```
数据源 — v14.1.0版本允许监听数据源数组中存在不同类型来源
废弃：
```
computedEager
```
— v14版本废弃该API，推荐使用Vue 3.5的原生
```
computed
```
优化来源
废弃：
```
watchPausable
```
— v14版本废弃该API，推荐使用Vue内置的
```
watch
```
或
```
pausableFilter
```
来源
废弃：别名导出 — v14版本废弃了
```
ignorableWatch
```
等次要名称，推荐使用主名称
```
watchIgnorable
```
来源
废弃：
```
eagerComputed
```
— v14版本废弃该别名，推荐使用
```
computedEager
```
来源
废弃：
```
controlledComputed
```
— v14版本废弃该别名，推荐使用
```
computedWithControl
```
来源

其他变更：

createReactiveFn

已废弃 ·

autoResetRef

已废弃 ·

debouncedRef

已废弃 ·

useDebounce

已废弃 ·

throttledRef

已废弃 ·

useThrottle

已废弃 ·

controlledRef

已废弃 ·

debouncedWatch

已废弃 ·

ignorableWatch

已废弃 ·

pausableWatch

已废弃 ·

throttledWatch

已废弃

Best Practices

最佳实践

Prefer Vue 3.4+ built-in
```
computed()
```
over
```
computedEager()
```
— standard computed properties now only trigger dependencies if the return value actually changes, making eager evaluation unnecessary source
Use
```
createSharedComposable()
```
for SSR-safe state sharing — it automatically falls back to non-shared instances during SSR to prevent cross-request state pollution, while maintaining a singleton on the client source
Share state within the same component using
```
provideLocal()
```
and
```
injectLocal()
```
— allows accessing provided values without going through the parent/child boundary, now with full Vapor mode support source
Replace manual watchers with
```
until()
```
for one-time async conditions — provides a promise-based API for flow control that resolves once a ref meets a specific requirement, reducing callback nesting source

// Preferred for one-time triggers
await until(isReady).toBe(true)
doSomething()

Implement
```
refManualReset()
```
for easy state restoration — provides a built-in
```
.reset()
```
method to return the ref to its initial value, ideal for clearing forms or reset-to-default filters source
Use
```
reactify()
```
to transform plain utility functions into reactive ones — automatically accepts refs as arguments and returns a
```
ComputedRef
```
, enabling rapid development of reactive logic source
Optimize hot paths with
```
refWithControl()
```
using
```
peek()
```
and
```
lay()
```
— allows reading or writing a ref's value without triggering the reactivity system or tracking dependencies, minimizing unnecessary updates source
Return dual object/array APIs via
```
makeDestructurable()
```
— makes your custom composables more flexible by allowing users to choose between positional (array) or named (object) destructuring source
Convert state during synchronization with
```
syncRef()
```
custom transforms — use the
```
transform
```
option with
```
ltr
```
and
```
rtl
```
functions to map values between refs of different types source

// Sync a number ref with a string ref
syncRef(count, stringCount, {
  transform: {
    ltr: left => String(left),
    rtl: right => Number(right)
  }
})

Choose
```
createGlobalState()
```
for persistent application-wide singletons — unlike shared composables which dispose state when subscribers reach zero, global state remains alive for the entire app lifecycle source

优先使用Vue 3.4+内置的
```
computed()
```
而非
```
computedEager()
```
— 标准计算属性现在仅在返回值实际变化时才触发依赖，因此无需再使用即时计算来源
使用
```
createSharedComposable()
```
实现SSR安全的状态共享 — 它会在SSR期间自动回退到非共享实例，以防止跨请求状态污染，同时在客户端保持单例来源
使用
```
provideLocal()
```
和
```
injectLocal()
```
在同一组件内共享状态 — 允许在不经过父子组件边界的情况下访问提供的值，现在完全支持Vapor模式来源
用
```
until()
```
替代手动监听器处理一次性异步条件 — 提供基于Promise的API进行流程控制，当ref满足特定条件时解析，减少回调嵌套来源

// 推荐用于一次性触发场景
await until(isReady).toBe(true)
doSomething()

使用
```
refManualReset()
```
实现便捷的状态恢复 — 提供内置的
```
.reset()
```
方法将ref恢复为初始值，非常适合清空表单或重置为默认过滤器来源
使用
```
reactify()
```
将普通工具函数转换为响应式函数 — 自动接受ref作为参数并返回
```
ComputedRef
```
，可快速开发响应式逻辑来源
使用
```
refWithControl()
```
的
```
peek()
```
和
```
lay()
```
方法优化热点路径 — 允许在不触发响应式系统或跟踪依赖的情况下读取或写入ref的值，最大限度减少不必要的更新来源
通过
```
makeDestructurable()
```
返回对象/数组双API — 让自定义组合式函数更灵活，用户可以选择位置（数组）或命名（对象）解构方式来源
使用
```
syncRef()
```
的自定义转换功能同步状态 — 配合
```
transform
```
选项的
```
ltr
```
和
```
rtl
```
函数，在不同类型的ref之间映射值来源

// 同步数字类型ref与字符串类型ref
syncRef(count, stringCount, {
  transform: {
    ltr: left => String(left),
    rtl: right => Number(right)
  }
})

为持久化的全局单例选择
```
createGlobalState()
```
— 与共享组合式函数（当订阅者为零时会销毁状态）不同，全局状态在整个应用生命周期内保持活跃来源

vueuse-shared-skilld

Original

Translation

vueuse/vueuse
`@vueuse/shared`

vueuse/vueuse
`@vueuse/shared`

API Changes

API变更

Best Practices

最佳实践