跳到正文

ScrollArea 滚动区域

页面里有一块需要自己滚动的区域(侧边栏、面板、代码视图、聊天记录),又希望滚动条细而且在所有平台上看起来一样时,用 ScrollArea。成千上万行的列表请用 VirtualList,它也能显示同样的滚动条;Layout 的各个区域已经放在 ScrollArea 里滚动。

使用前须知

给滚动区域一个高度或 max-height。否则它会随内容一起变高,永远不会滚动。

ScrollArea 是一个带细滚动条的滚动容器,滚动条浮在内容上方,样子参照 macOS:圆角的滑块在滚动或鼠标移入时淡入,鼠标指向它时变粗(没有可见的轨道),停止滚动后稍等片刻淡出。它在所有主题、所有平台上看起来都一样。滚动本身仍是原生的,滚轮、触控板、触摸和键盘都照常工作;另外可以拖动滑块,点击滑块上下的空白处会翻一页。

它的结构参照 react-scroll-area-demo:区域测量一个容器(也就是滚动的那个元素),再按 guttersPosition 把滚动条层(ScrollAreaGutters)放到指定位置。默认的 sticky 把滚动条层作为容器的第一个子元素,高度为 0,容器就是整个区域,只有一个元素。absolute 则由一个外框同时包住容器和旁边的滚动条层。ScrollArea 是最常用的写法,自带一个 div 作为容器;滚动元素由你自己渲染时(列表、VirtualList 的滚动元素),调用 useScrollAreaContainer,把它返回的属性展开到你的元素上。

演示

基础用法

给滚动区域一个高度(或 max-height)。内边距请通过 contentClassName 或 contentStyle 加在内容上,不要加在滚动区域本身,这样滚动条才会贴着边缘。

滚动方向

orientation 决定区域往哪些方向滚动:vertical(默认,过宽的内容会被裁掉)、horizontal 或 both,每个方向各有一条滚动条。两个方向都溢出时,两条滚动条会在角落处互相让开,角落保持透明。

触发方式

默认情况下,鼠标在区域内或正在滚动时显示滚动条。trigger="none" 让滚动条一直显示。

只在滚动时显示

trigger="scroll" 只在区域滚动(或拖动滑块)时显示滚动条,鼠标移入不显示;隐藏时滚动条不会挡住对内容的点击。鼠标已经停在滚动条上时,滚动条会一直显示、可以操作,直到鼠标离开。无论哪种触发方式,hideDelay 都决定停止滚动后滚动条还停留多久,默认 600ms;trigger="scroll" 时至少 100ms。

尺寸

size 决定滑块粗细:small 为 5px,medium 为 7px。鼠标指向滚动条或拖动滑块时,两者都会再加粗 3px。

渐隐

fade 让内容在还有更多内容的那一侧边缘渐隐,渐隐长度最多 24px,内容离开边缘时渐隐会逐渐出现。只有内容渐隐,滚动条不会;orientation="both" 时两个方向的渐隐会叠加。渐隐是一层遮罩,滚动时会重绘内容,所以适合较短的区域,不适合长列表。

边缘状态

某一侧边缘之外还有内容时,滚动区域会带上对应的修饰类:p-scroll-area--overflow-y-start(上方)、--overflow-y-end(下方)、--overflow-x-start 和 --overflow-x-end(行内方向的起点和终点,从右到左的布局里分别是右边和左边)。可以用它们来写阴影、分隔线或“还有更多”的提示。滚动不会触发渲染:这些类以及 --scrolling、--dragging 直接写在根元素上(渲染替换了 className 之后会再写一次),滚动时根元素上不写任何样式(开了 fade 时只移动遮罩)。只有滚动条出现或消失时区域才重新渲染。

滑块的表现和原生滚动条一样:每一帧,滑块的长度和位置都跟着当前的滚动位置和内容尺寸走,没有过渡动画。浏览器支持滚动驱动动画时,由浏览器在合成线程上按容器自己命名的滚动时间线移动滑块(嵌套在别的区域容器里的区域用自己的时间线),脚本只在尺寸变化时设置滑块长度。不支持时,一次滚动只申请一个动画帧(不管来了多少个滚动事件),在这一帧里用 transform 移动滑块。区域用 ResizeObserver 观察容器、内容和每条滚动条;观察不到的尺寸变化可以调用 actionsRef.measure() 重新测量。

任一边缘状态翻转时会调用 onEdgeChange,参数是 { top, bottom, left, right }(true 表示已经滚到这一侧的尽头);挂载后如果内容溢出,也会调用一次。

区域里用 position: sticky 钉住的标题或底栏会盖住滚动区的两端,这时把它的高度交给 railInset:railInset={{ top: 40, bottom: 40 }} 让纵向滚动条从标题下面开始、到底栏上面结束。left 和 right 对横向滚动条做同样的事,比如让开固定的第一列。也可以不写 prop,改用 CSS 变量,设在滚动区本身上:--p-scroll-area-rail-inset-top、-bottom、-left、-right(它们不继承,嵌套在里面的滚动区不会拿到)。

滚动穿透

默认(overscroll="none")滚到区域尽头时就停住:滚动不会传给后面的页面,Mac 触控板和 iOS 上区域(连同里面固定的标题、底栏)也不会回弹。overscroll="contain" 同样停在区域里,但允许这些设备让区域在边缘回弹。overscroll="auto" 让滚动接着传给页面,和普通的可滚动 div 一样。none 和 contain 只作用在内容当前确实溢出的方向上,所以只在横向溢出的区域不会挡住页面的纵向滚动。

用代码滚动

ref 指向容器,也就是滚动的那个元素(默认的 sticky 时它同时是根元素),所以可以直接调用原生的 scrollTo 和 scrollBy,onScroll 收到的也是它的滚动事件。

滚动到元素

actionsRef 提供 scrollToElement(element, options):只滚动这个区域(scrollIntoView 还会滚动页面),让区域里的某个元素出现在视野中。block 决定元素对齐到 start(默认)、center 还是 end,nearest 则只滚动到刚好可见。offset 在元素和对齐的边缘之间留出这么多 px,比如吸顶标题的高度(把同样的高度交给 railInset,滚动条也会从标题下面开始);behavior: "smooth" 让滚动带动画。ref 仍然指向容器。

文本框

<textarea> 自己就是滚动元素,而且不能包含子元素,所以 ScrollAreaTextarea 是以原生 textarea 为容器、absolute 滚动条的 useScrollAreaContainer:外框包住 textarea,把同样的滚动条叠在上面。边框、背景、聚焦环放在外层(wrapperClassName),内边距放在 textarea 上(className)。输入、粘贴、受控的 value 变化时,滚动条都会跟着更新。拖动右下角可以把文本框拉高,滚动条会停在拖动把手上方,不会挡住它。

滚动条位置

guttersPosition="sticky"(默认)多出来的东西最少:区域只有一个元素,滚动条是里面一层高度为 0、不占空间的层,所以 ref、className、style 和原生属性都在滚动元素上。guttersPosition="absolute" 不往容器里放任何东西:外框(根元素)包住容器,滚动条层盖在外框上。这时 className 和 style 用来设置外框的尺寸和边框(尺寸包含边框),ref、onScroll、tabIndex 和其他原生属性传给容器(containerClassName、containerStyle);rootRef 在两种位置下都指向根元素。absolute 时 fade 的遮罩在容器上,聚焦环画在外框周围。

自己的容器

useScrollAreaContainer(options) 就是去掉了自带 div 的 ScrollArea:在渲染滚动元素的组件里调用它,把返回的属性展开上去。它接受 ScrollArea 的选项(guttersPosition、orientation、trigger、size、fade、overscroll、railInset、hideDelay、onEdgeChange、actionsRef)、contentRef,以及你自己指向滚动元素(containerRef)和外框(frameRef)的 ref。把 containerProps 放到滚动元素上(它的 className 放在你的前面,style 放在你的前面、由你的覆盖),滚动元素的 overflow 由你自己设置;sticky 时把 <ScrollAreaGutters {...guttersProps} /> 作为它的第一个子元素。这个 hook 自己监听滚动元素的滚动,渲染换了一个元素时会重新绑定。

guttersPosition: "absolute" 时,把 frameProps 展开到你包在滚动元素和滚动条外面的外框上,<ScrollAreaGutters {...guttersProps} /> 紧跟在滚动元素后面。外框是纵向的 flex 容器:给滚动元素 flex: 1 1 auto 和 min-height: 0,让它填满外框并滚动。

用在 VirtualList 上

VirtualList 自己渲染滚动元素,所以这样接上滚动条:列表的 domRef 接 containerProps.ref,className 和 style 用容器的,sticky 滚动条通过 header 放进去,成为滚动元素的第一个子元素。列表照样自己滚动、测量和保持锚点。overscroll: "auto" 时列表保留自己的 overscroll-behavior。

属性

名称类型默认值说明版本
guttersPositionsticky | absolutesticky滚动条的位置:容器里一层高度为 0 的层,容器就是根元素(sticky);或在容器旁边,盖在同时包住两者的外框上(absolute)未发布
orientationvertical | horizontal | bothvertical区域滚动的方向,每个方向各有一条滚动条;纵向区域里过宽的内容会被裁掉未发布
triggerhover | scroll | nonehoverhover 在鼠标移入时显示滚动条,scroll 只在滚动时显示,none 一直显示。滚动或拖动时总会显示未发布
hideDelaynumber600停止滚动后滚动条还停留多久,单位 ms;trigger="scroll" 时至少为 100未发布
sizesmall | mediummedium滑块粗细:5px 或 7px,悬停时再加粗 3px未发布
fadebooleanfalse让内容在还有更多内容的边缘渐隐,滚动条不渐隐未发布
overscrollnone | contain | autononenone 让滚到尽头的滚动停在区域里,也不回弹;contain 也停住,但允许 Mac 触控板和 iOS 回弹;auto 让它接着传给页面。只作用在溢出的方向上未发布
railInset{ top?: number; bottom?: number; left?: number; right?: number }undefined滚动条在两端让出的 px,比如吸顶标题的高度。top、bottom 缩短纵向滚动条,left、right 缩短横向滚动条未发布
actionsRefRef<ScrollAreaActions>undefined提供 scrollToElement(element, { block?, offset?, behavior? }),只滚动这个区域,让 element 出现在视野中;以及 measure(),在观察不到的尺寸变化后重新测量未发布
onEdgeChange(edges: { top: boolean; bottom: boolean; left: boolean; right: boolean }) => voidundefined区域滚到或离开某一侧边缘时调用(true 表示已滚到尽头),挂载后内容溢出时也会调用未发布
classNamestringundefined根元素的类名:容器(sticky)或外框(absolute),在这里设置区域的尺寸和边框未发布
styleCSSPropertiesundefined根元素的样式未发布
rootRefRef<HTMLDivElement>undefined根元素:容器本身(sticky)或外框(absolute)未发布
containerClassNamestringundefined区域自带容器的类名;sticky 时和根元素是同一个元素未发布
containerStyleCSSPropertiesundefined区域自带容器的样式未发布
contentClassNamestringundefined包裹 children 的元素的类名未发布
contentStyleCSSPropertiesundefined包裹 children 的元素的样式未发布
onScroll(event: UIEvent<HTMLDivElement>) => voidundefined容器每次滚动时调用未发布
childrenReactNodeundefined要滚动的内容未发布

scrollToElement 选项

名称类型默认值说明版本
blockstart | center | end | neareststart元素对齐的位置。horizontal 区域里作用在横向,start 是行内方向的起点;both 时横向只滚动到刚好可见未发布
offsetnumber0元素和对齐的边缘之间留出的 px,比如吸顶标题的高度;center 忽略它未发布
behaviorScrollBehaviorundefinedsmooth 让滚动带动画,同 scrollTo未发布

ScrollArea 也接受原生 div 属性和 ref,它们传给容器,也就是滚动的那个元素;按偏移量滚动时直接用它的 scrollTo 和 scrollBy,滚动到某个元素用 actionsRef。orientation、trigger、hideDelay、size、fade 和 overscroll 可以通过 ConfigProvider 的 componentOptions.ScrollArea 给所有滚动区域(以及所有 useScrollAreaContainer)统一设置,组件上的 prop 优先。类名由 clsPrefix 拼出。有内容可滚动时,区域可以获得焦点(tabIndex={0}),键盘用户可以用方向键滚动;请用 aria-label 说明里面是什么内容。自定义滚动条对辅助技术隐藏,辅助技术使用的是原生滚动。

ScrollAreaTextarea 属性

名称类型默认值说明版本
triggerhover | scroll | nonehover同 ScrollArea未发布
hideDelaynumber600同 ScrollArea未发布
sizesmall | mediummedium同 ScrollArea未发布
overscrollnone | contain | autonone同 ScrollArea未发布
wrapperClassNamestringundefined包住 textarea 和滚动条的外框的类名,边框和背景写在这里未发布
wrapperStyleCSSPropertiesundefined外框的样式未发布

其余属性,包括 ref、className、style、value 和 onScroll,都传给原生 textarea。

useScrollAreaContainer 选项

ScrollArea 的 orientation、trigger、hideDelay、size、fade、overscroll、railInset、actionsRef 和 onEdgeChange,和 ScrollArea 一样默认取 ConfigProvider 的 componentOptions.ScrollArea,另外还有:

名称类型默认值说明版本
guttersPositionsticky | absolutesticky你把滚动条渲染在哪里:容器的第一个子元素,或外框里紧跟容器之后。它决定你渲染什么,所以不从 ConfigProvider 取默认值未发布
containerRefRef<E>undefined你自己指向滚动元素的 ref;containerProps.ref 在提交时转给它未发布
frameRefRef<HTMLDivElement>undefinedabsolute 时你自己指向外框的 ref;frameProps.ref 转给它未发布
contentRefRefObject<HTMLElement | null>undefined尺寸等于内容尺寸的元素,观察它的尺寸变化。不传时观察容器的每个子元素,以及之后增删的子元素未发布
fadeRefRefObject<HTMLElement | null>undefinedfade 且 sticky 时,放遮罩的内容元素(类名 p-scroll-area__content)未发布

useScrollAreaContainer 返回值

名称类型说明版本
containerProps{ ref, className, style, tabIndex }展开到滚动元素上。sticky 时 className 和 style 是根元素的类和变量;有内容可滚动时 tabIndex 为 0未发布
frameProps{ ref, className, style } | undefinedabsolute 时展开到外框上;sticky 时为 undefined(传了 guttersPosition: "absolute" 时类型上一定存在)未发布
guttersPropsScrollAreaGuttersProps展开到 <ScrollAreaGutters /> 上未发布
guttersPositionsticky | absolute滚动条应该放在哪里未发布
measure() => void立即重新测量,同 actionsRef.measure()未发布
scrollToElement(element, options?) => void同 actionsRef未发布
scrollableboolean当前是否有任一方向可以滚动未发布

返回的所有东西在它依赖的值变化之前都保持不变,可以放进 memo 子组件的 props。ScrollAreaGutters 只接受 guttersProps,对辅助技术隐藏。