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,每个方向各有一条滚动条。两个方向都溢出时,两条滚动条会在角落处互相让开,角落保持透明。
| Kate | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Kirby | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Mika | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Noor | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Oskar | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Priya | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Quinn | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Rae | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Sol | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
#触发方式
默认情况下,鼠标在区域内或正在滚动时显示滚动条。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 收到的也是它的滚动事件。
Section 1
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 2
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 3
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 4
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 5
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 6
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 7
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 8
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 9
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 10
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 11
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 12
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
#滚动到元素
actionsRef 提供 scrollToElement(element, options):只滚动这个区域(scrollIntoView 还会滚动页面),让区域里的某个元素出现在视野中。block 决定元素对齐到 start(默认)、center 还是 end,nearest 则只滚动到刚好可见。offset 在元素和对齐的边缘之间留出这么多 px,比如吸顶标题的高度(把同样的高度交给 railInset,滚动条也会从标题下面开始);behavior: "smooth" 让滚动带动画。ref 仍然指向容器。
Chapter 1
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 2
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 3
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 4
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 5
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 6
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 7
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 8
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
#文本框
<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 自己监听滚动元素的滚动,渲染换了一个元素时会重新绑定。
- Kate
- Kirby
- Mika
- Noor
- Oskar
- Priya
- Quinn
- Rae
- Sol
- Tove
guttersPosition: "absolute" 时,把 frameProps 展开到你包在滚动元素和滚动条外面的外框上,<ScrollAreaGutters {...guttersProps} /> 紧跟在滚动元素后面。外框是纵向的 flex 容器:给滚动元素 flex: 1 1 auto 和 min-height: 0,让它填满外框并滚动。
- Release 1.24.0
- Release 1.23.0
- Release 1.22.0
- Release 1.21.0
- Release 1.20.0
- Release 1.19.0
- Release 1.18.0
- Release 1.17.0
- Release 1.16.0
- Release 1.15.0
- Release 1.14.0
- Release 1.13.0
- Release 1.12.0
- Release 1.11.0
- Release 1.10.0
- Release 1.9.0
- Release 1.8.0
- Release 1.7.0
- Release 1.6.0
- Release 1.5.0
- Release 1.4.0
- Release 1.3.0
- Release 1.2.0
- Release 1.1.0
#用在 VirtualList 上
VirtualList 自己渲染滚动元素,所以这样接上滚动条:列表的 domRef 接 containerProps.ref,className 和 style 用容器的,sticky 滚动条通过 header 放进去,成为滚动元素的第一个子元素。列表照样自己滚动、测量和保持锚点。overscroll: "auto" 时列表保留自己的 overscroll-behavior。
#属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
guttersPosition | sticky | absolute | sticky | 滚动条的位置:容器里一层高度为 0 的层,容器就是根元素(sticky);或在容器旁边,盖在同时包住两者的外框上(absolute) | 未发布 |
orientation | vertical | horizontal | both | vertical | 区域滚动的方向,每个方向各有一条滚动条;纵向区域里过宽的内容会被裁掉 | 未发布 |
trigger | hover | scroll | none | hover | hover 在鼠标移入时显示滚动条,scroll 只在滚动时显示,none 一直显示。滚动或拖动时总会显示 | 未发布 |
hideDelay | number | 600 | 停止滚动后滚动条还停留多久,单位 ms;trigger="scroll" 时至少为 100 | 未发布 |
size | small | medium | medium | 滑块粗细:5px 或 7px,悬停时再加粗 3px | 未发布 |
fade | boolean | false | 让内容在还有更多内容的边缘渐隐,滚动条不渐隐 | 未发布 |
overscroll | none | contain | auto | none | none 让滚到尽头的滚动停在区域里,也不回弹;contain 也停住,但允许 Mac 触控板和 iOS 回弹;auto 让它接着传给页面。只作用在溢出的方向上 | 未发布 |
railInset | { top?: number; bottom?: number; left?: number; right?: number } | undefined | 滚动条在两端让出的 px,比如吸顶标题的高度。top、bottom 缩短纵向滚动条,left、right 缩短横向滚动条 | 未发布 |
actionsRef | Ref<ScrollAreaActions> | undefined | 提供 scrollToElement(element, { block?, offset?, behavior? }),只滚动这个区域,让 element 出现在视野中;以及 measure(),在观察不到的尺寸变化后重新测量 | 未发布 |
onEdgeChange | (edges: { top: boolean; bottom: boolean; left: boolean; right: boolean }) => void | undefined | 区域滚到或离开某一侧边缘时调用(true 表示已滚到尽头),挂载后内容溢出时也会调用 | 未发布 |
className | string | undefined | 根元素的类名:容器(sticky)或外框(absolute),在这里设置区域的尺寸和边框 | 未发布 |
style | CSSProperties | undefined | 根元素的样式 | 未发布 |
rootRef | Ref<HTMLDivElement> | undefined | 根元素:容器本身(sticky)或外框(absolute) | 未发布 |
containerClassName | string | undefined | 区域自带容器的类名;sticky 时和根元素是同一个元素 | 未发布 |
containerStyle | CSSProperties | undefined | 区域自带容器的样式 | 未发布 |
contentClassName | string | undefined | 包裹 children 的元素的类名 | 未发布 |
contentStyle | CSSProperties | undefined | 包裹 children 的元素的样式 | 未发布 |
onScroll | (event: UIEvent<HTMLDivElement>) => void | undefined | 容器每次滚动时调用 | 未发布 |
children | ReactNode | undefined | 要滚动的内容 | 未发布 |
#scrollToElement 选项
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
block | start | center | end | nearest | start | 元素对齐的位置。horizontal 区域里作用在横向,start 是行内方向的起点;both 时横向只滚动到刚好可见 | 未发布 |
offset | number | 0 | 元素和对齐的边缘之间留出的 px,比如吸顶标题的高度;center 忽略它 | 未发布 |
behavior | ScrollBehavior | undefined | smooth 让滚动带动画,同 scrollTo | 未发布 |
ScrollArea 也接受原生 div 属性和 ref,它们传给容器,也就是滚动的那个元素;按偏移量滚动时直接用它的 scrollTo 和 scrollBy,滚动到某个元素用 actionsRef。orientation、trigger、hideDelay、size、fade 和 overscroll 可以通过 ConfigProvider 的 componentOptions.ScrollArea 给所有滚动区域(以及所有 useScrollAreaContainer)统一设置,组件上的 prop 优先。类名由 clsPrefix 拼出。有内容可滚动时,区域可以获得焦点(tabIndex={0}),键盘用户可以用方向键滚动;请用 aria-label 说明里面是什么内容。自定义滚动条对辅助技术隐藏,辅助技术使用的是原生滚动。
#ScrollAreaTextarea 属性
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
trigger | hover | scroll | none | hover | 同 ScrollArea | 未发布 |
hideDelay | number | 600 | 同 ScrollArea | 未发布 |
size | small | medium | medium | 同 ScrollArea | 未发布 |
overscroll | none | contain | auto | none | 同 ScrollArea | 未发布 |
wrapperClassName | string | undefined | 包住 textarea 和滚动条的外框的类名,边框和背景写在这里 | 未发布 |
wrapperStyle | CSSProperties | undefined | 外框的样式 | 未发布 |
其余属性,包括 ref、className、style、value 和 onScroll,都传给原生 textarea。
#useScrollAreaContainer 选项
ScrollArea 的 orientation、trigger、hideDelay、size、fade、overscroll、railInset、actionsRef 和 onEdgeChange,和 ScrollArea 一样默认取 ConfigProvider 的 componentOptions.ScrollArea,另外还有:
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
guttersPosition | sticky | absolute | sticky | 你把滚动条渲染在哪里:容器的第一个子元素,或外框里紧跟容器之后。它决定你渲染什么,所以不从 ConfigProvider 取默认值 | 未发布 |
containerRef | Ref<E> | undefined | 你自己指向滚动元素的 ref;containerProps.ref 在提交时转给它 | 未发布 |
frameRef | Ref<HTMLDivElement> | undefined | absolute 时你自己指向外框的 ref;frameProps.ref 转给它 | 未发布 |
contentRef | RefObject<HTMLElement | null> | undefined | 尺寸等于内容尺寸的元素,观察它的尺寸变化。不传时观察容器的每个子元素,以及之后增删的子元素 | 未发布 |
fadeRef | RefObject<HTMLElement | null> | undefined | fade 且 sticky 时,放遮罩的内容元素(类名 p-scroll-area__content) | 未发布 |
#useScrollAreaContainer 返回值
| 名称 | 类型 | 说明 | 版本 |
|---|---|---|---|
containerProps | { ref, className, style, tabIndex } | 展开到滚动元素上。sticky 时 className 和 style 是根元素的类和变量;有内容可滚动时 tabIndex 为 0 | 未发布 |
frameProps | { ref, className, style } | undefined | absolute 时展开到外框上;sticky 时为 undefined(传了 guttersPosition: "absolute" 时类型上一定存在) | 未发布 |
guttersProps | ScrollAreaGuttersProps | 展开到 <ScrollAreaGutters /> 上 | 未发布 |
guttersPosition | sticky | absolute | 滚动条应该放在哪里 | 未发布 |
measure | () => void | 立即重新测量,同 actionsRef.measure() | 未发布 |
scrollToElement | (element, options?) => void | 同 actionsRef | 未发布 |
scrollable | boolean | 当前是否有任一方向可以滚动 | 未发布 |
返回的所有东西在它依赖的值变化之前都保持不变,可以放进 memo 子组件的 props。ScrollAreaGutters 只接受 guttersProps,对辅助技术隐藏。