Scroller 滚动条

介绍

与原 scroll-view 基本一致，添加了组件联动功能。

基础用法

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

<vd-scroller :scroll-y="true" @scroll="handleScroll">
  内容内容内容...
</vd-scroller>

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

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

设置滚动位置

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

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

const scrollerRef = shallowRef();

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

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

// 通过方法设置
function scrollTo2() {
  scrollerRef.value.scrollTo({
    left: 100,
    top: 100,
    animation: true,
  });
}

滚动到元素

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

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

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

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

函数调用

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

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

// 指定标识名称
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);
  }
});

API

Props

参数	说明	类型	默认值
name	标识名称	string	-
left	横向滚动条位置	string | number	-
top	纵向滚动条位置	string | number	-
animation	在设置滚动条位置时使用动画过渡	boolean	true
duration	动画时长	string | number	500
scroll-x	是否开启横向滚动	boolean	false
scroll-y	是否开启纵向滚动	boolean	false
shadow-x	横向滚动条阴影效果	boolean | 'left' | 'right'	false
shadow-y	纵向滚动条阴影效果	boolean | 'top' | 'bottom'	false
show-scrollbar	控制是否出现滚动条	boolean	true
scroll-anchoring	控制滚动位置不随内容变化而抖动（仅在 iOS 下生效）	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	滚动时触发	ScrollerOnScrollEvent
updated	滚动数据更新时触发	NodeScrollData
update:top	纵向滚动条位置更新时触发	number
update:left	横向滚动条位置更新时触发	number
scrolltoupper	触顶时触发	ScrollerOnScrollToUpperEvent
scrolltolower	触底时触发	ScrollerOnScrollToLowerEvent

Slots

名称	说明
default	自定义内容

Expose

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

类型定义

组件导出以下类型定义：

import type {
  ScrollerScrollToOption,
  ScrollerScrollToViewOption,
  ScrollerOnResizeEvent,
  ScrollerOnScrollEvent,
  ScrollerOnScrollThresholdEvent,
} from 'vital-design';