useScroll

分类

传感器

导出大小

2.22 kB

上次更改

4 个月前

响应式滚动位置和状态。

演示

源码演练场 (测试版)

左上角

左下角

右上角

右下角

滚动我

X 坐标

Y 坐标

测量

平滑滚动isScrollingfalse

到达顶部

true

到达右侧

false

到达底部

false

到达左侧

true

向上滚动

false

向右滚动

false

向下滚动

false

向左滚动

false

用法

vue

<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>

带偏移量

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

设置滚动位置

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

vue

<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>

平滑滚动

设置 behavior: smooth 来启用平滑滚动。behavior 选项默认为 auto，表示没有平滑滚动。有关更多信息，请参阅 window.scrollTo() 上的 behavior 选项。

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 })

重新计算滚动状态

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

这在例如动态内容更改后或您想在滚动事件之外重新计算滚动状态时非常有用。

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()。

指令用法

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

vue

<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-scrol
l="onScroll
">
    <div
 v-for="item
 in data
" :key
="item
">
      {{ item
 }}
    </div
>
  </div
>

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

类型声明

显示类型声明

export interface UseScrollOptions extends ConfigurableWindow {
  /**
   * Throttle time for scroll event, it’s disabled by default.
   *
   * @default 0
   */
  throttle
?: number
  /**
   * The check time when scrolling ends.
   * This configuration will be setting to (throttle + idle) when the `throttle` is configured.
   *
   * @default 200
   */
  idle
?: number
  /**
   * Offset arrived states by x pixels
   *
   */
  offset
?: {
    left
?: number
    right
?: number
    top
?: number
    bottom
?: number
  }
  /**
   * Use MutationObserver to monitor specific DOM changes,
   * such as attribute modifications, child node additions or removals, or subtree changes.
   * @default { mutation: boolean }
   */
  observe
?:
    | boolean
    | {
        mutation
?: boolean
      }
  /**
   * Trigger it when scrolling.
   *
   */
  onScroll
?: (e
: Event) => void
  /**
   * Trigger it when scrolling ends.
   *
   */
  onStop
?: (e
: Event) => void
  /**
   * Listener options for scroll event.
   *
   * @default {capture: false, passive: true}
   */
  eventListenerOptions
?: boolean | AddEventListenerOptions
  /**
   * Optionally specify a scroll behavior of `auto` (default, not smooth scrolling) or
   * `smooth` (for smooth scrolling) which takes effect when changing the `x` or `y` refs.
   *
   * @default 'auto'
   */
  behavior
?: MaybeRefOrGetter
<ScrollBehavior
>
  /**
   * On error callback
   *
   * Default log error to `console.error`
   */
  onError
?: (error
: unknown) => void
}
/**
 * Reactive scroll.
 *
 * @see https://vueuse.org.cn/useScroll
 * @param element
 * @param options
 */
export declare function useScroll
(
  element
: MaybeRefOrGetter
<
    HTMLElement | SVGElement | Window | Document | null | undefined
  >,
  options
?: UseScrollOptions,
): {
  x
: WritableComputedRef
<number, number>
  y
: WritableComputedRef
<number, number>
  isScrolling
: ShallowRef
<boolean, boolean>
  arrivedState
: {
    left
: boolean
    right
: boolean
    top
: boolean
    bottom
: boolean
  }
  directions
: {
    left
: boolean
    right
: boolean
    top
: boolean
    bottom
: boolean
  }
  measure
(): void
}
export type UseScrollReturn
 = ReturnType
<typeof useScroll
>