如何使用

基础使用

只需要将组件包裹你的需要滚动内容，设置好容器大小，内容将自动允许滚动并设置滚动条（默认垂直滚动）。

TIP

滚动容器撑开父级，因此在未设置高度或者最大高度时，不会出现滚动条，需要设置一个确定的高度。

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

<template>
  <ScrollRect class="long-content" containerClass="content">
    <h1>Long content that can scroll</h1>
    <p>
      Hello. 
      This is a simple scroll rect component for Vue3.
      You can wrap your long content with this component. 
      So it can scroll.
    </p>  
    <p>It is easy to use!</p>
    <p>
      It provides a simple scrollbar that can fade out and help you unify the display style of each browser.
    </p>  
    <p>It is easy to use!</p>
    <h1>Long content that can scroll</h1>
    <p>
      Hello. 
      This is a simple scroll rect component for Vue3.
      You can wrap your long content with this component. 
      So it can scroll.
    </p>  
    <p>It is easy to use!</p>
    <p>
      It provides a simple scrollbar that can fade out and help you unify the display style of each browser.
    </p>  
    <p>It is easy to use!</p>
  </ScrollRect>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

<style lang="scss">
.long-content {
  width: 100%;
  height: 300px;
  color: #333;
  background-color: #efefef;

  .content {
    padding: 20px;
  }
}
</style>

滚动区域自动撑开

某些时候，你可能希望滚动区域在很小时自动撑开容器，超出指定高度时才开始滚动，则可以设置 maxHeight 或者 maxWidth 属性， 当内容高度超出设置的最大值之后，才开始滚动。

<template>
  <ScrollRect class="long-content2" containerClass="content" :maxHeight="300">
    <button @click="add">+ Add item</button>
    <p v-for="item in list" :key="item.id">
      {{ item.text }}
      <button @click="remove(item.text)">Delete</button>
    </p> 
  </ScrollRect>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ScrollRect } from '@imengyu/vue-scroll-rect';

const list = ref<{
  id: number,
  text: string,
}[]>([]);

let id = 0;

function add() {
  list.value.push({ id: ++id, text: id + ' Hello, This is a simple scroll rect component for Vue3.' }); 
}
function remove(id: number) {
  list.value.splice(list.value.findIndex(item => item.id === id), 1);
}
</script>

<style lang="scss">
.long-content2 {
  width: 100%;
  color: #333;
  background-color: #efefef;

  .content {
    padding: 20px;
  }
  p {
    margin: 0;
    padding: 10px;
    border-bottom: 1px solid #ccc;

    button {
      margin-bottom: 0;
    }
  }
  button {
    margin-bottom: 10px;
    margin-left: 10px;
  }
}
</style>

滚动方向

可以通过 scroll 属性设置仅垂直滚动或仅水平滚动，或者二者都滚动。

• both : 水平滚动和垂直滚动
• vertical : 垂直滚动
• horizontal : 水平滚动
• none : 禁止滚动

scroll: both

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

scroll: vertical

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

scroll: horizontal

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

scroll: none

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

<template>
  <div class="horiz-view">
    <ScrollRect class="long-content" scroll="both">
      <ScrollContent title="scroll: both" />
    </ScrollRect>
    <ScrollRect class="long-content" scroll="vertical">
      <ScrollContent title="scroll: vertical" />
    </ScrollRect>
    <ScrollRect class="long-content" scroll="horizontal">
      <ScrollContent title="scroll: horizontal" />
    </ScrollRect>
    <ScrollRect class="long-content" scroll="none">
      <ScrollContent title="scroll: none" />
    </ScrollRect>
  </div>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

<style lang="scss">
.horiz-view {
  display: flex;
  flex-direction: row;
  flex-wrap: wrap;

  > .long-content {
    flex: 1 1 50%;
    width: 50%;
    border: 1px solid #ccc;
  }
}
.long-content {
  padding: 20px;
}
</style>

下拉刷新

在滚动内容顶部继续向下拖动可触发刷新（指针：触摸或鼠标）。需将 scroll 设为 vertical 或 both；仅 horizontal 时不会启用。

开启 enablePullToRefresh 后，当 scrollTop === 0 时下拉，松手时若下拉距离不小于 pullToRefreshThreshold，会触发 pullToRefreshStart。请使用 v-model:pullToRefreshLoading 表示加载中：开始刷新时设为 true，数据就绪后设为 false；从加载态结束时组件会触发 pullToRefreshEnd。

TIP

在 pullToRefreshStart 中请 尽快（同步） 将 pullToRefreshLoading 设为 true，再执行异步请求，可避免顶部加载区域短暂闪烁。

属性	说明
enablePullToRefresh	是否启用下拉刷新，默认 false
pullToRefreshThreshold	触发刷新所需的最小下拉距离（像素），默认 50
pullToRefreshLoading	是否处于加载中，支持 v-model:pullToRefreshLoading，默认 false
pullRefreshLoadingHeight	加载时顶部提示区域高度（像素），默认 48
pullRefreshMaxDistance	最大下拉距离与阻尼参考（像素），默认 120

事件	说明
pullToRefreshStart	达到阈值并松手，应在此处开始刷新
pullToRefreshEnd	pullToRefreshLoading 从 true 变为 false 后触发

默认会显示「下拉加载 / 释放加载 / 加载中…」文案；可通过插槽 pullRefresh 完全自定义。插槽作用域参数：

名字	类型	说明
state	'idle' | 'pulling' | 'release' | 'loading'	当前状态
distance	number	当前下拉距离（像素）
threshold	number	与 pullToRefreshThreshold 相同
loading	boolean	与 pullToRefreshLoading 相同
loadingHeight	number	与 pullRefreshLoadingHeight 相同

可通过 CSS 变量调整默认样式，例如 --vue-scroll-rect-pull-refresh-text-color、--vue-scroll-rect-pull-refresh-font-size、--vue-scroll-rect-pull-refresh-spinner-color。

下拉加载

在顶部向下拖动即可触发刷新（约 1.5 秒模拟请求）

列表行 1

列表行 2

列表行 3

列表行 4

列表行 5

列表行 6

列表行 7

列表行 8

列表行 9

列表行 10

列表行 11

列表行 12

列表行 13

列表行 14

列表行 15

列表行 16

列表行 17

列表行 18

列表行 19

列表行 20

列表行 21

列表行 22

列表行 23

列表行 24

<template>
  <ScrollRect
    class="pull-demo"
    scroll="vertical"
    containerClass="content"
    :enable-pull-to-refresh="true"
    v-model:pull-to-refresh-loading="loading"
    :pull-to-refresh-threshold="50"
    @pull-to-refresh-start="onPullRefresh"
  >
    <p class="hint">在顶部向下拖动即可触发刷新（约 1.5 秒模拟请求）</p>
    <button @click="onClick">按钮</button>
    <p v-for="n in 24" :key="n" class="row">列表行 {{ n }}</p>
  </ScrollRect>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ScrollRect } from '@imengyu/vue-scroll-rect';

const loading = ref(false);

async function onPullRefresh() {
  loading.value = true;
  await new Promise<void>((resolve) => setTimeout(resolve, 1500));
  loading.value = false;
}
function onClick() {
  console.log('click!')
}
</script>

<style lang="scss">
.pull-demo {
  width: 100%;
  height: 280px;
  color: #333;
  background-color: #efefef;

  .content {
    padding: 12px 20px 20px;
  }
  .hint {
    margin: 0 0 12px;
    font-size: 13px;
    color: #666;
  }
  button {
    display: block
  }
  .row {
    margin: 0;
    padding: 8px 0;
    border-bottom: 1px solid #ddd;
  }
}
</style>

自定义下拉区域

<template>
  <ScrollRect
    scroll="vertical"
    :enable-pull-to-refresh="true"
    v-model:pull-to-refresh-loading="loading"
    @pull-to-refresh-start="onPullRefresh"
  >
    <template #pullRefresh="{ state, distance, threshold, loading: isLoading }">
      <div class="my-pull">
        <span v-if="isLoading">刷新中…</span>
        <span v-else-if="state === 'release'">松开刷新</span>
        <span v-else>下拉 {{ Math.round(distance) }} / {{ threshold }} px</span>
      </div>
    </template>
    <p v-for="n in 10" :key="n">内容 {{ n }}</p>
  </ScrollRect>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ScrollRect } from '@imengyu/vue-scroll-rect';

const loading = ref(false);

async function onPullRefresh() {
  loading.value = true;
  await new Promise<void>((r) => setTimeout(r, 800));
  loading.value = false;
}
</script>

返回顶部

设置 enableBackToTop 为 true 后，会在滚动容器内提供返回顶部区域（默认按钮或插槽）。仅当滚动偏移超过 backToTopThreshold 时才显示：vertical / both 看 scrollTop，horizontal / both 看 scrollLeft。点击后将滚动位置设回起点 (0, 0)，等价于实例方法 scrollToStart()。

默认按钮使用 opacity + translateY 渐变显隐（可通过 CSS 变量调整时长与位移）。也可通过模板 ref 调用 scrollToStart() 自行放置按钮。

属性	说明
enableBackToTop	是否启用返回顶部区域（默认按钮或 backToTop 插槽），默认 false
backToTopThreshold	超过该偏移量（像素）后显示按钮；both 时任一轴向超过即显示，默认 120

插槽 backToTop 可完全自定义按钮；作用域参数：

名字	类型	说明
onBackToTop	() => void	调用后滚动到起点，与 scrollToStart 一致
visible	boolean	是否应显示（与默认按钮显隐逻辑一致，便于自定义动画）

默认按钮样式可通过 CSS 变量覆盖：--vue-scroll-rect-back-to-top-bg、--vue-scroll-rect-back-to-top-bg-hover、--vue-scroll-rect-back-to-top-color、--vue-scroll-rect-back-to-top-transition-duration、--vue-scroll-rect-back-to-top-translate-y。

向下滚动后点击右下角按钮可回到顶部

列表行 1

列表行 2

列表行 3

列表行 4

列表行 5

列表行 6

列表行 7

列表行 8

列表行 9

列表行 10

列表行 11

列表行 12

列表行 13

列表行 14

列表行 15

列表行 16

列表行 17

列表行 18

列表行 19

列表行 20

列表行 21

列表行 22

列表行 23

列表行 24

列表行 25

列表行 26

列表行 27

列表行 28

列表行 29

列表行 30

列表行 31

列表行 32

<template>
  <ScrollRect
    class="btt-demo"
    scroll="vertical"
    containerClass="content"
    :enable-back-to-top="true"
  >
    <p class="hint">向下滚动后点击右下角按钮可回到顶部</p>
    <p v-for="n in 32" :key="n" class="row">列表行 {{ n }}</p>
  </ScrollRect>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

<style lang="scss">
.btt-demo {
  width: 100%;
  height: 300px;
  color: #333;
  background-color: #efefef;

  .content {
    padding: 12px 20px 20px;
  }
  .hint {
    margin: 0 0 12px;
    font-size: 13px;
    color: #666;
  }
  .row {
    margin: 0;
    padding: 8px 0;
    border-bottom: 1px solid #ddd;
  }
}
</style>

自定义返回顶部

<template>
  <ScrollRect scroll="vertical" :enable-back-to-top="true" containerClass="content">
    <template #backToTop="{ onBackToTop, visible }">
      <button
        type="button"
        class="my-back-top"
        :class="{ 'is-on': visible }"
        @click="onBackToTop"
      >
        ↑ Top
      </button>
    </template>
    <p v-for="n in 20" :key="n">内容 {{ n }}</p>
  </ScrollRect>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

<style lang="scss" scoped>
.my-back-top {
  position: absolute;
  right: 16px;
  bottom: 16px;
  z-index: 2;
  padding: 8px 12px;
  border: 1px solid #ccc;
  border-radius: 6px;
  background: #fff;
  cursor: pointer;
  opacity: 0;
  transform: translateY(8px);
  pointer-events: none;
  transition: opacity 0.25s ease, transform 0.25s ease;
}
.my-back-top.is-on {
  opacity: 1;
  transform: translateY(0);
  pointer-events: auto;
}
</style>

滚动条

滚动条样式

可以通过 css 修改滚动条样式颜色等等，有一些 css 变量可以用于修改滚动条样式。

名字	说明
--vue-scroll-rect-scrollbar-thumb-color	滚动条滑块的颜色
--vue-scroll-rect-scrollbar-thumb-color-light	滚动条滑块鼠标悬浮时的颜色
--vue-scroll-rect-scrollbar-thumb-color-pressed	滚动条滑块鼠标按下时的颜色
--vue-scroll-rect-scrollbar-thumb-radius	滚动条滑块半径
--vue-scroll-rect-scrollbar-thumb-margin	滚动条左右边距
--vue-scroll-rect-scrollbar-size	滚动条宽度

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

<template>
  <div class="horiz-view">
    <ScrollRect scrollBarAlwaysShow class="long-content scrollbar-style1" scroll="both">
      <ScrollContent />
    </ScrollRect>
    <ScrollRect scrollBarAlwaysShow class="long-content scrollbar-style2" scroll="both">
      <ScrollContent />
    </ScrollRect>
    <ScrollRect scrollBarAlwaysShow scrollBarBackgroundClickable class="long-content scrollbar-style3" scroll="both">
      <ScrollContent />
    </ScrollRect>
    <ScrollRect scrollBarAlwaysShow class="long-content scrollbar-style4" scroll="both">
      <ScrollContent />
    </ScrollRect>
  </div>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

<style lang="scss">
.scrollbar-style1 {
  --vue-scroll-rect-scrollbar-thumb-color: rgba(162, 145, 255, 0.3);
  --vue-scroll-rect-scrollbar-thumb-color-light: rgba(162, 145, 255, 0.5);
  --vue-scroll-rect-scrollbar-thumb-color-pressed: rgba(162, 145, 255, 0.2);
  --vue-scroll-rect-scrollbar-thumb-radius: 0px;
  --vue-scroll-rect-scrollbar-size: 12px;
}
.scrollbar-style2 {
  --vue-scroll-rect-scrollbar-thumb-color: rgba(162, 145, 255, 0.7);
  --vue-scroll-rect-scrollbar-thumb-color-light: rgba(162, 145, 255, 0.9);
  --vue-scroll-rect-scrollbar-thumb-color-pressed: rgba(162, 145, 255, 0.6);
  --vue-scroll-rect-scrollbar-thumb-radius: 20px;
  --vue-scroll-rect-scrollbar-size: 12px;
  --vue-scroll-rect-scrollbar-thumb-margin: 4px;
}
.scrollbar-style3 {
  --vue-scroll-rect-scrollbar-thumb-color-pressed: rgba(255, 255, 255, 0.6);
  --vue-scroll-rect-scrollbar-thumb-radius: 0px;
  --vue-scroll-rect-scrollbar-size: 12px;

  > .scrollbar {
    &.horizontal {
      border-top: 1px solid #0f0f0f;
    }
    &.vertical {
      border-left: 1px solid #0f0f0f;
    }
  }
}
.scrollbar-style4 {
  --vue-scroll-rect-scrollbar-thumb-color: rgba(0, 0, 0, 0.2);
  --vue-scroll-rect-scrollbar-thumb-color-light: rgba(0, 0, 0, 0.5);
  --vue-scroll-rect-scrollbar-thumb-color-pressed: rgba(0, 0, 0, 0.4);

  > .scrollbar {
    background-color: #333;
  }
}
</style>

滚动条常显示

滚动条默认是在鼠标移入后渐变显示，你可以设置 scrollBarAlwaysShow 属性为 true ，滚动条将一直显示。

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

<template>
  <ScrollRect class="long-content" scroll="both" :scrollBarAlwaysShow="true">
    <ScrollContent />
  </ScrollRect>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

设置 scrollBarBackgroundClickable 属性为 true ，滚动条背景点击区域也可触发滚动。

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

Long content that can scroll

Hello. This is a simple scroll rect component for Vue3. You can wrap your long content with this component. So it can scroll.

It is easy to use!

It provides a simple scrollbar that can fade out and help you unify the display style of each browser.

It is easy to use!

<template>
  <ScrollRect class="long-content scrollbar-background" scroll="both" :scrollBarAlwaysShow="true" :scrollBarBackgroundClickable="true">
    <ScrollContent />
  </ScrollRect>
</template>

<script setup lang="ts">
import { ScrollRect } from '@imengyu/vue-scroll-rect';
</script>

更换内置的滚动条

如果你希望换掉内置的滚动条，使用自己的滚动条组件，可以通过插槽 scrollBarX 和 scrollBarY 来实现。

插槽会传出当前滚动条滚动位置和计算长度数据 (scrollBarValue)，你可以根据这个百分比来计算滚动条的显示位置；传出 onScroll 回调用于控制滚动。。

scrollBarValue 结构如下：

名字	类型	类型
show	boolean	是否显示滚动条
size	number	滚动条计算长度（百分比，0-100）
sizeRaw	number	滚动条计算长度（像素）
pos	number	滚动条滚动位置（百分比，0-100）

onScroll 结构如下：

参数	类型
pos	number

<template>
  <ScrollRect class="long-content" scroll="both">
    <ScrollContent />
    <template #scrollBarY="{ scrollBarValue, onScroll }">
      <MyScrollBar :value="scrollBarValue.pos" :size="scrollBarValue.size" @update:value="onScroll" />
    </template>
  </ScrollRect>
</template>