useScroll

Demo

source

左上角

左下角

右上角

右下角

滚动我

X 位置

Y 位置

平滑滚动正在滚动false

到达顶部

true

到达右侧

false

到达底部

false

到达左侧

true

向上滚动

false

向右滚动

false

向下滚动

false

向左滚动

false

用法

vue

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

const el = ref<HTMLElement | null>(null)
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'

const el = ref<HTMLElement | null>(null)
const { x, y } = useScroll(el)
</script>

<template>
  <div ref="el" />
  <button @click="x += 10">
    向右滚动 10px
  </button>
  <button @click="y += 10">
    向下滚动 10px
  </button>
</template>

平滑滚动

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

TypeScript

import { useScroll } from '@vueuse/core'

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

// 或作为 `ref`：
const smooth = ref(false)
const behavior = computed(() => smooth.value ? 'smooth' : 'auto')
const { x, y } = useScroll(el, { behavior })

import { useScroll } from '@vueuse/core'
const el = ref(null)
const { x, y } = useScroll(el, { behavior: 'smooth' })
// 或作为 `ref`：
const smooth = ref(false)
const behavior = computed(() => (smooth.value ? 'smooth' : 'auto'))
const { x, y } = useScroll(el, { behavior })

指令用法

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

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

类型声明

显示类型声明

typescript

export interface UseScrollOptions extends ConfigurableWindow {
  /**
   * 滚动事件的节流时间，默认情况下禁用。
   *
   * @default 0
   */
  throttle?: number
  /**
   * 滚动结束时的检查时间。
   * 当配置了 `throttle` 时，该配置将设置为 (throttle + idle)。
   *
   * @default 200
   */
  idle?: number
  /**
   * 以 x 像素偏移到达状态
   *
   */
  offset?: {
    left?: number
    right?: number
    top?: number
    bottom?: number
  }
  /**
   * 滚动时触发。
   *
   */
  onScroll?: (e: Event) => void
  /**
   * 滚动结束时触发。
   *
   */
  onStop?: (e: Event) => void
  /**
   * 滚动事件的监听器选项。
   *
   * @default {capture: false, passive: true}
   */
  eventListenerOptions?: boolean | AddEventListenerOptions
  /**
   * 可选地指定滚动行为为 `auto`（默认，非平滑滚动）或 `smooth`（用于平滑滚动），在更改 `x` 或 `y` 引用时生效。
   *
   * @default 'auto'
   */
  behavior?: MaybeRefOrGetter<ScrollBehavior>
  /**
   * 错误回调
   *
   * 默认将错误记录到 `console.error`
   */
  onError?: (error: unknown) => void
}
/**
 * 响应式滚动。
 *
 * @see https://vueuse.org/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: Ref<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>