滚动条 Scrollbar

介绍

Scrollbar 基于 OverlayScrollbars 实现，用来替换宿主元素的原生滚动条表现，同时保留原生滚动能力、滚动事件和滚动定位能力。

这个组件处理了 target 元素的创建与销毁，外部只需要关心两类能力：

组件级兼容 props，例如 type、outerClass、outerStyle
底层 OverlayScrollbars 的配置与实例方法

如果你已经熟悉 OverlayScrollbars 原始文档，可以把 Scrollbar 看成一个 Vue 组件壳：

target 由组件内部容器托管
options 拆成了组件 props
eventListeners 通过 events prop 透传
实例方法通过组件 ref 直接暴露

基本用法

基于 OverlayScrollbars 的滚动条组件基础用法。

滚动条类型

设置 type 属性改变滚动条类型，track 类型会持续展示滚动条轨道。

底层参数透传

Scrollbar 把 OverlayScrollbars 常用配置拆成了独立 props，并额外保留了 overlayOptions 用于一次性传递完整底层配置对象。

暴露的方法

组件 ref 会暴露滚动快捷方法和 OverlayScrollbars 实例方法，适合命令式滚动、主动更新以及读取底层状态。

API

`<scrollbar>` Props

参数名	描述	类型	默认值
type	组件视觉类型。`embed` 使用嵌入式悬浮滚动条，`track` 始终展示轨道。	`'track' \| 'embed'`	`'embed'`
outer-class	外层根节点类名。	`string \| Record<string, any> \| unknown[]`	`-`
outer-style	外层根节点样式。	`CSSProperties \| CSSProperties[]`	`-`
padding-absolute	对应 `OverlayScrollbars` 的 `paddingAbsolute`。	`boolean`	`-`
show-native-overlaid-scrollbars	对应 `OverlayScrollbars` 的 `showNativeOverlaidScrollbars`。	`boolean`	`-`
update-options	对应底层 `update` 配置。	`ScrollbarOptions['update']`	`-`
overflow	对应底层 `overflow` 配置。	`ScrollbarOptions['overflow']`	`-`
scrollbars	对应底层 `scrollbars` 配置。	`ScrollbarOptions['scrollbars']`	`-`
overlay-options	完整底层 options，会与上述 props 合并。	`ScrollbarOptions`	`-`
events	初始化时注册到底层实例的事件监听集合。	`ScrollbarEventListeners`	`-`
hide	强制隐藏滚动条，主要用于组件内部兼容。	`boolean`	`false`
disable-horizontal	禁用横向滚动。	`boolean`	`false`
disable-vertical	禁用纵向滚动。	`boolean`	`false`

Props 合并规则

overlayOptions 作为完整底层配置的基础对象。
paddingAbsolute、showNativeOverlaidScrollbars、updateOptions、overflow、scrollbars 会覆盖 overlayOptions 中对应字段。
disableHorizontal 和 disableVertical 最终会强制对应轴的 overflow 为 hidden。
type 会提供默认主题类，hide 会提供默认的可见性策略；如果你显式传入 scrollbars.theme、scrollbars.visibility、scrollbars.autoHide，则以显式配置为准。

`<scrollbar>` Events

事件名	描述	参数
scroll	组件级滚动事件，底层触发 `scroll` 时同步向上抛出。	`ev: Event`

`events` Prop 支持的底层事件

events prop 与底层 OverlayScrollbars 的事件名保持一致。

事件名	描述	参数
initialized	初始化完成后触发。	`instance: OverlayScrollbars`
updated	底层实例更新且实际发生变化后触发。	`instance: OverlayScrollbars` `args: ScrollbarUpdatedEvent`
destroyed	实例销毁后触发。	`instance: OverlayScrollbars` `canceled: boolean`
scroll	视口滚动时触发。	`instance: OverlayScrollbars` `ev: Event`

`<scrollbar>` Methods

方法名	描述	参数	返回值	版本
getOSInstance	获取底层 `OverlayScrollbars` 实例。	-	`OverlayScrollbars \| null`
options	获取或更新底层 options。	`newOptions?: ScrollbarOptions` `pure?: boolean`	`ScrollbarOptionsResolved \| undefined`
on	绑定底层事件监听。	`eventListeners: ScrollbarEventListeners` 或 `name` / `listener`	`() => void \| undefined`
off	解绑底层事件监听。	`name` `listener`	`void`
update	主动触发一次底层更新。	`force?: boolean`	`boolean`
sleep	设置底层实例是否进入休眠。	`sleeping: boolean`	`void`
state	读取底层状态。	-	`ScrollbarState \| undefined`
elements	读取底层生成的元素引用。	-	`ScrollbarElements \| undefined`
plugin	获取底层插件实例。	`osPlugin: ScrollbarPlugin`	`unknown`
destroy	销毁底层实例。	-	`void`
scrollTo	滚动到指定位置。	`options: number \| { left?: number; top?: number }` `y?: number`	`void`
scrollTop	纵向滚动。	`top: number`	`void`	2.40.0
scrollLeft	横向滚动。	`left: number`	`void`	2.40.0

OverlayScrollbars Options 详解

`paddingAbsolute`

参数	说明	类型	默认值
padding-absolute	内容 padding 是否按绝对布局处理。	`boolean`	`false`

`showNativeOverlaidScrollbars`

参数	说明	类型	默认值
show-native-overlaid-scrollbars	原生 overlay scrollbars 是否仍然可见。	`boolean`	`false`

`updateOptions`

updateOptions 对应底层 update 配置对象，用于调节更新检测行为。

字段	说明	类型	默认值
elementEvents	指定哪些元素事件触发更新。	`Array<[string, string]> \| null`	`[['img', 'load']]`
debounce.mutation	`MutationObserver` 更新节流。	`[timeout?, maxWait?, leading?] \| number \| null`	`[0, 33]`
debounce.resize	`ResizeObserver` 更新节流。	`[timeout?, maxWait?, leading?] \| number \| null`	`null`
debounce.event	事件更新节流。	`[timeout?, maxWait?, leading?] \| number \| null`	`[33, 99]`
debounce.env	环境变化更新节流。	`[timeout?, maxWait?, leading?] \| number \| null`	`[222, 666, true]`
attributes	额外监听的属性名。	`string[] \| null`	`null`
ignoreMutation	过滤某些 mutation。	`(mutation: MutationRecord) => boolean`	`null`
flowDirectionStyles	自定义流向检测。	`(viewport: HTMLElement) => Record<string, unknown>`	`null`

`overflow`

字段	说明	类型	默认值
overflow.x	横向滚动策略。	`'hidden' \| 'scroll' \| 'visible' \| 'visible-hidden' \| 'visible-scroll'`	`'scroll'`
overflow.y	纵向滚动策略。	`'hidden' \| 'scroll' \| 'visible' \| 'visible-hidden' \| 'visible-scroll'`	`'scroll'`

`scrollbars`

字段	说明	类型	默认值
scrollbars.theme	滚动条主题类名。	`string \| null`	由 `type` 推导
scrollbars.visibility	可见性策略。	`'visible' \| 'hidden' \| 'auto'`	embed 为 `'auto'`，track 为 `'visible'`
scrollbars.autoHide	自动隐藏策略。	`'never' \| 'scroll' \| 'move' \| 'leave'`	embed 为 `'leave'`，track 为 `'never'`
scrollbars.autoHideDelay	自动隐藏延迟。	`number`	`1300`
scrollbars.autoHideSuspend	首次交互前是否挂起自动隐藏。	`boolean`	`false`
scrollbars.dragScroll	是否允许拖拽 handle。	`boolean`	`true`
scrollbars.clickScroll	是否允许点击轨道滚动。	`boolean \| 'instant' \| ((isHorizontal) => options)`	`'instant'`
scrollbars.pointers	响应的 pointer 类型。	`string[] \| null`	`['mouse', 'touch', 'pen']`

TypeScript

组件已经把底层常用类型从包入口抛出，可以直接从 @sdata/web-vue 导入。

import type {
  ScrollbarElements,
  ScrollbarEventListeners,
  ScrollbarExpose,
  ScrollbarInstance,
  ScrollbarOptions,
  ScrollbarOptionsResolved,
  ScrollbarProps,
  ScrollbarState,
  ScrollbarUpdatedEvent,
} from '@sdata/web-vue';

常用类型说明

类型名	说明
`ScrollbarProps`	组件完整 props 类型。
`ScrollbarInstance`	组件实例类型，包含 expose 的所有方法。
`ScrollbarExpose`	仅包含对外暴露方法的类型。
`ScrollbarOptions`	底层 `PartialOptions` 的别名，适合用作传入配置。
`ScrollbarOptionsResolved`	底层 `Options` 的别名，表示完整解析后的配置。
`ScrollbarEventListeners`	底层事件监听集合类型。
`ScrollbarUpdatedEvent`	`updated` 事件第二个参数类型。
`ScrollbarState`	`state()` 返回值类型。
`ScrollbarElements`	`elements()` 返回值类型。

全局原生滚动条样式

Scrollbar 组件只会替换它自身宿主元素的原生滚动条。如果希望页面内所有原生滚动条（视口、overflow: auto 容器等）也保持与组件一致的外观，可以为根元素加上设计系统类名，手动开启全局原生滚动条基线：

<!doctype html>
<html class="sd-design-system-scrollbar">
  <head>
    ...
  </head>
  <body>
    <!-- 文档树内的原生滚动条都会应用统一样式 -->
  </body>
</html>

加在 <html> 上会同时作用于视口滚动条与所有后代元素；只想作用于某个子树时，也可以加在对应的包裹元素上。

样式说明

全局基线与 Scrollbar 组件共用同一组 --sd-scrollbar-* CSS 变量（默认值取自组件 token）。在 :root、body 或任意祖先元素上覆盖这些变量，原生滚动条与 <Scrollbar> 组件会实时同步：

--sd-scrollbar-size：滚动条宽高（默认 6px）
--sd-scrollbar-thumb-radius：滑块圆角（默认 6px）
--sd-scrollbar-thumb-color / -hover / -active：滑块颜色（默认 --sd-color-neutral-4 / 5 / 6，随主题自动同步）

轨道透明。

覆盖示例（把全局滚动条加粗到 10px，原生滚动条与 Scrollbar 组件同步生效）：

:root {
  --sd-scrollbar-size: 10px;
}

实现遵循 MDN 建议：以现代标准属性 scrollbar-width: thin 与 scrollbar-color 为主，::-webkit-scrollbar 系列伪元素作为不支持标准属性时的回退。

当浏览器同时支持两者时（Chrome / Edge / Safari），标准属性会覆盖 ::-webkit-scrollbar 规则，而标准属性无法表达圆角与 hover/active 颜色。因此这些浏览器中全局原生滚动条为细条 + 灰色滑块 + 透明轨道，但不带圆角与交互态；圆角与 hover/active 仅在只支持 webkit 伪元素的浏览器中生效。若需在 Chrome 中也获得与组件完全一致的圆角与交互态，请直接使用 Scrollbar 组件。

类名前缀

该类名使用组件库的 CSS 类前缀（默认 sd，即 .sd-design，与 sd-button 等组件类一致）。它属于 CSS 类名，与快速上手中通过插件配置的组件标签前缀相互独立。

参考

底层行为、事件语义和字段定义与 OverlayScrollbars 文档保持一致。
组件额外提供 scrollTo、scrollTop、scrollLeft 三个快捷方法，以兼容现有 web-vue 组件调用方式。