ScrollArea

自定义滚动区域,基于 reka-ui ScrollAreaRoot,内部自动提供垂直和水平 ScrollBar,在跨平台得到一致的滚动条样式。

Anatomy

• ScrollArea滚动区域根,内部已挂载 Viewport、垂直 / 水平 ScrollBar 与 ScrollAreaCorner
  • ScrollBar可选,单独使用以自定义额外方向或覆写样式;根组件已默认包含两个方向

基本用法

垂直滚动

固定高度的容器超出时显示滚动条。

列表项 1

列表项 2

列表项 3

列表项 4

列表项 5

列表项 6

列表项 7

列表项 8

列表项 9

列表项 10

列表项 11

列表项 12

列表项 13

列表项 14

列表项 15

列表项 16

列表项 17

列表项 18

列表项 19

列表项 20

列表项 21

列表项 22

列表项 23

列表项 24

列表项 25

列表项 26

列表项 27

列表项 28

列表项 29

列表项 30

<script setup lang="ts">
import { ScrollArea } from '@tripo3d/design';
</script>

<template>
  <ScrollArea class="h-50 w-64 rounded-2 border border-white-10 bg-gray-2">
    <div class="p-3">
      <div v-for="i in 30" :key="i" class="border-b border-white-5 py-1 text-sm text-white-80">
        列表项 {{ i }}
      </div>
    </div>
  </ScrollArea>
</template>

水平滚动

横向内容溢出

内部内容宽于 Viewport 时,底部自动出现水平滚动条。

1

2

3

4

5

6

7

8

9

10

11

12

<ScrollArea class="w-80 rounded-2 border border-white-10 bg-gray-2">
  <div class="flex gap-3 p-3 w-max">
    <div v-for="i in 12" :key="i" class="size-20 shrink-0 rounded-2 bg-gray-3">
      {{ i }}
    </div>
  </div>
</ScrollArea>

自定义 Viewport

viewportClass

为 Viewport 单独追加 class,比如给内部容器设置 padding。

行 1

行 2

行 3

行 4

行 5

行 6

行 7

行 8

行 9

行 10

行 11

行 12

行 13

行 14

行 15

行 16

行 17

行 18

行 19

行 20

<ScrollArea
  class="h-50 w-64 rounded-2 border border-white-10 bg-gray-2"
  viewport-class="p-4"
>
  <div v-for="i in 20" :key="i" class="py-1 text-sm text-white-80">
    行 {{ i }}
  </div>
</ScrollArea>

API

ScrollArea Props

名称	类型	默认值	说明
class	string	—	根容器 class;通常在此设置高度 / 宽度边界
viewportClass	string	—	Viewport 的额外 class,可用于 padding 等内部布局
type	'auto' | 'always' | 'scroll' | 'hover'	'hover'	滚动条显示策略,透传自 reka-ui
dir	'ltr' | 'rtl'	—	书写方向,透传自 reka-ui
scrollHideDelay	number	600	scroll/hover 模式下滚动条隐藏延迟(ms)

其余 props 透传至 reka-ui ScrollAreaRootProps。

ScrollBar Props

名称	类型	默认值	说明
orientation	'vertical' | 'horizontal'	'vertical'	滚动条方向
class	string	—	滚动条额外 class

其余 props 透传至 reka-ui ScrollAreaScrollbarProps。

Slots

插槽	作用域	说明
default (ScrollArea)	—	滚动区域的内容;根组件会自动包进 Viewport

可访问性

• 基于 reka-ui,原生滚动事件与键盘操作(方向键、PgUp/PgDn)均可用
• 滚动条为装饰性元素,内容区依然是标准可滚动区域,屏幕阅读器能正常遍历
• 请务必为根容器设置高度 / 宽度限制,否则不会出现滚动条