ScrollArea

ScrollArea 用于在固定尺寸容器内展示超出范围的内容，并提供一致的自定义滚动条样式。组件基于 Radix Scroll Area 封装，默认组合 Root、Viewport、Scrollbar、Thumb 和 Corner。

import {
  ScrollArea,
  ScrollAreaRoot,
  ScrollAreaScrollbar,
  ScrollAreaThumb,
  ScrollAreaViewport
} from '@skyroc/web-ui';

何时使用

• 内容高度或宽度固定，但内部列表、图片或文本会溢出。
• 需要自定义滚动条视觉，而不是完全依赖浏览器默认滚动条。
• 需要在菜单、侧栏、列表、卡片或预览区域内限制内容尺寸。
• 页面主体滚动优先使用原生滚动；虚拟长列表优先使用 Virtualizer。

纵向滚动

设置固定高度后，默认 orientation="vertical" 会渲染纵向滚动条。

<ScrollArea className="h-72 w-48">
  <div>Scrollable content</div>
</ScrollArea>

横向滚动

设置 orientation="horizontal" 后，主组件会渲染横向滚动条。内容需要自身产生横向溢出，例如使用 w-max 或 whitespace-nowrap。

<ScrollArea
  className="w-96 whitespace-nowrap"
  orientation="horizontal"
>
  <div className="w-max">Wide content</div>
</ScrollArea>

尺寸

通过 size 调整滚动条厚度，从 xs 到 2xl 共 6 个尺寸。

自定义样式

通过 classNames 覆盖内部 slot。常用 slot 包括 root、viewport、scrollbar、thumb 和 corner。

<ScrollArea
  classNames={{
    scrollbar: 'bg-muted/60',
    thumb: 'bg-primary'
  }}
>
  <div>Content</div>
</ScrollArea>

API

ScrollArea

主组件组合 Root、Viewport、Scrollbar、Thumb 和 Corner。当前主组件一次渲染一个方向的 Scrollbar；如果需要同时显示横向和纵向滚动条，可使用结构组件手动组合。

结构组件

ScrollArea 也导出结构组件，适合需要同时渲染横向和纵向滚动条，或需要完全控制 DOM 结构时使用。

类型