Element Plus Scrollbar 组件完全指南：替换原生滚动条、手动控制与无限滚动-平芜编程栈

Element Plus Scrollbar 组件完全指南：替换原生滚动条、手动控制与无限滚动

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus

Element Plus 的Scrollbar（滚动条）组件用于替换浏览器原生滚动条，提供跨平台一致的外观与交互，同时保留原生滚动行为。它广泛服务于 el-table、el-select、el-cascader、el-tree 等组件内部，也是业务中实现"隐藏原生滚动条 + 自定义美观滚动条"的通用方案。读完本文，你将掌握其全部配置属性、事件与方法，能实现固定高度滚动、横向滚动、按内容自适应高度、手动/编程式滚动控制，以及基于end-reached事件的无限滚动加载。本文以仓库内文档 docs/en-US/component/scrollbar.md 为主体，并结合组件源码与测试用例补充底层实现细节。

基本用法：用 height 固定滚动区域

Scrollbar通过height属性设定滚动区域高度，未设置时则按父容器高度自适应。文档示例（basic-usage.vue）如下：

<template> <el-scrollbar height="400px"> <p v-for="item in 20" :key="item" class="scrollbar-demo-item">{{ item }}</p> </el-scrollbar> </template> <style scoped> .scrollbar-demo-item { display: flex; align-items: center; justify-content: center; height: 50px; margin: 10px; text-align: center; border-radius: 4px; background: var(--el-color-primary-light-9); color: var(--el-color-primary); } </style>

height同时支持string与number两种类型（如400px或400）。从源码看，该属性最终通过addUnit统一补全单位后应用到内部 wrap 容器上，见 scrollbar.vue 中的wrapStyle计算逻辑：

const wrapStyle = computed<StyleValue>(() => { const style: CSSProperties = {} const height = addUnit(props.height) const maxHeight = addUnit(props.maxHeight) if (height) style.height = height if (maxHeight) style.maxHeight = maxHeight return [props.wrapStyle, style] })

值得注意：即使未显式传入height，只要父容器给出了确定高度并允许子元素滚动，Scrollbar同样可以工作——它内部没有对高度做强制断言，而是完全由实际渲染的 wrap 容器尺寸驱动滚动条计算。

横向滚动

当内容宽度超过滚动条宽度时，会自动出现横向滚动条。文档示例（horizontal-scroll.vue）通过flex布局撑宽内容并配合flex-shrink: 0防止子项被压缩：

<template> <el-scrollbar> <div class="scrollbar-flex-content"> <p v-for="item in 50" :key="item" class="scrollbar-demo-item">{{ item }}</p> </div> </el-scrollbar> </template> <style scoped> .scrollbar-flex-content { display: flex; width: fit-content; } .scrollbar-demo-item { flex-shrink: 0; display: flex; align-items: center; justify-content: center; width: 100px; height: 50px; margin: 10px; border-radius: 4px; background: var(--el-color-danger-light-9); color: var(--el-color-danger); } </style>

width: fit-content让内容容器宽度随子元素自适应，从而产生超出可视区的横向溢出。组件内部把横向与纵向滚动条分开渲染：bar.vue同时渲染一个水平Thumb和一个垂直Thumb（见 bar.vue），各自独立计算位移与尺寸，因此两个方向的滚动可以共存。

最大高度与自适应收起

max-height允许滚动条"按需出现"：内容未超出最大高度时不显示滚动条，超出后才出现。文档示例（max-height.vue）配合动态增删列表演示了这一行为：

<template> <el-button @click="add">Add Item</el-button> <el-button @click="onDelete">Delete Item</el-button> <el-scrollbar max-height="400px"> <p v-for="item in count" :key="item" class="scrollbar-demo-item">{{ item }}</p> </el-scrollbar> </template> <script lang="ts" setup> import { ref } from 'vue' const count = ref(3) const add = () => { count.value++ } const onDelete = () => { if (count.value > 0) { count.value-- } } </script>

实现层面，height/max-height的变化会触发专门的监听：组件watch这两个属性，在非native模式下于nextTick后调用update()重新测量内容并刷新滚动条（见 scrollbar.vue）。这是max-height模式下"内容增减后滚动条尺寸/显示状态正确刷新"的关键机制。

手动控制滚动：setScrollTop / setScrollLeft / scrollTo

Scrollbar将滚动方法通过defineExpose暴露给父组件（见 scrollbar.vue），从而可以在任意时机编程式控制滚动位置。文档示例（manual-scroll.vue）用滑块驱动滚动：

<template> <el-scrollbar ref="scrollbarRef" height="400px" always @scroll="scroll"> <div ref="innerRef"> <p v-for="item in 20" :key="item" class="scrollbar-demo-item">{{ item }}</p> </div> </el-scrollbar> <el-slider v-model="value" :max="max" :format-tooltip="formatTooltip" @input="inputSlider" /> </template> <script lang="ts" setup> import { onMounted, ref } from 'vue' import type { ScrollbarInstance } from 'element-plus' const max = ref(0) const value = ref(0) const innerRef = ref<HTMLDivElement>() const scrollbarRef = ref<ScrollbarInstance>() onMounted(() => { max.value = innerRef.value!.clientHeight - 380 }) const inputSlider = (value: number) => { scrollbarRef.value!.setScrollTop(value) } const scroll = ({ scrollTop }: { scrollTop: number }) => { value.value = scrollTop } </script>

组件对外暴露的方法汇总如下：

方法	说明	签名
`setScrollTop`	设置滚动到顶部的距离（垂直方向）	`(scrollTop: number) => void`
`setScrollLeft`	设置滚动到左侧的距离（水平方向）	`(scrollLeft: number) => void`
`scrollTo`	滚动到指定坐标，支持两种重载	`(options: ScrollToOptions) => void`或`(x: number, y: number) => void`
`update`	手动更新滚动条状态（如内容动态变化后重新测量）	`() => void`
`handleScroll`	处理滚动事件（内部方法，也可手动触发以同步滚动条）	`() => void`
`wrapRef`	内部滚动 wrap 容器的 DOM 引用	`Ref<HTMLDivElement>`

setScrollTop/setScrollLeft对入参做了严格校验：非数字时会通过debugWarn发出value must be a number的警告并直接返回，避免产生无效赋值（见 scrollbar.vue）。scrollTo则直接透传给 wrap 容器的原生scrollTo，支持ScrollToOptions与(x, y)两种调用形式（scrollbar.vue）。

无限滚动：end-reached 事件

从 2.10.0 版本开始，Scrollbar新增了end-reached事件：当滚动到达末尾时触发，可用于实现无限滚动（触底加载更多）。文档示例（infinite-scroll.vue）如下：

<template> <el-scrollbar height="400px" @end-reached="loadMore"> <p v-for="item in num" :key="item" class="scrollbar-demo-item">{{ item }}</p> </el-scrollbar> </template> <script lang="ts" setup> import { ref } from 'vue' import type { ScrollbarDirection } from 'element-plus' const num = ref(30) const loadMore = (direction: ScrollbarDirection) => { if (direction === 'bottom') { num.value += 5 } } </script>

end-reached的回调参数direction为'top' | 'bottom' | 'left' | 'right'，即到达的是哪个方向，可按需决定加载策略（如仅bottom时加载下一页）。事件类型定义见 scrollbar.ts。

distance：触发距离阈值

从 2.10.5 版本开始，distance属性（默认0）用于设置距离边缘多少像素时提前触发end-reached。这在"即将触底时预加载下一批数据"的场景非常实用，可以让加载过程对用户无感。distance大于0时，handleScroll会基于scrollHeight - distance <= clientHeight + scrollTop之类的判定提前报告到达（见 scrollbar.vue）：

const arrivedStates = { bottom: !isGreaterThan( wrapRef.value.scrollHeight - props.distance, wrapRef.value.clientHeight + wrapScrollTop ), top: wrapScrollTop <= props.distance && prevTop !== 0, right: !isGreaterThan( wrapRef.value.scrollWidth - props.distance, wrapRef.value.clientWidth + wrapScrollLeft ) && prevLeft !== wrapScrollLeft, left: wrapScrollLeft <= props.distance && prevLeft !== 0, }

组件内部还维护了distanceScrollState方向状态机，通过DIRECTION_PAIRS在"到达某端"与"离开对端"之间做去重：只有从非到达状态切入到达状态时才会触发一次end-reached，从而避免在末尾反复滚动时重复触发（scrollbar.vue）。

组件结构与渲染原理

Scrollbar的模板结构非常清晰（见 scrollbar.vue）：

<div class="el-scrollbar"> <div class="el-scrollbar__wrap" tabindex="..."> <component :is="tag" class="el-scrollbar__view"> <!-- slot --> </component> </div> <template v-if="!native"> <bar :always="always" :min-size="minSize" /> </template> </div>

wrap：真正发生滚动的容器，类名el-scrollbar__wrap；非native模式下会追加el-scrollbar__wrap--hidden-default类以隐藏原生滚动条（scrollbar.vue）；
view：内容视图容器，类名el-scrollbar__view，其标签类型由tag属性决定（默认div，可改为ul、section等）；
bar：仅在非native模式下渲染的自定义滚动条，内部再拆分为水平 / 垂直两个thumb（滑块）。

组件通过provide(scrollbarContextKey)向bar提供scrollbarElement与wrapElement引用，实现父子模块间通信（scrollbar.vue）。

滚动条尺寸与位移的计算

自定义滚动条滑块的长度和位移由 bar.vue 中的update计算：

const originalHeight = offsetHeight ** 2 / wrap.scrollHeight const originalWidth = offsetWidth ** 2 / wrap.scrollWidth const height = Math.max(originalHeight, props.minSize) const width = Math.max(originalWidth, props.minSize)

滑块长度近似为可视区高度² / 内容总高度（即内容越长滑块越短），并受min-size（默认 20px）兜底，防止内容过长时滑块过小难以点击。位移则在滚动时按(scrollTop * 100 / offsetHeight) * ratio换算为百分比 transform（bar.vue）。容器两端各留 2px 边距，即 util.ts 中的GAP = 4；垂直/水平方向的关键属性名统一封装在BAR_MAP（util.ts）中，滑块样式由renderThumbStyle生成：

export const renderThumbStyle = ({ move, size, bar }): CSSProperties => ({ [bar.size]: size, transform: `translate${bar.axis}(${move}%)`, })

这些计算均有对应测试佐证。在 scrollbar.test.tsx 的垂直滚动测试中，外层 204px、内层 500px 时滚动 100px，断言滑块样式包含transform: translateY(50%); height: 80px;，精确验证了上述公式；水平方向测试同样断言translateX(50%); width: 80px;。

响应式更新与 noresize 优化

组件默认通过useResizeObserver同时监听 view 容器与 wrap 容器的尺寸变化，并监听全局window resize事件，任一变化都会调用update重算滚动条（scrollbar.vue）。noresize置为true时则停止所有这些监听——如果你的容器尺寸确定不变，建议开启它以优化性能；此时若内容仍会变化，可手动调用暴露的update()刷新。此外，组件还会监听 wrap 的transitionend与animationend事件来更新滚动条，以覆盖 transform 驱动的过渡/动画场景（如幻灯片切换）中尺寸观测不到的问题（scrollbar.vue）。

组件在onMounted、onUpdated时都会刷新滚动条，并在onActivated（配合<KeepAlive>）时恢复之前记录的scrollTop/scrollLeft（scrollbar.vue）。

API 参考

以下 API 表完全继承自 docs/en-US/component/scrollbar.md，并结合 scrollbar.ts 的源码补充了类型与默认值细节。

Attributes

名称	说明	类型	默认值
`height`	滚动条高度	`string / number`	—
`max-height`	滚动条最大高度	`string / number`	—
`native`	是否使用原生滚动条样式	`boolean`	`false`
`wrap-style`	wrap 容器的样式	`string / object`（`CSSProperties \\| CSSProperties[] \\| string[]`）	—
`wrap-class`	wrap 容器的类名	`string`	—
`view-style`	view 容器的样式	`string / object`（同上）	—
`view-class`	view 容器的类名	`string`	—
`noresize`	不响应容器尺寸变化；若容器尺寸不变，建议开启以优化性能	`boolean`	`false`
`tag`	view 容器的元素标签	`string`	`div`
`always`	是否始终显示滚动条	`boolean`	`false`
`min-size`	滚动条最小尺寸	`number`	`20`
`id`（2.4.0+）	view 容器的 id	`string`	—
`role`（2.4.0+，a11y）	view 容器的 role	`string`	—
`aria-label`（2.4.0+，a11y）	view 容器的 aria-label	`string`	—
`aria-orientation`（2.4.0+，a11y）	view 容器的 aria-orientation	`enum`：`'horizontal' \\| 'vertical'`	—
`tabindex`（2.8.3+）	wrap 容器的 tabindex	`number / string`	—
`distance`（2.10.5+）	触发`end-reached`的距离阈值（px）	`number`	`0`

其中wrap-style/view-style在源码中通过definePropType<StyleValue>([String, Object, Array, Boolean])定义，因此除字符串外也支持 CSSProperties 对象与数组；wrap-class/view-class同理支持类名字符串、数组与对象。ariaLabel/ariaOrientation经由useAriaProps注入（scrollbar.ts）。

Events

名称	说明	类型
`scroll`	滚动时触发，返回滚动距离	`({ scrollLeft: number, scrollTop: number }) => void`
`end-reached`（2.10.0+）	滚动到末尾时触发	`(direction: 'top' \\| 'bottom' \\| 'left' \\| 'right') => void`

scroll事件在每次滚动时都会携带当前的scrollTop与scrollLeft（scrollbar.vue），可用于实现"滚动监听 + 双向同步"（如前述手动滚动示例中的滑块回显）。

Slots

名称	说明
`default`	自定义滚动区域内容

Exposes（通过 ref 访问）

名称	说明	类型
`handleScroll`	处理滚动事件	`() => void`
`scrollTo`	滚动到指定坐标	`(options: ScrollToOptions \\| number, yCoord?: number) => void`
`setScrollTop`	设置滚动到顶部距离	`(scrollTop: number) => void`
`setScrollLeft`	设置滚动到左侧距离	`(scrollLeft: number) => void`
`update`	手动更新滚动条状态	`() => void`
`wrapRef`	滚动条 wrap 容器引用	`Ref<HTMLDivElement>`

无障碍与键盘支持

从 2.4.0 起组件补齐了无障碍相关属性：role、aria-label、aria-orientation会透传到 view 容器上；从 2.8.3 起tabindex可作用到 wrap 容器，使滚动区域本身可被键盘聚焦。这意味着你可以将滚动区域标识为role="region"并给出aria-label描述，让屏幕阅读器用户也能理解该区域的语义；配合tabindex后，用户可通过方向键在可滚动区域内聚焦并滚动，符合现代可访问性实践。

使用建议小结

固定高度区域：使用height（如height="400px"），滚动条出现与否由内容是否溢出自动决定；
自适应收起：使用max-height，内容少时无滚动条、内容多时自动出现；
横向内容：内容宽度超过容器时自动出现水平滚动条，配合flex与width: fit-content实现；
编程控制：通过模板 ref 调用setScrollTop/setScrollLeft/scrollTo，并在需要时调用update()强制刷新；
无限滚动：监听end-reached并按需使用distance提前预加载，注意事件的方向去重逻辑，无需担心重复触发；
性能：容器尺寸固定不变时设置noresize，避免冗余的 ResizeObserver 与 resize 监听开销。