Scrollbar 滚动条 ​

用于替代浏览器原生滚动条。

基础用法 ​

使用 height 设置滚动区域高度;不传则按父容器高度自适应。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

横向滚动 ​

当内容宽度超过滚动容器宽度时出现横向滚动条。

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

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

滚动遮罩 ​

通过 mask 提示视口上、下、左、右方向仍有可滚动内容,默认关闭。

值行为
false关闭所有遮罩(默认)
true开启四个方向的遮罩,按实际溢出情况显示
'top'仅开启顶部遮罩
'bottom'仅开启底部遮罩
'left'仅开启左侧遮罩
'right'仅开启右侧遮罩
vue
<template>
  <u-scrollbar height="240px" mask />
  <u-scrollbar height="240px" mask="top" />
  <u-scrollbar height="240px" mask="bottom" />
  <u-scrollbar mask="left" />
  <u-scrollbar mask="right" />
</template>

纵向或横向滚动并切换遮罩模式。每个遮罩仅在该方向还有更多内容时出现,滚动到边缘后消失;没有溢出的轴不会显示遮罩,两个轴同时溢出时四个遮罩可同时出现。

Vertical scrolling

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

Horizontal scrolling

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

遮罩默认以 200ms 渐入渐出,使用 --u-transition-duration-fast;用户偏好减少动态效果时会关闭动画。遮罩不会拦截指针事件,也不会覆盖滚动条控件,同样适用于 native 模式。

left 与 right 指视口的物理左右边缘,容器设置 direction: rtl 时同样如此。

distance 属性仅影响 end-reached 事件,不影响遮罩出现的时机。使用 noresize 时,内容或容器尺寸变化后请调用 update() 刷新遮罩。

自定义遮罩 ​

可在 Scrollbar 组件上通过以下 CSS 变量自定义各方向遮罩:

CSS 变量说明默认值
--u-scrollbar-top-mask-height顶部遮罩高度40px
--u-scrollbar-bottom-mask-height底部遮罩高度40px
--u-scrollbar-left-mask-width左侧遮罩宽度40px
--u-scrollbar-right-mask-width右侧遮罩宽度40px
--u-scrollbar-top-mask-color顶部遮罩颜色var(--u-bg-color)
--u-scrollbar-bottom-mask-color底部遮罩颜色var(--u-bg-color)
--u-scrollbar-left-mask-color左侧遮罩颜色var(--u-bg-color)
--u-scrollbar-right-mask-color右侧遮罩颜色var(--u-bg-color)

默认颜色会跟随亮色或暗色主题。使用自定义背景时,请将遮罩颜色设置为与容器背景一致。上方示例将纵向遮罩高度与横向遮罩宽度设置为 48px。

最大高度 ​

仅当内容高度超过 max-height 时出现纵向滚动条。

1

2

3

手动滚动 ​

可调用 setScrollTop、setScrollLeft 方法程序化控制滚动位置。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

无限滚动 ​

滚动到底部时触发 end-reached,可用于无限加载。

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

滚动条 API ​

滚动条 属性 ​

名称说明类型默认值
height滚动区域高度string / number—
max-height最大高度string / number—
native是否使用原生滚动条样式booleanfalse
wrap-style外层包裹样式string / object—
wrap-class外层包裹 classstring—
view-style视图区域样式string / object—
view-class视图区域 classstring—
noresize不监听容器尺寸变化;容器尺寸不变时建议开启以优化性能booleanfalse
tag视图根元素标签stringdiv
always是否始终显示滚动条booleanfalse
mask渐变遮罩:true 为四个方向,传入方向值仅开启对应方向,false 关闭boolean / enumfalse
min-size滚动条滑块最小尺寸number20
id视图元素 idstring—
role a11y视图 rolestring—
aria-label a11y视图 aria-labelstring—
aria-orientation a11y视图 aria-orientationenum—
tabindex外层包裹容器 tabindexnumber / string—
distance触发 end-reached 的距离阈值(像素)number0

滚动条 事件 ​

事件名说明类型
scroll滚动时触发,参数含 scrollLeft、scrollTopFunction
end-reached滚动到达边缘时触发Function

滚动条 插槽 ​

名称说明
default默认内容

滚动条 方法 ​

名称说明类型
handleScroll处理滚动事件Function
scrollTo滚动到指定坐标Function
setScrollTop设置纵向滚动距离Function
setScrollLeft设置横向滚动距离Function
update手动更新滚动条状态Function
wrapRef外层包裹 DOM 引用object