useScroll
反应式滚动位置和状态。
¥Reactive scroll position and state.
示例
用法
¥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.
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.
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>类型声明
显示类型声明
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>