vueuse-core-skilld

@vueuse/core 15.0.0

准备好的源代码：@vueuse/[email protected]（package.json:4）。以下文件引用使用相对于该包根目录的路径。文档引用为绝对 URL。

环境限制

• 自 v13 起仅支持 ESM（"type": "module"，package.json:3）。require() 会失败。
• 需要 Vue ^3.5.0（package.json:42）。
• 需要 Node.js >= 22（package.json:39）；v15.0.0 起不再支持 Node 20（发布说明）。
• 导出：. 和 ./metadata（package.json:24-28）。所有内容均从 dist/ 提供。
• @vueuse/[email protected] 是一个依赖项，并且已完整重新导出（dist/index.d.ts:3），因此 import { useToggle } from '@vueuse/core' 可以正常使用；请参阅共享 API。

会改变生成代码的 v15 规则

1. 不再有 templateRef。 已在 v15.0.0 中移除（发布说明）。请改用 Vue 内置的 useTemplateRef()。
2. 定时器选项已移除；请传入 scheduler。 v15.0.0 中，ConfigurableScheduler 组合式函数已移除弃用的逐个组合式函数的 interval / immediate 选项（发布说明）。受影响的选项接口会扩展或交叉组合 ConfigurableScheduler（dist/index.d.ts:212-217）：useCountdown、useNow、useTimestamp、useTimeAgo、useTimeAgoIntl、useTemporalNow、useElementByPoint、useMemory、useVibrate，以及 useWebSocket 的 heartbeat 选项。scheduler 的类型为 (cb: Fn) => Pausable，因此可以直接接入 useRafFn。
3. useThrottleFn 现在默认会触发尾随调用（trailing 的默认值从 false 改为 true，v15.0.0（发布说明））。传入 trailing = false（第 3 个参数）即可保持 v14 的行为。
4. useEventSource 会处理 SSE message 事件，并同时触发 onmessage 和 addEventListener 处理程序（v15.0.0（发布说明））。对于未命名事件，请勿手动添加重复监听器。
5. 下一个主版本将更改 deepRefs 的默认值。 目前默认值为 true，并明确警告下一个主版本会将其改为 false（dist/index.d.ts:204-211）。如果该值很重要，请显式传入 deepRefs。

请勿使用（已弃用或已替换）

导出项	替代方案	依据
computedEager	computed()（Vue 3.4+ 在值未改变时不再重新触发）	文档“将在未来版本中移除”
watchPausable	Vue 3.5 原生 watch() 会返回 { stop, pause, resume }	文档
executeTransition	transition(source, from, to, options)	在 dist/index.d.ts:5114-5121 中标记为已弃用
UseTransitionOptions.transition	easing 选项	同一弃用代码块
breakpointsVuetify	breakpointsVuetifyV2 或 breakpointsVuetifyV3	在 dist/index.d.ts:758-762 中标记为已弃用
asyncComputed	computedAsync（别名仍保留，dist/index.d.ts:46）	computedAsync 的别名

常见任务

import { useLocalStorage, useDark, useTitle, useThrottleFn } from '@vueuse/core'

// Reactive getter args enable derived values without computed()
const isDark = useDark()
const title = useTitle(() => isDark.value ? 'Night' : 'Day')

// Storage with schema evolution: mergeDefaults fills new keys
const settings = useLocalStorage('settings', { theme: 'light', density: 'comfortable' }, { mergeDefaults: true })

// v15 throttle fires a trailing call by default; 3rd arg is `trailing`
const onResize = useThrottleFn(handler, 200, false, true) // trailing=false, leading=true

import { useWebMCP } from '@vueuse/core'

// Register a WebMCP tool for browser agents (new in v15)
const { isSupported, isRegistered, error } = useWebMCP({
  name: 'get-current-user',
  description: 'Returns the signed-in user id',
  inputSchema: { type: 'object' },
  execute: () => ({ userId: user.value?.id ?? null }),
})

更多模式：最佳实践。

参考资料

• API 概览：完整的 v15 导出清单，按类别分组。
• 共享 API：由 core 重新导出的 @vueuse/shared 函数。
• v14 到 v15 迁移：自 v14.3.0 起所有不兼容变更、功能和重要修复，均附有引用。
• v15 新增函数：useWebMCP、useTemporalNow、useLiveAnnouncer、useElementOverflow 的用法。
• 最佳实践：getter、事件过滤器、存储序列化器、调度器、SSR、作用域。

调试说明（v15 修复可能解释行为变化）

• useFetch 会忽略较新请求启动后返回的过时成功响应，并会忽略重新获取成功后返回的过时中止错误 （v15， v14.4）。
• useWebSocket 会忽略来自已被替代套接字的消息，并在显式调用 close() 后将状态同步为 CLOSED（同上版本）。
• useResizeObserver 使用 instanceof Element 检查来保护 observe()，因此 Vue 注释节点不再导致崩溃（v15）。
• 指针处理：useDraggable 和 usePointerSwipe 会在 pointercancel 时结束，usePointer 会重置 isInside，onLongPress 会清除待处理的按压 （v15， v14.4）。