09:12
Design review scheduled
Maya added the component audit to Thursday's agenda.
一个 React 滚动区域，使用原生滚动，带 Liquid Glass 滚动条与玻璃面板。
ScrollArea 在内部渲染玻璃面板、原生滚动视口、内容容器与自定义滚动条。
原生滚动条会被隐藏。主题滚动条在静止时保持低调，当指针位于区域上方或视口滚动时会变得更明显；只有内容真正溢出时才会渲染。
ScrollArea 没有内置高度。通过 className 给根节点设置高度即可创建可滚动视口。下面的示例还传入了 aria-label，它会转发到可滚动视口，而不是仅用于展示的根节点。
设置 orientation="horizontal" 只渲染横向滚动条。宽度超出视口的内容仍可通过触控板、滚轮或键盘滚动。
使用 orientation="both" 处理二维内容。此时会渲染转角，避免两条滚动条互相重叠。
根节点负责玻璃表面。使用 className 控制其宽高、圆角与外部布局。内边距应放在内容内部（如示例所示），这样列表行在需要时也可以贴边排列。
overflowEdgeThreshold 控制视口距离边缘多近时 data-overflow-* 属性才会变化。下面的示例在滚动 16px 后给出反馈。
The ring appears once the viewport scrolls 16px past the top edge.
viewport 只在可滚动时可聚焦，与原生滚动容器行为一致。通过 aria-label 或 aria-labelledby 为区域命名，并用 aria-describedby 提供额外说明。
指针与键盘滚动保持原生行为，自定义滚动条仅是装饰，对辅助技术隐藏。区域命名见可访问性指南。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
children | ReactNode | — | 渲染在视口内的可滚动内容。 |
orientation | "vertical" | "horizontal" | "both" | "vertical" | 要渲染的滚动条方向。 |
overflowEdgeThreshold | number | Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number }> | 0 | 将一个边缘标记为溢出前需要越过的像素距离。 |
aria-label | string | — | 转发到可滚动视口的无障碍名称。 |
aria-labelledby | string | — | 为视口提供名称的元素 ID。 |
aria-describedby | string | — | 为视口提供说明的元素 ID。 |
render | ReactElement | ((props, state) => ReactElement) | — | 替换根元素。 |
ref | Ref<HTMLDivElement> | — | 转发到根元素的 ref。 |
className | string | — | 合并到根节点的 Tailwind 类；在这里设置高度。 |
style | CSSProperties | — | 内联样式，合并到与 className 相同的元素。 |
ui | { root?: ClassValue; glass?: ClassValue; overlay?: ClassValue; viewport?: ClassValue; content?: ClassValue; scrollbar?: ClassValue; thumb?: ClassValue; corner?: ClassValue } | — | 按 data-slot 组织的内部槽位类名。 |
| 属性 | 说明 |
|---|---|
data-orientation | 表示启用的滚动条方向（horizontal、vertical 或 both）。 |
data-scrolling | 用户正在区域内滚动时存在。 |
data-has-overflow-x | 内容宽度超出视口时存在。 |
data-has-overflow-y | 内容高度超出视口时存在。 |
data-overflow-x-start | 横向起点方向存在溢出时存在。 |
data-overflow-x-end | 横向终点方向存在溢出时存在。 |
data-overflow-y-start | 纵向起点方向存在溢出时存在。 |
data-overflow-y-end | 纵向终点方向存在溢出时存在。 |
data-hovering | 指针位于区域上方时存在于滚动条上。 |
data-slot | 标记内部部件（root、glass、overlay、viewport、content、scrollbar、thumb、corner），用于样式选择。 |
组件使用共享玻璃材质。可以在父级调整 --ui-glass-* token，用 className 控制布局，并通过 ui 按 data-slot 调整内部槽位。组件级数值位于 src/theme/scroll-area.ts。Token 分层与预设见主题指南。