vueuse-components-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vueuse/vueuse

@vueuse/components

vueuse/vueuse

@vueuse/components

Version: 14.2.1 (Feb 2026) Deps: @vueuse/shared@14.2.1, @vueuse/core@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/shared@14.2.1，@vueuse/core@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问题 — 问题反馈、解决方案、边界情况 • GitHub讨论 — 问答、模式、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes for

@vueuse/components

— prioritize recent major/minor releases.

BREAKING:
```
@vueuse/components
```
v14+ requires Vue 3.5+, following core library requirements source
BREAKING: Renderless components refactored for consistency in v14.0.0. Components like
```
OnClickOutside
```
and
```
OnLongPress
```
now use an
```
options
```
prop for configuration and
```
@trigger
```
emit for actions source
BREAKING: ESM-only package — CJS build has been dropped since v13.0.0 source
DEPRECATED:
```
VOnClickOutside
```
is deprecated in favor of the lowercase
```
vOnClickOutside
```
directive source
DEPRECATED:
```
VOnLongPress
```
is deprecated in favor of the lowercase
```
vOnLongPress
```
directive source
NEW:
```
UseDraggable
```
supports
```
autoScroll
```
and
```
restrictInView
```
options for constrained dragging in v14.2.0 source
NEW:
```
UseDraggable
```
supports
```
storageKey
```
and
```
storageType
```
props for persistent element position source
NEW:
```
vOnKeyStroke
```
directive added for listening to keyboard events directly on elements
NEW:
```
UseIdle
```
default slot data now includes
```
pause
```
and
```
resume
```
methods via
```
Stoppable
```
implementation source
NEW:
```
vInfiniteScroll
```
supports reactive
```
canLoadMore
```
option in v14.1.0 source
NEW:
```
UseElementVisibility
```
added
```
initialValue
```
option in v14.1.0 source
NEW:
```
UseMouseInElement
```
supports tracking inline-level elements in v14.1.0 source
NEW:
```
vIntersectionObserver
```
now supports reactive
```
rootMargin
```
option in v14.2.0 source

NEW:

UseOffsetPagination

emits

page-change

page-size-change

, and

page-count-change

events

Also changed:

useTransition

custom interpolators ·

refManualReset

new function ·

tryOnScopeDispose

failSilently ·

useAsyncState

execute result ·

useTimeAgoIntl

custom units

本节记录

@vueuse/components

各版本的API变更信息——优先参考近期的大版本/小版本更新。

破坏性变更：
```
@vueuse/components
```
v14+要求Vue 3.5+，遵循核心库的要求来源
**破坏性变更：**无渲染组件在v14.0.0中进行了重构以保持一致性。
```
OnClickOutside
```
和
```
OnLongPress
```
等组件现在使用
```
options
```
属性进行配置，通过
```
@trigger
```
事件触发操作来源
**破坏性变更：**仅支持ESM的包——自v13.0.0起已移除CJS构建版本来源
已废弃：
```
VOnClickOutside
```
已被废弃，推荐使用小写形式的
```
vOnClickOutside
```
指令来源
已废弃：
```
VOnLongPress
```
已被废弃，推荐使用小写形式的
```
vOnLongPress
```
指令来源
新增：
```
UseDraggable
```
在v14.2.0中支持
```
autoScroll
```
和
```
restrictInView
```
选项，用于约束拖拽范围来源
新增：
```
UseDraggable
```
支持
```
storageKey
```
和
```
storageType
```
属性，用于持久化元素位置来源
**新增：**添加了
```
vOnKeyStroke
```
指令，用于直接在元素上监听键盘事件
新增：
```
UseIdle
```
的默认插槽数据现在通过
```
Stoppable
```
实现包含
```
pause
```
和
```
resume
```
方法来源
新增：
```
vInfiniteScroll
```
在v14.1.0中支持响应式的
```
canLoadMore
```
选项来源
新增：
```
UseElementVisibility
```
在v14.1.0中添加了
```
initialValue
```
选项来源
新增：
```
UseMouseInElement
```
在v14.1.0中支持跟踪内联级元素来源
新增：
```
vIntersectionObserver
```
在v14.2.0中现在支持响应式的
```
rootMargin
```
选项来源

新增：

UseOffsetPagination

触发

page-change

、

page-size-change

和

page-count-change

事件

其他变更：

useTransition

自定义插值器 ·

refManualReset

新函数 ·

tryOnScopeDispose

静默失败 ·

useAsyncState

执行结果 ·

useTimeAgoIntl

自定义单位

Best Practices

最佳实践

Use the
```
storage-key
```
and
```
storage-type
```
props on the
```
<UseDraggable>
```
component to automatically persist element position in
```
localStorage
```
or
```
sessionStorage
```
across sessions source
Utilize the
```
ignore
```
option in
```
OnClickOutside
```
(component or directive) to pass an array of refs or CSS selectors for elements that should not trigger the handler, essential for complex UIs like nested modals source
Always provide
```
#loading
```
and
```
#error
```
slots in
```
<UseImage>
```
to prevent layout shifts and handle broken images gracefully, rather than managing loading states manually in the script source
Prefer
```
createReusableTemplate
```
over extracting small, repeated UI fragments into separate files to maintain access to local scope variables and avoid tedious prop/emit definitions source
Provide a generic type to
```
createReusableTemplate<T>()
```
to enable full TypeScript support and IDE autocompletion for data passed between
```
DefineTemplate
```
and
```
ReuseTemplate
```
source
Use
```
createTemplatePromise
```
to call complex UI elements like modals or dialogs as promises, keeping the UI definition in the template while maintaining programmatic control and clean async/await flows source
Configure
```
@vueuse/components
```
directives like
```
v-on-click-outside
```
or
```
v-on-long-press
```
using the
```
[handler, options]
```
array syntax for clean, inline logic without needing a separate setup variable for options source

vue

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

Use the
```
<UseOffsetPagination>
```
component to handle complex pagination state; it emits clean events (
```
page-change
```
,
```
page-size-change
```
) that are more idiomatic and easier to wire up in templates than manually watching refs source
Set
```
detectIframe: true
```
in
```
onClickOutside
```
options when building global navigation or modals to ensure they close when the user clicks inside an iframe, an edge case often missed in manual implementations source
Utilize the
```
as
```
prop on renderable components like
```
<UseElementBounding>
```
or
```
<UseFullscreen>
```
to render them as semantically correct HTML elements (e.g.,
```
section
```
,
```
nav
```
) instead of the default
```
div
```
source

在
```
<UseDraggable>
```
组件上使用
```
storage-key
```
和
```
storage-type
```
属性，可在
```
localStorage
```
或
```
sessionStorage
```
中自动持久化元素位置，跨会话保留来源
在
```
OnClickOutside
```
（组件或指令）中使用
```
ignore
```
选项，传入ref数组或CSS选择器，指定不应触发处理函数的元素，这对于嵌套模态框等复杂UI至关重要来源
始终在
```
<UseImage>
```
中提供
```
#loading
```
和
```
#error
```
插槽，以防止布局偏移并优雅地处理图片加载失败的情况，而不是在脚本中手动管理加载状态来源
优先使用
```
createReusableTemplate
```
，而不是将小型重复UI片段提取到单独文件中，这样可以保持对局部作用域变量的访问，避免繁琐的属性/事件定义来源
为
```
createReusableTemplate<T>()
```
提供泛型类型，以启用完整的TypeScript支持和IDE自动补全，用于在
```
DefineTemplate
```
和
```
ReuseTemplate
```
之间传递的数据来源
使用
```
createTemplatePromise
```
将模态框或对话框等复杂UI元素作为Promise调用，将UI定义保留在模板中，同时保持程序化控制和清晰的async/await流程来源
使用
```
[handler, options]
```
数组语法配置
```
@vueuse/components
```
指令，如
```
v-on-click-outside
```
或
```
v-on-long-press
```
，实现简洁的内联逻辑，无需为选项单独设置变量来源

vue

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

使用
```
<UseOffsetPagination>
```
组件处理复杂的分页状态；它触发清晰的事件（
```
page-change
```
、
```
page-size-change
```
），比手动监听ref更符合Vue的惯用写法，也更容易在模板中连接逻辑来源
当构建全局导航或模态框时，在
```
onClickOutside
```
选项中设置
```
detectIframe: true
```
，确保用户点击iframe内部时导航或模态框能关闭，这是手动实现中常被忽略的边界情况来源
在
```
<UseElementBounding>
```
或
```
<UseFullscreen>
```
等可渲染组件上使用
```
as
```
属性，将它们渲染为语义正确的HTML元素（如
```
section
```
、
```
nav
```
），而不是默认的
```
div
```
来源