vueuse-integrations-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vueuse/vueuse

@vueuse/integrations

vueuse/vueuse

@vueuse/integrations

Version: 14.2.1 (Feb 2026) Deps: @vueuse/core@14.2.1, @vueuse/shared@14.2.1 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月） 依赖：@vueuse/core@14.2.1，@vueuse/shared@14.2.1 **标签：**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 Issues — bug、解决方案、边缘案例 • GitHub讨论 — 问答、模式、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

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

BREAKING: Requires Vue 3.5+ — v14.x now requires Vue 3.5.0 as a peer dependency for native features like
```
useTemplateRef
```
BREAKING: ESM-only — dropped CommonJS (CJS) build in v13.0.0, now an ESM-only package source
BREAKING:
```
focus-trap
```
dependency —
```
useFocusTrap
```
updated peer dependency range to
```
^7 || ^8
```
in v14.2.0 source

BREAKING:

universal-cookie

dependency —

useCookies

now supports and prefers

universal-cookie

^7 || ^8

BREAKING:
```
change-case
```
v5 —
```
useChangeCase
```
is now compatible with
```
change-case
```
v5, including internal naming changes
DEPRECATED: Alias exports — v14.0.0 deprecated alias exports in favor of original function names for consistency source
NEW:
```
watchElement
```
option —
```
useSortable
```
added
```
watchElement
```
in v14.2.0 to auto-reinitialize when target element changes source
NEW:
```
updateContainerElements
```
—
```
useFocusTrap
```
exposed
```
updateContainerElements
```
in v13.6.0 for dynamic container updates source
NEW:
```
serializer
```
option —
```
useIDBKeyval
```
added
```
options.serializer
```
in v13.6.0 for custom data serialization source
NEW: Component Ref support —
```
useSortable
```
can now accept a Vue component instance/ref as the target element since v13.1.0 source
NEW: Thenable
```
useAxios
```
—
```
useAxios
```
returns are now thenable, allowing
```
await useAxios(...)
```
in async contexts source
NEW: Flexible
```
execute
```
—
```
useAxios
```
```
execute()
```
can now take
```
url
```
or
```
config
```
separately for manual triggers source
NEW:
```
initialData
```
option —
```
useAxios
```
added
```
initialData
```
to provide a default value before the request finishes source
NEW: Helper functions —
```
moveArrayElement
```
,
```
insertNodeAt
```
, and
```
removeNode
```
are now exported from
```
useSortable
```
source

Also changed:

useAsyncValidator

internal types ·

useJwt

options refinement ·

useNProgress

reactive state consistency ·

useSortable

type misalignment fix source

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

破坏性变更：要求Vue 3.5+ — v14.x版本现在要求Vue 3.5.0作为peer依赖，以支持
```
useTemplateRef
```
等原生特性
破坏性变更：仅支持ESM — v13.0.0版本移除了CommonJS（CJS）构建，现在是纯ESM包来源
破坏性变更：
```
focus-trap
```
依赖 — v14.2.0版本中
```
useFocusTrap
```
的peer依赖范围更新为
```
^7 || ^8
```
来源
破坏性变更：
```
universal-cookie
```
依赖 —
```
useCookies
```
现在支持并优先使用
```
universal-cookie
```
```
^7 || ^8
```
版本
破坏性变更：
```
change-case
```
v5 —
```
useChangeCase
```
现在兼容
```
change-case
```
v5版本，包括内部命名变更
已废弃：别名导出 — v14.0.0版本废弃了别名导出，改用原始函数名称以保持一致性来源
新增：
```
watchElement
```
选项 — v14.2.0版本中
```
useSortable
```
新增
```
watchElement
```
选项，当目标元素变化时自动重新初始化来源
新增：
```
updateContainerElements
```
— v13.6.0版本中
```
useFocusTrap
```
暴露了
```
updateContainerElements
```
方法，用于动态更新容器来源
新增：
```
serializer
```
选项 — v13.6.0版本中
```
useIDBKeyval
```
新增
```
options.serializer
```
选项，支持自定义数据序列化来源
新增：组件Ref支持 — 自v13.1.0版本起，
```
useSortable
```
可以接受Vue组件实例/Ref作为目标元素来源
新增：Thenable
```
useAxios
```
—
```
useAxios
```
的返回值现在支持thenable，允许在异步上下文使用
```
await useAxios(...)
```
来源
新增：灵活的
```
execute
```
—
```
useAxios
```
的
```
execute()
```
方法现在可以单独传入
```
url
```
或
```
config
```
以手动触发请求来源
新增：
```
initialData
```
选项 —
```
useAxios
```
新增
```
initialData
```
选项，用于在请求完成前提供默认值来源
新增：辅助函数 —
```
moveArrayElement
```
、
```
insertNodeAt
```
和
```
removeNode
```
现在从
```
useSortable
```
中导出来源

其他变更：

useAsyncValidator

内部类型优化 ·

useJwt

选项细化 ·

useNProgress

响应式状态一致性优化 ·

useSortable

类型不匹配修复来源

Best Practices

最佳实践

Import functions from submodules to maximize tree-shaking efficiency and reduce the final bundle size source

// Preferred
import { useAxios } from '@vueuse/integrations/useAxios'

// Avoid
import { useAxios } from '@vueuse/integrations'

Await
```
useAxios()
```
directly for one-off requests as the return value is thenable, simplifying promise handling source

const { data, error } = await useAxios('/api/posts')

Enable
```
resetOnExecute: true
```
in
```
useAxios
```
options to clear stale data automatically when a new request is triggered source

const { execute } = useAxios('/api/data', { method: 'GET' }, { resetOnExecute: true })

Explicitly import
```
useCookies
```
in Nuxt 3 environments to avoid name collisions with Nuxt's built-in
```
useCookie
```
composable source

import { useCookies } from '@vueuse/integrations/useCookies'

Use
```
autoUpdateDependencies: true
```
with
```
useCookies
```
to automatically track and update dependencies for any cookie names accessed via
```
.get()
```
source

const { get } = useCookies(['initial'], { autoUpdateDependencies: true })

Enable the
```
watchElement: true
```
option in
```
useSortable
```
to automatically reinitialize the instance when the target element changes (e.g., with
```
v-if
```
) source

useSortable(el, list, { watchElement: true })

Wrap post-update logic in
```
nextTick()
```
after calling
```
moveArrayElement
```
in
```
useSortable
```
to ensure the DOM update has fully finished source

useSortable(el, list, {
  onUpdate: (e) => {
    moveArrayElement(list, e.oldIndex, e.newIndex)
    nextTick(() => { /* perform post-move logic */ })
  }
})

Use
```
nextTick()
```
before calling
```
activate()
```
in
```
useFocusTrap
```
when dealing with conditionally rendered (
```
v-if
```
) elements to ensure they exist in the DOM source

async function openModal() {
  show.value = true
  await nextTick()
  activate()
}

Prefer the
```
UseFocusTrap
```
component over the manual composable for automatic activation on mount and cleanup on unmount source

vue

<UseFocusTrap v-if="show" :options="{ immediate: true }">
  <div class="modal">...</div>
</UseFocusTrap>

Await the
```
.set()
```
method returned by
```
useIDBKeyval
```
to ensure that the IndexedDB transaction is fully committed before proceeding source

const count = useIDBKeyval('my-count', 0)
await count.set(10)

从子模块导入函数以最大化tree-shaking效率，减小最终打包体积来源

// 推荐写法
import { useAxios } from '@vueuse/integrations/useAxios'

// 不推荐写法
import { useAxios } from '@vueuse/integrations'

直接
```
await useAxios()
```
处理一次性请求，因为返回值支持thenable，简化Promise处理来源

const { data, error } = await useAxios('/api/posts')

在
```
useAxios
```
选项中启用
```
resetOnExecute: true
```
，以在触发新请求时自动清除过期数据来源

const { execute } = useAxios('/api/data', { method: 'GET' }, { resetOnExecute: true })

在Nuxt 3环境中显式导入
```
useCookies
```
，避免与Nuxt内置的
```
useCookie
```
组合式函数命名冲突来源

import { useCookies } from '@vueuse/integrations/useCookies'

为
```
useCookies
```
启用
```
autoUpdateDependencies: true
```
，以自动跟踪并更新通过
```
.get()
```
访问的所有Cookie名称的依赖来源

const { get } = useCookies(['initial'], { autoUpdateDependencies: true })

在
```
useSortable
```
中启用
```
watchElement: true
```
选项，当目标元素变化时（例如使用
```
v-if
```
）自动重新初始化实例来源

useSortable(el, list, { watchElement: true })

在
```
useSortable
```
中调用
```
moveArrayElement
```
后，将更新后逻辑包裹在
```
nextTick()
```
中，确保DOM更新完全完成来源

useSortable(el, list, {
  onUpdate: (e) => {
    moveArrayElement(list, e.oldIndex, e.newIndex)
    nextTick(() => { /* 执行移动后的逻辑 */ })
  }
})

当处理条件渲染（
```
v-if
```
）的元素时，在调用
```
useFocusTrap
```
的
```
activate()
```
前使用
```
nextTick()
```
，确保元素已存在于DOM中来源

async function openModal() {
  show.value = true
  await nextTick()
  activate()
}

优先使用
```
UseFocusTrap
```
组件而非手动调用组合式函数，以实现挂载时自动激活、卸载时自动清理来源

vue

<UseFocusTrap v-if="show" :options="{ immediate: true }">
  <div class="modal">...</div>
</UseFocusTrap>

调用
```
useIDBKeyval
```
返回的
```
.set()
```
方法时使用
```
await
```
，确保IndexedDB事务完全提交后再继续执行来源

const count = useIDBKeyval('my-count', 0)
await count.set(10)