> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/scroll-area.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# ScrollArea 滚动区域

在限定区域内浏览内容。

## 基本用法


项目 1

项目 2

项目 3

项目 4

项目 5

项目 6

项目 7

项目 8

项目 9

项目 10

项目 11

项目 12

项目 13

项目 14

项目 15

项目 16

项目 17

项目 18

项目 19

项目 20

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/scroll-area/basic.tsx"
import { ScrollArea } from '@ifhover/leaf-ui';

export function ScrollAreaBasic() {
  return (
    <ScrollArea height={180} aria-label="项目列表">
      {Array.from({ length: 20 }, (_, i) => (
        <div key={String(i)} style={{ padding: '12px 16px' }}>
          项目 {i + 1}
        </div>
      ))}
    </ScrollArea>
  );
}
```

展开代码

## 更多用法


### A

横向浏览内容

### B

横向浏览内容

### C

横向浏览内容

### D

横向浏览内容

### E

横向浏览内容

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/scroll-area/advanced.tsx"
import { Card, ScrollArea, Space } from '@ifhover/leaf-ui';

export function ScrollAreaHorizontal() {
  return (
    <ScrollArea orientation="horizontal" aria-label="横向卡片">
      <Space size={12}>
        {['A', 'B', 'C', 'D', 'E'].map((name) => (
          <Card key={name} title={name} style={{ width: 180, flex: 'none' }}>
            横向浏览内容
          </Card>
        ))}
      </Space>
    </ScrollArea>
  );
}
```

展开代码

## 使用说明

通过 height 或 maxHeight 限制滚动区域。orientation 控制方向，scrollbar 控制滚动条显示；支持原生滚轮、触摸和键盘滚动。

滚动条默认悬浮并在鼠标移入时淡入，不占用内容空间。`ref` 指向实际滚动容器，`style` 与 `className` 用于外层。完整的样式扩展与键盘操作见 [Scrollbar](https://ifhover.github.io/leaf-ui/components/scrollbar.md)。未溢出或到达边界时，滚轮继续滚动页面。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { ScrollAreaProps } from '@ifhover/leaf-ui';
```

## ScrollAreaProps API

| 属性                  | 类型                                     | 默认值          | 说明          |
| ------------------- | -------------------------------------- | ------------ | ----------- |
| `height`            | `CSSProperties['height']`              | —            | 高度，数字按像素计算  |
| `maxHeight`         | `CSSProperties['maxHeight']`           | —            | 最大高度        |
| `orientation`       | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | 滚动方向        |
| `scrollbar`         | `'auto' \| 'always' \| 'hidden'`       | `'auto'`     | 滚动条显示方式     |
| `viewportClassName` | `string`                               | —            | 实际滚动容器的类名。  |
| `viewportStyle`     | `CSSProperties`                        | —            | 实际滚动容器的样式。  |
| `contentClassName`  | `string`                               | —            | 内容容器的类名。    |
| `contentStyle`      | `CSSProperties`                        | —            | 内容容器的样式。    |
| `verticalOffset`    | `number`                               | `0`          | 纵向轨道顶部预留空间。 |