用于替换浏览器原生滚动条。
基础用法
通过 height 属性设置滚动条高度,若不设置则根据父容器高度自适应。
export function ScrollbarBasic() { return ( <ElScrollbar height="400px"> {Array.from({ length: 20 }, (_, i) => ( <p key={i + 1} style={itemStyle}> {i + 1} </p> ))} </ElScrollbar> );}
横向滚动
export function ScrollbarHorizontal() { return ( <ElScrollbar> <div style={{ display: "flex", width: "fit-content" }}> {Array.from({ length: 50 }, (_, i) => ( <p key={i + 1} style={{ ...itemStyle, flexShrink: 0, width: 100 }}> {i + 1} </p> ))} </div> </ElScrollbar> );}
最大高度
export function ScrollbarMaxHeight() { const [count, setCount] = useState(3); return ( <> <ElButton onClick={() => setCount((n) => n + 1)}>Add Item</ElButton> <ElButton onClick={() => setCount((n) => (n > 0 ? n - 1 : 0))}>Delete Item</ElButton> <ElScrollbar maxHeight="400px"> {Array.from({ length: count }, (_, i) => ( <p key={i + 1} style={itemStyle}> {i + 1} </p> ))} </ElScrollbar> </> );}
手动滚动
通过使用 setScrollTop 与 setScrollLeft 方法,可以手动控制滚动条滚动。
export function ScrollbarManual() { const scrollbarRef = useRef<ScrollbarExpose>(null); const [value, setValue] = useState(0); const [max, setMax] = useState(0); useEffect(() => { const wrap = scrollbarRef.current?.wrapRef.current; if (!wrap) return; setMax(Math.max(0, wrap.scrollHeight - wrap.clientHeight)); }, []); return ( <> <ElScrollbar ref={scrollbarRef} height="400px" always onScroll={({ scrollTop }) => setValue(scrollTop)} > {Array.from({ length: 20 }, (_, i) => ( <p key={i + 1} style={itemStyle}> {i + 1} </p> ))} </ElScrollbar> {max > 0 && ( <ElSlider className={styles.slider} value={value} max={max} formatTooltip={(v) => `${v} px`} onChange={(next) => { const v = Number(next) || 0; setValue(v); scrollbarRef.current?.setScrollTop(v); }} /> )} </> );}
无限滚动2.10.0
end-reached 是在滚动条到达底部时触发的。它可以用作无限滚动。
export function ScrollbarInfinite() { const [num, setNum] = useState(30); const loadMore = (direction: ScrollbarDirection) => { if (direction === "bottom") setNum((n) => n + 5); }; return ( <ElScrollbar height="400px" distance={5} onEndReached={loadMore}> {Array.from({ length: num }, (_, i) => ( <p key={i + 1} style={itemStyle}> {i + 1} </p> ))} </ElScrollbar> );}
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| height | 滚动条高度 | string / number | — |
| max-height | 滚动条最大高度 | string / number | — |
| native | 是否使用原生滚动条样式 | boolean | false |
| wrap-style | wrap 容器的样式 | object | — |
| wrap-class | wrap 容器的类名 | string | — |
| view-style | view 的样式 | object | — |
| view-class | view 的类名 | string | — |
| noresize | 容器尺寸不变时置为 true 可省去尺寸监听 | boolean | false |
| tag | view 的标签名 | string | div |
| always | 是否总是显示滚动条 | boolean | false |
| min-size | 滚动条最小尺寸 | number | 20 |
| id | view 的 id | string | — |
| role | view 的 role | string | — |
| aria-label | view 的 aria-label | string | — |
| aria-orientation | view 的 aria-orientation | enum | — |
| tabindex | wrap 的 tabindex | number / string | — |
| distance | 触发 end-reached 的距离阈值(px) | number | 0 |
| 事件名 | 说明 | 参数 |
|---|
| onScroll | 滚动时触发,返回滚动距离 | Function |
| onEndReached | 滚动到边界时触发 | Function |
| 插槽名 | 说明 | React 写法 |
|---|
| default | 自定义默认内容 | children |
| 方法名 | 说明 | 类型 |
|---|
| wrapRef | scrollbar wrap 的 ref | object |
| update | 手动更新滚动条状态 | Function |
| scrollTo | 滚动到指定坐标 | Function |
| setScrollTop | 设置距顶部距离 | Function |
| setScrollLeft | 设置距左侧距离 | Function |
| handleScroll | 处理滚动事件 | Function |