useScroll

反应式滚动位置和状态。

¥Reactive scroll position and state.

示例

源代码演练场

TopLeft

BottomLeft

TopRight

BottomRight

Scroll Me

X Position

Y Position

Measure

Smooth scrollingisScrollingfalse

Top Arrived

true

Right Arrived

false

Bottom Arrived

false

Left Arrived

true

Scrolling Up

false

Scrolling Right

false

Scrolling Down

false

Scrolling Left

false

用法

¥Usage

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

const el = useTemplateRef<HTMLElement>('el')
const { x, y, isScrolling, arrivedState, directions } = useScroll(el)
</script>

<template>
  <div ref="el" />
</template>

使用偏移量

¥With offsets

const { x, y, isScrolling, arrivedState, directions } = useScroll(el, {
  offset: { top: 30, bottom: 30, right: 30, left: 30 },
})

设置滚动位置

¥Setting scroll position

设置 x 和 y 值以使元素滚动到该位置。

¥Set the x and y values to make the element scroll to that position.

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

const el = useTemplateRef<HTMLElement>('el')
const { x, y } = useScroll(el)
</script>

<template>
  <div ref="el" />
  <button @click="x += 10">
    Scroll right 10px
  </button>
  <button @click="y += 10">
    Scroll down 10px
  </button>
</template>

平滑滚动

¥Smooth scrolling

设置 behavior: smooth 以启用平滑滚动。behavior 选项默认为 auto，这意味着不平滑滚动。有关详细信息，请参阅 window.scrollTo() 上的 behavior 选项。

¥Set behavior: smooth to enable smooth scrolling. The behavior option defaults to auto, which means no smooth scrolling. See the behavior option on window.scrollTo() for more information.

TypeScript

import { useScroll } from '@vueuse/core'
import { useTemplateRef } from 'vue'

const el = useTemplateRef<HTMLElement>('el')
const { x, y } = useScroll(el, { behavior: 'smooth' })

// Or as a `ref`:
const smooth = ref(false)
const behavior = computed(() => smooth.value ? 'smooth' : 'auto')
const { x, y } = useScroll(el, { behavior })

import { useScroll } from '@vueuse/core'
import { useTemplateRef } from 'vue'
const el = useTemplateRef('el')
const { x, y } = useScroll(el, { behavior: 'smooth' })
// Or as a `ref`:
const smooth = ref(false)
const behavior = computed(() => (smooth.value ? 'smooth' : 'auto'))
const { x, y } = useScroll(el, { behavior })

重新计算滚动状态

¥Recalculate scroll state

你可以随时调用 measure() 方法手动更新滚动位置和 arrivedState。

¥You can call the measure() method to manually update the scroll position and arrivedState at any time.

这很有用，例如，在动态内容更改之后，或者当你想在滚动事件之外重新计算滚动状态时。

¥This is useful, for example, after dynamic content changes or when you want to recalculate the scroll state outside of scroll events.

TypeScript

import { useScroll } from '@vueuse/core'
import { nextTick, onMounted, useTemplateRef, watch } from 'vue'

const el = useTemplateRef<HTMLElement>('el')
const reactiveValue = shallowRef(false)

const { measure } = useScroll(el)

// In a watcher
watch(reactiveValue, () => {
  measure()
})

// Or inside any function
function updateScrollState() {
  // ...some logic
  nextTick(() => {
    measure()
  })
}

import { useScroll } from '@vueuse/core'
import { nextTick, useTemplateRef, watch } from 'vue'
const el = useTemplateRef('el')
const reactiveValue = shallowRef(false)
const { measure } = useScroll(el)
// In a watcher
watch(reactiveValue, () => {
  measure()
})
// Or inside any function
function updateScrollState() {
  // ...some logic
  nextTick(() => {
    measure()
  })
}

建议在 `nextTick()` 内部调用 `measure()`，以确保 DOM 先更新。滚动状态由 `onMount` 自动初始化。如果你希望在某些动态更改后重新计算状态，则只需手动调用 `measure()`。

¥[!NOTE] it's recommended to call measure() inside nextTick(), to ensure the DOM is updated first. The scroll state is initialized automatically onMount. You only need to call measure() manually if you want to recalculate the state after some dynamic changes.

指令用法

¥Directive Usage

<script setup lang="ts">
import type { UseScrollReturn } from '@vueuse/core'
import { vScroll } from '@vueuse/components'

const data = ref([1, 2, 3, 4, 5, 6])

function onScroll(state: UseScrollReturn) {
  console.log(state) // {x, y, isScrolling, arrivedState, directions}
}
</script>

<template>
  <div v-scroll="onScroll">
    <div v-for="item in data" :key="item">
      {{ item }}
    </div>
  </div>

  <!-- with options -->
  <div v-scroll="[onScroll, { throttle: 10 }]">
    <div v-for="item in data" :key="item">
      {{ item }}
    </div>
  </div>
</template>