Scrollbar 滚动条
用于替代浏览器原生滚动条。
基础用法
使用 height 设置滚动区域高度;不传则按父容器高度自适应。
横向滚动
当内容宽度超过滚动容器宽度时出现横向滚动条。
滚动遮罩
通过 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
Horizontal scrolling
遮罩默认以 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 时出现纵向滚动条。
手动滚动
可调用 setScrollTop、setScrollLeft 方法程序化控制滚动位置。
无限滚动
滚动到底部时触发 end-reached,可用于无限加载。
滚动条 API
滚动条 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| height | 滚动区域高度 | string / number | — |
| max-height | 最大高度 | string / number | — |
| native | 是否使用原生滚动条样式 | boolean | false |
| wrap-style | 外层包裹样式 | string / object | — |
| wrap-class | 外层包裹 class | string | — |
| view-style | 视图区域样式 | string / object | — |
| view-class | 视图区域 class | string | — |
| noresize | 不监听容器尺寸变化;容器尺寸不变时建议开启以优化性能 | boolean | false |
| tag | 视图根元素标签 | string | div |
| always | 是否始终显示滚动条 | boolean | false |
| mask | 渐变遮罩:true 为四个方向,传入方向值仅开启对应方向,false 关闭 | boolean / enum | false |
| min-size | 滚动条滑块最小尺寸 | number | 20 |
| id | 视图元素 id | string | — |
| role a11y | 视图 role | string | — |
| aria-label a11y | 视图 aria-label | string | — |
| aria-orientation a11y | 视图 aria-orientation | enum | — |
| tabindex | 外层包裹容器 tabindex | number / string | — |
| distance | 触发 end-reached 的距离阈值(像素) | number | 0 |
滚动条 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| scroll | 滚动时触发,参数含 scrollLeft、scrollTop | Function |
| end-reached | 滚动到达边缘时触发 | Function |
滚动条 插槽
| 名称 | 说明 |
|---|---|
| default | 默认内容 |
滚动条 方法
| 名称 | 说明 | 类型 |
|---|---|---|
| handleScroll | 处理滚动事件 | Function |
| scrollTo | 滚动到指定坐标 | Function |
| setScrollTop | 设置纵向滚动距离 | Function |
| setScrollLeft | 设置横向滚动距离 | Function |
| update | 手动更新滚动条状态 | Function |
| wrapRef | 外层包裹 DOM 引用 | object |