vueuse-integrations-skilld

@vueuse/integrations 15.0.0

VueUse 的附加包：为 12 个工具库提供响应式封装。需要 Vue（^3.5.0），并将 @vueuse/core 和 @vueuse/shared 15.0.0 作为依赖项提供（package.json:55-70,108-111）。从 v13 起仅支持 ESM。从 v15 起需要 Node >= 22（package.json:52-54）。

参考资料

• 完整 API 概览 — 所有导出项、签名、选项和默认值，均已根据 dist/ 核实。
• 用法模式 — 各函数的用法示例和注意事项。
• 从 v14 迁移到 v15 — 破坏性变更和更新步骤。

安装

npm i @vueuse/integrations

每个封装都需要单独安装对应的可选 peer 依赖，否则导入时会在运行时失败：

组合式函数	Peer 依赖
useAsyncValidator	async-validator@^4
useAxios	axios@^1
useChangeCase	change-case@^5
useCookies	`universal-cookie@^7
useDrauu	`drauu@^1
useFocusTrap	`focus-trap@^7
useFuse	fuse.js@^7
useIDBKeyval	idb-keyval@^6
useJwt	jwt-decode@^4
useNProgress	nprogress@^0.2
useQRCode	qrcode@^1.5
useSortable	sortablejs@^1

来源：package.json:55-69。

导入规则：使用子模块

为实现摇树优化，请从各函数的子模块导入（README.md:33-42）：

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

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

组件从 /component 子路径导入：

import { UseFocusTrap } from '@vueuse/integrations/useFocusTrap/component'
import { UseSortable } from '@vueuse/integrations/useSortable/component'
import { UseAsyncValidator } from '@vueuse/integrations/useAsyncValidator/component'

别名导出已在 v14.0.0 中弃用；请使用原始名称（https://github.com/vueuse/vueuse/issues/5009）。

v15 的破坏性变更（相较于 v14）

1. useIDBKeyval 返回对象 { data, isFinished, isSupported, set }，而不是 ref（dist/useIDBKeyval.d.ts:46-51）。const count = useIDBKeyval('k', 0) 将无法再编译；请改为解构 data。
2. useIDBKeyval 默认通过 BroadcastChannel 在多个标签页间同步；设置 listenToStorageChanges: false 可禁用（dist/useIDBKeyval.js:60-76, https://github.com/vueuse/vueuse/pull/5338）。
3. 不再支持 Node.js 20；需要 Node >= 22（https://github.com/vueuse/vueuse/releases/tag/v15.0.0）。
4. drauu 的 peer 依赖范围扩大为 ^1 || ^0.4（https://github.com/vueuse/vueuse/pull/5595）。

详情和迁移代码：参见迁移参考。

快速示例

useAxios

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

// Awaits the whole result; rejects on error
const { data, error } = await useAxios('/api/posts')

// Manual trigger without firing immediately
const { execute } = useAxios('/api/posts', { method: 'GET' }, { immediate: false })

// Typed data via initialData (data becomes Ref<T> instead of Ref<T | undefined>)
const { data } = useAxios<User[]>('/api/users', undefined, { initialData: [] })

execute() 接受 url、config 或两者。默认选项：immediate（仅当传入 url 字符串时为 true）、shallow: true、abortPrevious: true、resetOnExecute: false（dist/useAxios.js:13-17,35）。

useIDBKeyval

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

const { data: count, set } = useIDBKeyval('my-count', 0)
count.value++          // watched, persisted automatically
await set(10)          // explicit write, resolves after the IDB transaction
count.value = null     // deletes the key

useSortable

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

const list = ref(['a', 'b', 'c'])
const { start, stop, option } = useSortable(el, list, {
  watchElement: true, // reinitialize when el appears/disappears (v-if)
})

默认的 onUpdate 处理器会自动移动数组元素（dist/useSortable.js:14-16）。传入自定义 onUpdate 可覆盖默认行为；如需手动移动，请使用 moveArrayElement(list, from, to, e)。

useFocusTrap

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

const target = useTemplateRef<HTMLElement>('modal')
const { activate, deactivate, hasFocus } = useFocusTrap(target, { immediate: true })

async function open() {
  show.value = true
  await nextTick() // wait for v-if to render the element
  activate()
}

容器元素的变化会自动跟踪；返回对象为 { hasFocus, isPaused, activate, deactivate, pause, unpause }，不包含 updateContainerElements（dist/useFocusTrap.js:37-66）。

useCookies

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

const { get, set, remove } = useCookies(['token'], { autoUpdateDependencies: true })

对于 SSR，请使用 createCookies(req) 从请求创建组合式函数（dist/useCookies.d.ts:4-9）。在 Nuxt 中，请显式导入以避免与 Nuxt 的 useCookie 冲突。

useFuse

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

const search = ref('')
const { results } = useFuse(search, data, {
  fuseOptions: { keys: ['title'] },
  resultLimit: 10,
  matchAllWhenSearchEmpty: true,
})

其他封装

useChangeCase('hello world', 'camelCase')   // writable computed; type must match a change-case *Case export
useDrauu(svgEl, { brush: { color: 'red' } }) // target must be an <svg> element
useJwt(token)                                // { header, payload } with fallbackValue on decode error
useNProgress()                               // { isLoading, progress, start, done, remove }
useQRCode('https://vueuse.org')              // ShallowRef<string> of a data URL
useAsyncValidator(form, rules, { manual: true }) // thenable; { pass, errors, execute }

使用 useDrauu、useNProgress、useQRCode 或 useAsyncValidator 编写较复杂代码前，请参阅用法模式。

环境限制

• Vue ^3.5.0 peer 依赖（package.json:68）。
• 仅支持 ESM；从 v13.0.0 起不再提供 CommonJS 构建（https://github.com/vueuse/vueuse/releases/tag/v13.0.0）。
• Node >= 22（package.json:53）。
• useQRCode 仅在浏览器中渲染（isClient 守卫，dist/useQRCode.js:16）。
• useIDBKeyval 的标签页同步需要 BroadcastChannel；isSupported 会报告其支持情况（dist/useIDBKeyval.js:18）。