useElementVisibility

类别

Elements

导出大小

796 B

最近修改

7 months ago

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

🌐 Tracks the visibility of an element within the viewport.

示例

源代码在线运行

Info on the right bottom corner

Target Element (scroll down)

Element outside the viewport

用法

🌐 Usage

<script setup lang="ts">
import { useElementVisibility } from '@vueuse/core'
import { useTemplateRef } from 'vue'

const target = useTemplateRef('target')
const targetIsVisible = useElementVisibility(target)

const target2 = useTemplateRef('target2')
const targetVisibilityController = useElementVisibility(target2, { controls: true })
</script>

<template>
  <div ref="target">
    <h1>Hello world</h1>
  </div>

  <div ref="target2">
    <h1>Hi there</h1>
  </div>
</template>

rootMargin

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

🌐 If you wish to trigger your callback sooner before the element is fully visible, you can use the rootMargin option (See MDN IntersectionObserver/rootMargin).

TypeScript

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

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

threshold

如果你想控制更新值所需的可见性百分比，可以使用 threshold 选项（请参阅 MDN IntersectionObserver/threshold）。

🌐 If you want to control the percentage of the visibility required to update the value, you can use the threshold option (See MDN IntersectionObserver/threshold).

TypeScript

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

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

controls

默认情况下，useElementVisibility 会返回一个 ShallowRef<boolean>。设置 controls: true 以同时获取可见性引用和底层 useIntersectionObserver 的控件：

🌐 By default useElementVisibility returns a ShallowRef<boolean>. Set controls: true to receive the visibility ref together with the controls of the underlying useIntersectionObserver:

TypeScript

const { isVisible, isActive, pause, resume, stop, isSupported } = useElementVisibility(target, {
  controls: true,
})

'use strict'
const { isVisible, isActive, pause, resume, stop, isSupported } =
  useElementVisibility(target, {
    controls: true,
  })

状态	类型	描述
isVisible	ShallowRef<boolean>	目标当前是否在视口中可见。
isActive	ShallowRef<boolean>	观察者当前是否运行中。当观察者停止时，例如在 once: true 触发之后，转换为 false。
isSupported	ComputedRef<boolean>	IntersectionObserver API 是否可用。
pause	() => void	暂停观察并将 isActive 设置为 false。
resume	() => void	恢复观察。
stop	() => void	永久停止观察。

使用 once: true，读取 isActive 以判断在元素首次可见后跟踪是否已经停止：

🌐 With once: true, read isActive to tell whether tracking has already stopped after the element first became visible:

TypeScript

const { isVisible, isActive } = useElementVisibility(target, {
  controls: true,
  once: true,
})

'use strict'
const { isVisible, isActive } = useElementVisibility(target, {
  controls: true,
  once: true,
})

组件用法

🌐 Component Usage

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

指令用法

🌐 Directive Usage

<script setup lang="ts">
import { vElementVisibility } from '@vueuse/components'
import { shallowRef, useTemplateRef } from 'vue'

const target = useTemplateRef('target')
const isVisible = shallowRef(false)

function onElementVisibility(state) {
  isVisible.value = state
}

const target2 = useTemplateRef('target2')
const isVisible2 = shallowRef(false)

function onElementVisibilityWithControls(state) {
  isVisible2.value = state.isVisible.value
  if (state.isVisible.value) {
    state.stop()
  }
}
</script>

<template>
  <div v-element-visibility="onElementVisibility">
    {{ isVisible ? 'inside' : 'outside' }}
  </div>

  <!-- with options -->
  <div ref="target">
    <div v-element-visibility="[onElementVisibility, { scrollTarget: target }]">
      {{ isVisible ? 'inside' : 'outside' }}
    </div>
  </div>

  <!-- with controls -->
  <div ref="target2">
    <div v-element-visibility="[onElementVisibilityWithControls, { controls: true }]">
      {{ isVisible2 ? 'inside' : 'outside' }}
    </div>
  </div>
</template>