> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/scrollbar.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.

# Scrollbar 滚动条

在区域内浏览较长或较宽的内容。

## 基本用法

鼠标移入区域时，滚动条平滑出现；移出后淡出，不占用内容宽度。滚轮、触摸与键盘保留浏览器的滚动行为。


项目动态 1

项目动态 2

项目动态 3

项目动态 4

项目动态 5

项目动态 6

项目动态 7

项目动态 8

项目动态 9

项目动态 10

项目动态 11

项目动态 12

basic.tsx

复制代码

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

export function ScrollbarBasic() {
  return (
    <Scrollbar height={200} aria-label={'项目动态'}>
      {Array.from({ length: 12 }, (_, index) => (
        <div key={String(index)} style={{ padding: '12px 20px' }}>
          {'项目动态'} {index + 1}
        </div>
      ))}
    </Scrollbar>
  );
}
```

展开代码

## 横向与常显

`orientation` 控制可滚动的方向。`scrollbar="always"` 常显，`hidden` 仅隐藏滚动条，内容仍可滚动。拖动滑块或点击轨道可定位内容。


项目 1

项目 2

项目 3

项目 4

项目 5

项目 6

basic.tsx

复制代码

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

export function ScrollbarHorizontal() {
  return (
    <Scrollbar
      orientation="horizontal"
      scrollbar="always"
      aria-label={'项目看板'}
    >
      <div style={{ display: 'flex', width: 'max-content', gap: 16, padding: '12px 12px 24px' }}>
        {Array.from({ length: 6 }, (_, index) => (
          <div
            key={String(index)}
            style={{
              width: 180,
              padding: 24,
              borderRadius: 'var(--leaf-radius)',
              background: 'var(--leaf-color-surface-muted)',
            }}
          >
            {'项目'} {index + 1}
          </div>
        ))}
      </div>
    </Scrollbar>
  );
}
```

展开代码

## 动态内容与滚动控制

内容和容器尺寸变化后，滑块自动更新。`ref` 指向实际滚动容器，可调用 `scrollTo`、读取 `scrollTop`，也可传给 BackTop 等组件。到达边缘或没有溢出时，滚轮继续滚动页面。


增加内容返回顶部

条目 1

条目 2

条目 3

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/scrollbar/basic.tsx"
import { Button, Flex, Scrollbar } from '@ifhover/leaf-ui';

import { useRef, useState } from 'react';

export function ScrollbarDynamic() {
  const viewport = useRef<HTMLDivElement>(null);
  const [count, setCount] = useState(3);
  return (
    <Flex direction="column" gap="md">
      <Flex gap="sm" wrap>
        <Button variant="outline" onClick={() => setCount((previous) => previous + 3)}>
          {'增加内容'}
        </Button>
        <Button
          variant="soft"
          onClick={() => viewport.current?.scrollTo({ top: 0, behavior: 'smooth' })}
        >
          {'返回顶部'}
        </Button>
      </Flex>
      <Scrollbar ref={viewport} maxHeight={200} aria-label={'动态列表'}>
        {Array.from({ length: count }, (_, index) => (
          <div key={String(index)} style={{ padding: '12px 20px' }}>
            {'条目'} {index + 1}
          </div>
        ))}
      </Scrollbar>
    </Flex>
  );
}
```

展开代码

## Scrollbar API

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

| 属性                  | 类型                                     | 默认值      | 说明                  |
| ------------------- | -------------------------------------- | -------- | ------------------- |
| `height`            | `CSSProperties['height']`              | —        | 滚动区域高度。             |
| `maxHeight`         | `CSSProperties['maxHeight']`           | —        | 最大高度；未设置高度限制时跟随内容。  |
| `orientation`       | `'vertical' \| 'horizontal' \| 'both'` | `'both'` | 滚动方向。               |
| `scrollbar`         | `'auto' \| 'always' \| 'hidden'`       | `'auto'` | 滚动条显示方式。            |
| `viewportClassName` | `string`                               | —        | 实际滚动容器的类名。          |
| `viewportStyle`     | `CSSProperties`                        | —        | 实际滚动容器的样式。          |
| `contentClassName`  | `string`                               | —        | 内容容器的类名。            |
| `contentStyle`      | `CSSProperties`                        | —        | 内容容器的样式。            |
| `verticalOffset`    | `number`                               | `0`      | 纵向轨道顶部预留空间，适用于固定表头。 |

`style` 与 `className` 用于外层；`id`、`role`、`tabIndex`、区域名称与 `onScroll` 用于实际滚动容器。建议提供 `aria-label` 或 `aria-labelledby` 为滚动区域命名。滑块可通过 Tab 聚焦，支持方向键、PageUp / PageDown 与 Home / End。

`ScrollArea` 使用相同的滚动条实现，默认仅纵向滚动；已有用法可以继续使用。