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
横向滚动
最大高度
使用 max-height 属性限制最大高度。
1
2
3
最大高度
在 Nuxt 中使用
Scrollbar 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入，无需手动注册。
Nuxt SSR Item 1
Nuxt SSR Item 2
Nuxt SSR Item 3
Nuxt SSR Item 4
Nuxt SSR Item 5
Nuxt SSR Item 6
Nuxt SSR Item 7
Nuxt SSR Item 8
Nuxt SSR Item 9
Nuxt SSR Item 10
Nuxt 中使用
SSR 注意事项：
- ✅ 支持
height和max-height动态展示 - ✅ 自定义滑块在客户端激活，不影响服务端首屏渲染
- ✅ 原生滚动条降级模式 (native) 完美支持 SSR
API
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| height | 滚动条高度 | string / number | — | — |
| max-height | 滚动条最大高度 | string / number | — | — |
| native | 是否使用原生滚动条 | boolean | — | false |
| always | 滚动条总是显示 | boolean | — | false |
| min-size | 滚动条最小尺寸 | number | — | 20 |
| view-class | 视图的自定义类名 | string | — | — |
| view-style | 视图的自定义样式 | string / object / array | — | — |
| noresize | 不响应容器尺寸变化 | boolean | — | false |
| tag | 视图的元素标签 | string | — | div |
| theme-overrides | 主题覆盖变量 | ComponentThemeVars | — | — |
Events
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| scroll | 滚动事件 | { scrollLeft, scrollTop } |
Slots
| 插槽名 | 说明 | 插槽参数 |
|---|---|---|
default | 滚动容器内容。 | 无 |
Methods
| 方法名 | 说明 | 参数 |
|---|---|---|
| scrollTo | 滚动到指定位置 | (options: ScrollToOptions | number, y?: number) |
| setScrollTop | 设置滚动距离顶部的距离 | (value: number) |
| setScrollLeft | 设置滚动距离左侧的距离 | (value: number) |
| update | 手动更新滚动条状态 | — |
Expose
| 名称 | 说明 | 类型 |
|---|---|---|
wrap | 实际滚动容器元素引用。 | HTMLDivElement | undefined |
update | 手动更新滚动条状态。 | () => void |
scrollTo | 滚动到指定位置。 | (arg1: ScrollbarScrollToArg, arg2?: number) => void |
setScrollTop | 设置垂直滚动距离。 | (value: number) => void |
setScrollLeft | 设置水平滚动距离。 | (value: number) => void |
主题变量
Scrollbar 组件支持通过覆盖以下 CSS 变量来自定义局部样式：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-scrollbar-width | 滚动条宽度 | 6px |
--yh-scrollbar-thumb-color | 滑块颜色 | #c0c4cc |
--yh-scrollbar-thumb-hover-color | 滑块悬停颜色 | #909399 |
--yh-scrollbar-track-color | 轨道颜色 | transparent |
--yh-scrollbar-thumb-radius | 滑块圆角 | 3px |
类型导出
| 名称 | 说明 |
|---|---|
YhScrollbarProps | 组件 Props 类型 |
YhScrollbarEmits | 组件事件类型 |
YhScrollbarSlots | 组件插槽类型 |
YhScrollbarExpose | 组件 Expose 类型 |
YhScrollbarScrollPayload | 滚动事件负载类型 |
YhScrollbarScrollToArg | scrollTo 参数类型 |
YhScrollbarInstance | 组件实例类型 |