跳到主要内容

useElementVisibility

分类
导出大小
793 B
上次更改
2 个月前

跟踪元素在视口中的可见性。

演示

右下角的信息
目标元素 (向下滚动)
元素在视口外部

用法

vue
<script setup lang="ts">
import { 
useElementVisibility
} from '@vueuse/core'
import {
useTemplateRef
} from 'vue'
const
target
=
useTemplateRef
<HTMLDivElement>('target')
const
targetIsVisible
=
useElementVisibility
(
target
)
</script> <template> <
div
ref
="
target
">
<
h1
>Hello world</
h1
>
</
div
>
</template>

rootMargin

如果你希望在元素完全可见之前更早地触发回调,你可以使用 rootMargin 选项 (参见 MDN IntersectionObserver/rootMargin)。

ts
const 
targetIsVisible
=
useElementVisibility
(target, {
rootMargin
: '0px 0px 100px 0px',
})

threshold

如果你想控制更新值所需的可见性百分比,你可以使用 threshold 选项 (参见 MDN IntersectionObserver/threshold)。

ts
const 
targetIsVisible
= useElementVisibility(target, {
threshold
: 1.0, // 100% visible
})

组件用法

此函数还通过 @vueuse/components 包提供了一个无渲染组件版本。了解更多用法

vue
<template>
  <UseElementVisibility v-slot="{ 
isVisible
}">
Is Visible: {{
isVisible
}}
</UseElementVisibility> </template>

指令用法

此函数还通过 @vueuse/components 包提供了一个指令版本。了解更多用法

vue
<script setup lang="ts">
import { 
vElementVisibility
} from '@vueuse/components'
import {
shallowRef
,
useTemplateRef
} from 'vue'
const
target
=
useTemplateRef
<HTMLDivElement>('target')
const
isVisible
=
shallowRef
(false)
function
onElementVisibility
(
state
) {
isVisible
.
value
=
state
} </script> <template> <
div
v-element-visibili
ty="
onElementVisibility
">
{{
isVisible
? 'inside' : 'outside' }}
</
div
>
<!-- with options --> <
div
ref
="
target
">
<
div
v-element-visibili
ty="
[
onElementVisibility
, {
scrollTarget
:
target
}]
">
{{
isVisible
? 'inside' : 'outside' }}
</
div
>
</
div
>
</template>

类型声明

ts
export interface UseElementVisibilityOptions
  extends ConfigurableWindow,
    
Pick
<
UseIntersectionObserverOptions
, "threshold"> {
/** * @see https://mdn.org.cn/en-US/docs/Web/API/IntersectionObserver/rootMargin */
rootMargin
?:
MaybeRefOrGetter
<string>
/** * The element that is used as the viewport for checking visibility of the target. */
scrollTarget
?:
MaybeRefOrGetter
<HTMLElement | undefined | null>
/** * Stop tracking when element visibility changes for the first time * * @default false */
once
?: boolean
} /** * Tracks the visibility of an element within the viewport. * * @see https://vueuse.org.cn/useElementVisibility */ export declare function
useElementVisibility
(
element
:
MaybeComputedElementRef
,
options
?: UseElementVisibilityOptions,
):
ShallowRef
<boolean, boolean>
export type
UseElementVisibilityReturn
=
ReturnType
<typeof
useElementVisibility
>

来源

源代码演示文档

贡献者

Anthony Fu
Anthony Fu
IlyaL
Scott Bedard
IlyaL
Dominik Ritter
wheat
Amr Bashir
SerKo
David Gonzalez
huiliangShen
ziolko-appfire
erikwu
Curt Grimes
vaakian X
sun0day
三咲智子
Jelf
webfansplz
AllenYu
Ary Raditya
Chung, Lian
Carlos Yanes
Alex Kozack

更新日志

8c521 - feat(components)!: 重构组件并使其保持一致 (#4912)
v12.8.0
7432f - feat(types): 废弃 MaybeRefMaybeRefOrGetter,转而使用 Vue 的原生类型 (#4636)
v12.6.0
f2f94 - feat: 添加 once 选项 (#4577)
v12.3.0
59f75 - feat(toValue): 废弃 @vueuse/shared 中的 toValue,转而使用 Vue 的原生函数
v12.1.0
3a928 - feat: 添加 rootMargin 选项 (#4100)
0a9ed - feat!: 放弃对 Vue 2 的支持,优化打包并清理 (#4349)
v10.8.0
ce9bb - fix(useElementVisiblity): 可配置阈值 (#3715)
v10.7.0
07d39 - fix: 使用最后一个交叉条目 (#3365)
v10.4.0
429ed - fix: 调整阈值为 0 以解决大型元素的可见性问题 (#3308)

根据 MIT 许可证发布。