Scrollbar 滚动条（模拟）

介绍

通过触屏事件模拟的滚动条，解决小程序下 scroll-view 滚动状态获取、控制难的问题，功能与 Scroller 大致相同，在部分场景无法替代原 scroll-view，可根据场景选择使用。

基础用法

通过 @scroll 监听元素滚动的实时 scrollTop、scrollLeft 变化。

<vd-scrollbar
  scroll-x
  scroll-y
  @scroll="handleScroll"
>
  内容内容内容...
</vd-scrollbar>

import type { ScrollbarScrollEvent } from 'vital-design';

function handleScroll(info: ScrollbarScrollEvent) {
  console.log('滚动变化：', info);
}

滚动阴影

通过 shadow-x 和 shadow-y 控制滚动条的阴影效果。

<vd-scrollbar scroll-y shadow-y>
  内容内容内容...
</vd-scrollbar>

<!-- 单独设置Y轴顶部的阴影效果 -->
<vd-scrollbar scroll-y shadow-y="top">
  内容内容内容...
</vd-scrollbar>

设置滚动位置

通过 left、top 设置元素的滚动位置，你也可以通过组件提供的 scrollTo 方法设置滚动位置。

<vd-scrollbar
  ref="scrollbarRef"
  v-model:left="state.left"
  v-model:top="state.top"
  :scroll-y="true"
>
  内容内容内容...
</vd-scrollbar>

import { easing, bezier } from '@vital-design/shared';

const scrollbarRef = shallowRef();

const state = reactive({
  left: 0,
  top: 0,
});

// 通过双向绑定设置
function scrollTo1() {
  state.left = 100;
  state.top = 100;
}

// 通过方法设置（支持自定义动画曲线）
function scrollTo2() {
  scrollbarRef.value.scrollTo({
    left: 100,
    top: 100,
    animation: true,
    // animation: easing('ease'),
    // animation: bezier(0.25, 0.1, 0.25, 1),
  });
}

滚动到元素

通过组件提供的 scrollToView 方法滚动到元素。

<vd-scrollbar ref="scrollbarRef" :scroll-y="true">
  <div id="element1">元素元素元素</div>
  <div id="element2">元素元素元素</div>
  <div id="element3">元素元素元素</div>
</vd-scrollbar>

const scrollbarRef = shallowRef();
const instance = getCurrentInstance();

function scrollToView() {
  scrollbarRef.value.scrollToView({
    selector: '#element2',
    animation: true,
    instance,
  });
}

滚动回弹

通过 rebound-x 和 rebound-y 控制滚动条的回弹效果。

<vd-scrollbar scroll-y rebound-y>
  内容内容内容...
</vd-scrollbar>

<!-- 单独设置Y轴顶部的回弹效果 -->
<vd-scrollbar scroll-y rebound-y="top">
  内容内容内容...
</vd-scrollbar>

函数调用

使用 useScroll 方法，可实时获取 Scrollbar 组件状态与操作组件。

<vd-scrollbar name="page" :scroll-y="true">
  内容内容内容...
</vd-scrollbar>

// 指定标识名称
const { nearlyX, nearlyY, onScroll } = useScroll('page');

nearlyX; // 最近的横向滚动可滚动滚动条
nearlyY; // 最近的纵向滚动可滚动滚动条

// 滚动事件监听
onScroll(({ type, item, event }) => {
  if (event.type === 'scroll') {
    console.log('滚动：', event);
  }
  else if (event.type === 'updated') {
    console.log('更新：', event);
  }
  else if (event.type === 'scrolltoupper') {
    console.log('触顶部/左边：', event);
  }
  else if (event.type === 'scrolltolower') {
    console.log('触底部/右边：', event);
  }
});

自定义滑块样式

通过组件提供的 css 变量来自定义滑块样式。

<vd-scrollbar scroll-y custom-class="scrollbar-demo">
  内容内容内容...
</vd-scrollbar>

.scrollbar-demo {
  --vd-scrollbar-slider-size: 6px;
  --vd-scrollbar-slider-background: rgba(25, 137, 250, 0.3);
  --vd-scrollbar-slider-thumb-opacity: 1;
  --vd-scrollbar-slider-thumb-color: #1989fa;
}

API

Props

参数	说明	类型	默认值
name	标识名称	string	-
left	横向滚动条位置	string | number	-
top	纵向滚动条位置	string | number	-
debounce	尺寸计算防抖时间	string | number	false
animation	在设置滚动条位置时使用动画过渡	boolean	true
animation-executer	动画过渡执行方式，可选值为 css、js	ScrollbarAnimationExecuter	'css'
duration	动画时长	string | number	500
timing-function	动画过渡曲线函数	CssTimingFunction	'ease'
momentum	滑动滚动条滚动结束时使用惯性滚动	boolean	true
scroll-x	是否开启横向滚动	boolean	false
scroll-y	是否开启纵向滚动	boolean	false
shadow-x	横向滚动条阴影效果	boolean | 'left' | 'right'	false
shadow-y	纵向滚动条阴影效果	boolean | 'top' | 'bottom'	false
rebound-x	横向滚动条回弹效果	boolean | 'left' | 'right'	false
rebound-y	纵向滚动条回弹效果	boolean | 'top' | 'bottom'	false
slider-x	是否出现横向滑块	boolean	true
slider-y	是否出现竖向滑块	boolean	true
slider-always	是否一直显示滑块	boolean	false
upper-threshold	距顶部/左边触发触顶阈值	string | number	50
lower-threshold	距底部/右边触发触底阈值	string | number	50
content-class	内容节点类名	ClassValue	-
content-style	内容节点样式	StyleValue	-

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
scroll	滚动时触发	ScrollbarOnScrollEvent
resize	滚动尺寸变化时触发	ScrollbarOnResizeEvent
updated	滚动数据更新时触发	NodeScrollData
update:top	纵向滚动条位置更新时触发	number
update:left	横向滚动条位置更新时触发	number
scrolltoupper	触顶时触发	ScrollbarOnScrollThresholdEvent
scrolltolower	触底时触发	ScrollbarOnScrollThresholdEvent

Slots

名称	说明
default	自定义内容

Expose

方法名	说明	参数	返回值
scrollTo	滚动到指定位置	ScrollbarScrollToOption	-
scrollToView	滚动到指定元素	ScrollbarScrollToViewOption	-

类型定义

组件导出以下类型定义：

import type {
  ScrollbarScrollToOption,
  ScrollbarScrollToViewOption,
  ScrollbarOnResizeEvent,
  ScrollbarOnScrollEvent,
  ScrollbarOnScrollThresholdEvent,
} from 'vital-design';