vueuse-components-skilld

@vueuse/components 15.0.0

围绕 @vueuse/core 组合式函数构建的无渲染组件和指令封装。包含 46 个组件、14 个指令和 2 个已弃用的指令别名（dist/index.js:1237）。

事实（所有引文路径均位于已准备好的 @vueuse/components 包内）：

• 版本为 15.0.0（package.json:4）；依赖 @vueuse/core 15.0.0 和 @vueuse/shared 15.0.0（package.json:43-44）
• 对等依赖：vue ^3.5.0（package.json:40）
• Node.js >=22（package.json:37）；v15 起不再支持 Node 20
• 仅支持 ESM（"type": "module"，package.json:3）；不提供 CJS 构建
• sideEffects: false，支持 tree-shaking（package.json:22）；通过 unpkg/jsdelivr 提供 IIFE 包，供 CDN 使用（package.json:30-31）
• 安装：npm i @vueuse/components @vueuse/core（README.md:10，https://vueuse.org/guide/components）

组件的工作方式

组件分为两类，取决于它们渲染的内容（已通过 dist/index.js 验证）：

1. 纯无渲染组件：自身不创建 DOM，只渲染默认插槽；作用域插槽接收响应式组合式函数返回值。示例：UseMouse（dist/index.js:805-809）。
2. 元素封装组件：渲染一个元素（props.as || "div"），其 ref 会传入组合式函数，插槽内容则成为子元素。该元素是组合式函数的目标。示例：UseElementBounding（dist/index.js:340-345）。

元素封装组件：OnClickOutside、OnLongPress、UseDraggable、UseElementBounding、UseElementOverflow、UseElementSize、UseElementVisibility、UseFullscreen、UseImage（没有默认插槽时会渲染 img）、UseMouseInElement、UseMousePressed、UsePointerLock、UseScreenSafeArea、UseVirtualList（自身包含容器和包装 div）。

其余组件均为纯无渲染组件。完整目录包含 props、插槽数据和 emits：references/components.md。

常见任务

鼠标位置（官方指南中的模式，https://vueuse.org/guide/components）：

<template>
  <UseMouse v-slot="{ x, y }">
    x: {{ x }} y: {{ y }}
  </UseMouse>
</template>

深色模式切换；注意，UseDark 插槽数据为 { isDark, toggleDark }（dist/index.js:173-178）：

<template>
  <UseDark v-slot="{ isDark, toggleDark }">
    <button @click="toggleDark()">Is Dark: {{ isDark }}</button>
  </UseDark>
</template>

点击外部区域，组件写法。OnClickOutside 接收 options prop 并触发 trigger 事件；渲染的 div 是目标（dist/index.js:5-17）：

<OnClickOutside :options="{ ignore: [ignoreElRef] }" @trigger="close">
  <div>Click outside of me</div>
</OnClickOutside>

指令写法，使用 [handler, options] 元组绑定（dist/index.js:26-29）：

<script setup>
import { vOnClickOutside } from '@vueuse/components'
</script>

<template>
  <div v-if="modal" v-on-click-outside="[closeModal, { ignore: [ignoreElRef] }]">
    Hello World
  </div>
</template>

带有加载和错误插槽的图像（dist/index.js:763-770）：

<UseImage src="https://place.dog/300/200">
  <template #loading>Loading..</template>
  <template #error>Failed</template>
</UseImage>

带持久化位置的可拖动元素；storage-key 启用 useStorage 持久化，storage-type 选择 local（默认）或 session（dist/index.d.ts:157-168，dist/index.js:286-300）：

<UseDraggable storage-key="panel-pos" :initial-value="{ x: 10, y: 10 }" v-slot="{ x, y, style }">
  <div :style="style">Drag me at {{ x }}, {{ y }}</div>
</UseDraggable>

适用规则

• 从 @vueuse/components 以命名导出的方式导入组件和指令。没有 app.use() 插件；如有需要，请自行全局注册（app.component('UseMouse', UseMouse)）。
• 对于 On* 组件，通过 options prop 传递配置，并通过 @trigger 触发事件响应，而不是使用处理函数 props（dist/index.js:15-16, 66-68）。
• 对于元素包装组件，设置 as 来更改渲染的元素，例如 as="section"（dist/index.js:11）。例外：UseScreenSafeArea 的类型声明了 as，但其运行时 props 数组未包含该属性，因此始终渲染 div（dist/index.js:1096-1101 vs dist/index.d.ts:548-553）。
• UseIdle 必须传入 timeout prop（dist/index.d.ts:297-299）。
• UseVirtualList 必须传入 list 和 options props；height 默认为 300px；它通过模板 ref 暴露 scrollTo(index)（dist/index.d.ts:590-610, dist/index.js:1190-1206）。
• UseObjectUrl 仅在对象 URL 存在后才渲染其插槽；插槽 prop 是 URL 字符串（dist/index.js:906-915）。
• UseOffsetPagination 会通过 page-change、page-size-change、page-count-change 触发事件，并携带完整的分页状态（dist/index.js:918-951）。
• UsePointer 接受 target="window"（默认值）或 target="self"（dist/index.d.ts:463-465, dist/index.js:976-984）。
• 请勿使用已弃用的导出 VOnClickOutside 和 VOnLongPress；它们是 vOnClickOutside / vOnLongPress 的别名（dist/index.d.ts:17-18, 43-44）。
• 指令绑定值：处理函数，或 [handler, options] 元组；vElementSize 接受 [handler, initialSize, options]，而 vScrollLock 接受布尔值。详情和修饰符见：references/directives.md。

参考资料

• references/components.md — 全部 46 个组件的目录：props、插槽数据结构、触发事件、渲染的元素
• references/directives.md — 全部 14 个指令：绑定值形式、修饰符、处理函数载荷
• references/migration.md — v13 到 v15 的特定版本变更及官方发布页面 URL

官方文档：https://vueuse.org/guide/components