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

# ScrollArea

数据展示`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

为受限区域提供跨浏览器一致的滚动条与阴影提示。

## 何时使用

局部内容必须限制尺寸并独立滚动时使用 ScrollArea。

**推荐**

- 明确滚动方向和尺寸上限。
- 触摸与键盘用户都应能访问内容。

**避免**

- 不要制造不必要的嵌套滚动区域。

## 代码演示


### 基础用法
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

function ScrollAreaExample() {
  return (
    <ScrollArea
      maxHeight={180}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 8,
      }}
    >
      <div style={{ padding: 16 }}>
        {Array.from({ length: 12 }, (_, index) => (
          <p key={index}>Activity item {index + 1}</p>
        ))}
      </div>
    </ScrollArea>
  );
}

export default ScrollAreaExample;
```

### 水平与双轴滚动
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';

function ScrollDirections() {
  return (
    <Stack gap="lg">
      <ScrollArea direction="horizontal" maxWidth={400}>
        <div style={{ width: 760, padding: 16, whiteSpace: 'nowrap' }}>
          A long horizontal timeline that remains inside its own scroll area.
        </div>
      </ScrollArea>
      <ScrollArea direction="both" maxWidth={360} maxHeight={140}>
        <div style={{ width: 680, height: 260, padding: 16 }}>
          Content that can scroll on both axes.
        </div>
      </ScrollArea>
    </Stack>
  );
}

export default ScrollDirections;
```

### 常驻滚动条与自定义尺寸
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';

function ScrollbarStyles() {
  const content = Array.from({ length: 10 }, (_, index) => (
    <p key={index}>Scrollable row {index + 1}</p>
  ));

  return (
    <Stack direction="horizontal" gap="lg">
      <ScrollArea type="always" scrollbarSize={4} maxHeight={160}>
        <div style={{ padding: 12 }}>{content}</div>
      </ScrollArea>
      <ScrollArea type="always" scrollbarSize={10} maxHeight={160}>
        <div style={{ padding: 12 }}>{content}</div>
      </ScrollArea>
    </Stack>
  );
}

export default ScrollbarStyles;
```

### 横向滚动
为横向内容设置有限宽度，并用 `orientation` 显示对应滚动条。
```tsx preview
import { ScrollArea, Tag } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaHorizontal() {
  return (
    <ScrollArea
      direction="horizontal"
      maxWidth={400}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div
        style={{ display: 'flex', gap: 8, padding: 16, width: 'max-content' }}
      >
        {items.slice(0, 20).map((item) => (
          <Tag key={item} color="primary">
            {item}
          </Tag>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### 双向滚动
内容同时超出宽高时分别滚动，外层页面不承担内容的横向溢出。
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaBoth() {
  return (
    <ScrollArea
      direction="both"
      maxHeight={200}
      maxWidth={300}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div style={{ width: 600, padding: 16 }}>
        {items.map((item) => (
          <p
            key={item}
            style={{
              margin: '0 0 8px',
              color: 'var(--tao-color-text-secondary)',
              whiteSpace: 'nowrap',
            }}
          >
            {item} — This is a long line that overflows the container
            horizontally to demonstrate both scrollbars.
          </p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### 始终显示滚动条
`type="always"` 保留滚动条轨道，适用于滚动能力需要更明显的区域。
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaAlwaysVisible() {
  return (
    <ScrollArea
      type="always"
      maxHeight={200}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div style={{ padding: 16 }}>
        {items.map((item) => (
          <p
            key={item}
            style={{
              margin: '0 0 8px',
              color: 'var(--tao-color-text-secondary)',
            }}
          >
            {item}
          </p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### 滚动边缘提示
边缘阴影提示还有未显示的内容，滚动到底部后对应提示消失。
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaWithShadow() {
  return (
    <ScrollArea
      scrollShadow
      maxHeight={200}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div style={{ padding: 16 }}>
        {items.map((item) => (
          <p
            key={item}
            style={{
              margin: '0 0 8px',
              color: 'var(--tao-color-text-secondary)',
            }}
          >
            {item}
          </p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### 滚动条尺寸
调整滚动条尺寸，示例保留有界内容区域。
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaCustomSize() {
  return (
    <Stack gap="lg">
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          Thin (4px)
        </p>
        <ScrollArea
          type="always"
          scrollbarSize={4}
          maxHeight={150}
          style={{
            border: '1px solid var(--tao-color-border-secondary)',
            borderRadius: 6,
          }}
        >
          <div style={{ padding: 16 }}>
            {items.slice(0, 30).map((item) => (
              <p
                key={item}
                style={{
                  margin: '0 0 8px',
                  color: 'var(--tao-color-text-secondary)',
                }}
              >
                {item}
              </p>
            ))}
          </div>
        </ScrollArea>
      </div>
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          Thick (10px)
        </p>
        <ScrollArea
          type="always"
          scrollbarSize={10}
          maxHeight={150}
          style={{
            border: '1px solid var(--tao-color-border-secondary)',
            borderRadius: 6,
          }}
        >
          <div style={{ padding: 16 }}>
            {items.slice(0, 30).map((item) => (
              <p
                key={item}
                style={{
                  margin: '0 0 8px',
                  color: 'var(--tao-color-text-secondary)',
                }}
              >
                {item}
              </p>
            ))}
          </div>
        </ScrollArea>
      </div>
    </Stack>
  );
}
```

### 横向边缘提示
横向滚动时使用两侧阴影提示内容延伸方向。
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaHorizontalShadow() {
  return (
    <ScrollArea
      direction="horizontal"
      scrollShadow
      maxWidth={400}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div
        style={{ display: 'flex', gap: 8, padding: 16, width: 'max-content' }}
      >
        {items.slice(0, 30).map((item) => (
          <div
            key={item}
            style={{
              flexShrink: 0,
              width: 100,
              height: 60,
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              background: 'var(--tao-color-fill-quaternary)',
              borderRadius: 6,
              fontSize: 13,
              color: 'var(--tao-color-text-secondary)',
            }}
          >
            {item}
          </div>
        ))}
      </div>
    </ScrollArea>
  );
}
```

## API


### [#](#scrollarea)ScrollArea



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | Scrollbar visibility behavior | `ScrollAreaType | undefined` | `hover` |
| direction | Scroll direction | `"vertical" | "horizontal" | "both" | undefined` | `vertical` |
| maxHeight | Max height — enables vertical scroll | `string | number | undefined` | `-` |
| maxWidth | Max width — enables horizontal scroll | `string | number | undefined` | `-` |
| scrollbarSize | Scrollbar size in px | `number | undefined` | `6` |
| scrollbarOffset | Offset from edges in px | `number | undefined` | `2` |
| scrollShadow | Show scroll shadows at edges | `boolean | undefined` | `-` |
| onScroll | Callback on scroll | `((e: UIEvent<HTMLDivElement, UIEvent>) => void) | undefined` | `-` |
| onScrollEnd | Callback when scrolled to bottom (threshold in px) | `(() => void) | undefined` | `-` |
| scrollEndThreshold | Threshold in px for onScrollEnd | `number | undefined` | `10` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

