ScrollArea

建立受控滚动区域。中文惯用名：滚动区域。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.scroll-area`
名称	ScrollArea
二级分类	布局（`layout`）
用途	建立受控滚动区域
描述	中文惯用名：滚动区域。

预览

静态结构：Base UI ScrollArea——根节点 data-slot="scroll-area"（relative overflow-hidden），内容在 viewport（data-slot="scroll-area-viewport"，size-full）内滚动，滚动条为自定义节点（data-slot="scroll-area-scrollbar" + data-slot="scroll-area-thumb"，垂直 w-2 / 水平 h-2，圆角 thumb 取 bg-border）；maxHeight / maxWidth 内联 style（数字按 px，也接受 CSS 长度字符串），未指定时高度由内容决定、不产生滚动；内容超出视口才出现滚动条。

DSL 结构

DslNode

{
  "type": "ScrollArea",
  "props": {
    "maxHeight": 120
  },
  "children": [
    {
      "type": "Flex",
      "props": {
        "direction": "vertical",
        "gap": 4
      },
      "children": [
        {
          "type": "Text",
          "props": {
            "text": "通知消息 1：你提交的报表已通过审批。"
          }
        },
        {
          "type": "Text",
          "props": {
            "text": "通知消息 2：项目「支付重构」已进入测试阶段。"
          }
        },
        {
          "type": "Text",
          "props": {
            "text": "通知消息 3：本周配额已使用 82%。"
          }
        },
        {
          "type": "Text",
          "props": {
            "text": "通知消息 4：新成员已加入协作空间。"
          }
        }
      ]
    }
  ]
}

何时用

何时使用

建立受控滚动区域：面板内部的列表、日志流、通知流、长侧栏。
需要限制高度而不撑破外框：maxHeight 触顶后内部滚动。
需要自定义滚动条外观（跨浏览器一致）的场景。

何时不用

长页面整体滚动：用窗口滚动（长页面回顶配 BackTop），不要给整页套 ScrollArea。
内容不需要滚动（短列表）：直接渲染，滚动容器会带来额外焦点与滚动条开销。
虚拟化长列表 / 大数据量：使用 DataTable 等带虚拟化的组件。

变体

变体	视觉形态	适用场景
定高滚动	maxHeight 限制高度，内部纵向滚动	通知流、日志面板、长下拉内容
限宽滚动	maxWidth 限制宽度，内部横向滚动	代码行、宽表格片段
双向约束	maxHeight + maxWidth 同时给出	缩略图墙、二维内容浏览区
不定高	不传尺寸，内容自然撑开	内容长度可控、仅需统一滚动条外观

API 属性

属性	类型	默认值	说明
`maxHeight`	`number	string`	—
`maxWidth`	`number	string`	—
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式（与 maxHeight / maxWidth 合并，同键后者优先）
`children`	`DslNode[]`	—	滚动内容（DSL 子树）

使用规范

明确滚动归属：一个视觉区域内只留一层滚动（ScrollArea 内部不再嵌滚动容器）。
高度上限按容器可用高度给（数字或 100% 系列长度），避免硬编码与视口不匹配。
滚动区域内的内容保持可键盘聚焦，滚动条仅作视觉提示。
需要「滚到底部自动加载」时配合加载态组件（Skeleton / Spinner）给出反馈。

正例

✓ 侧栏通知：ScrollArea maxHeight={240} 内纵向排列通知条目。
✓ 控制台输出：ScrollArea 限高，日志持续追加时区域高度稳定。

反例

✕ 给整个页面内容套 ScrollArea（应交给窗口滚动）。
✕ 在 ScrollArea 内再嵌一个 ScrollArea（嵌套滚动，滚轮行为不可预期）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。