useScroll

类别

Sensors

导出体积

1.79 kB

上次更改

3 months ago

响应式的滚动位置和状态。

示例

源码 playground (beta)

左上角

左下角

右上角

右下角

滚动我

X 位置

Y 位置

测量

平滑滚动正在滚动false

到达顶部

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">
    向右滚动 10px
  </button>
  <button @click="y += 10">
    向下滚动 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' })

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

Recalculate scroll state

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

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.

重新计算滚动状态

您可以随时调用 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()
  })
}

NOTE

推荐在 nextTick() 中调用 measure()，以确保 DOM 首先更新。滚动状态在 onMount 时自动初始化。只有在您希望在某些动态变化后重新计算状态时，才需要手动调用 measure()。

指令用法

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