Skip to content

Scrollbar 滚动条 ​

用于替换浏览器原生滚动条,提供更一致的视觉体验和更强大的交互控制。

基础用法 ​

通过 height 属性设置滚动条高度。

基础用法

横向滚动 ​

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

横向滚动

最大高度 ​

使用 max-height 属性限制最大高度。示例默认提供更多条目,便于直接观察滚动效果和内容追加后的变化。

最大高度

在 Nuxt 中使用 ​

Scrollbar 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时,组件会自动导入,无需手动注册。

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滚动事件负载类型
YhScrollbarScrollToArgscrollTo 参数类型
YhScrollbarInstance组件实例类型

Released under the MIT License.