Skip to content

useScroll

Category
Export Size
1.79 kB
Last Changed
3 months ago

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

Demo

左上角
左下角
右上角
右下角
滚动我
X 位置
Y 位置
正在滚动false
到达顶部
true
到达右侧
true
到达底部
true
到达左侧
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>

带偏移量

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

设置滚动位置

设置 xy 的值以使元素滚动到该位置。

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 选项。

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

指令用法

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>

Type Declarations

Show Type Declarations
typescript
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
  }
  /**
   * 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/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>

Source

SourceDemoDocs

Contributors

Anthony Fu
丶远方
Anthony Fu
IlyaL
webfansplz
kongmoumou
Curt Grimes
autofix-ci[bot]
Robin
719media
Dima Kaltovich
Poet
Nico Prat
MinatoHikari
Vladimir
AlanYu
Scott Bedard
Christian Martinez
holtergram
Ayaka Rizumu
云游君
btea
Thierry Michel
Pavel Yankovski
Bobakanoosh
Joseph Fitz Hughes

Changelog

v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
4b7ab - fix: handle negative scroll values (#4613)
v12.3.0 on
59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's native
a033e - feat(useWindowScroll): use useScroll under the hood (#4424)
v12.1.0 on
90ff4 - fix: to properly report arriveState for elastic scroll (#4133)
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v10.10.0 on
317ca - fix: sync scroll val to internal state, fix #3809 (#3817)
v10.8.0 on
fab86 - fix: add onError hook and avoid throws by default, fix #3580 (#3605)
v10.6.1 on
e9742 - fix: can not read properties of null (reading document) (#3544)
v10.6.0 on
86bd8 - fix: trigger once onMounted to get correct inital arrivedStates values (#3384)
v10.4.0 on
c1b29 - fix: evade edge case when window or document is Proxy (#3280)
v10.3.0 on
dde41 - fix: support configurable window (#3229)
v10.2.0 on
8855f - fix: support window in setArrivedState (#3086)
v10.1.1 on
a88fe - fix(useInfiniteScroll): re-measure arrived states when async infinite scroll resolves (#3030)
v10.0.0-beta.4 on
23b9a - fix: add support for row-reverse and column-reverse (#2577)
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue

Released under the MIT License.