ScrollArea

增强原生滚动功能，实现自定义的跨浏览器样式。

View code

功能特性

滚动条位于可滚动内容上方，不占用布局空间
滚动行为保持原生特性，无需通过 CSS 变换实现底层位移
仅在与控件交互时启用指针行为垫片，键盘操作不受影响
支持从右到左的布局方向

安装

通过命令行安装该组件。

$ npm add reka-ui

结构构成

导入所有部件并进行组合。

vue

<script setup>
import { ScrollAreaRoot, ScrollAreaScrollbar, ScrollAreaThumb, ScrollAreaViewport } from 'reka-ui'
</script>

<template>
  <ScrollAreaRoot>
    <ScrollAreaViewport />
    <ScrollAreaScrollbar orientation="horizontal">
      <ScrollAreaThumb />
    </ScrollAreaScrollbar>
    <ScrollAreaScrollbar orientation="vertical">
      <ScrollAreaThumb />
    </ScrollAreaScrollbar>
    <ScrollAreaCorner />
  </ScrollAreaRoot>
</template>

API 参考

Root

包含滚动区域的所有组成部分。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`dir`		`'ltr' \| 'rtl'` The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
`scrollHideDelay`	`600`	`number` If type is set to either `scroll` or `hover`, this prop determines the length of time, in milliseconds, before the scrollbars are hidden after the user stops interacting with scrollbars.
`type`	`'hover'`	`'always' \| 'scroll' \| 'hover' \| 'auto'` Describes the nature of scrollbar visibility, similar to how the scrollbar preferences in MacOS control visibility of native scrollbars. `auto` - means that scrollbars are visible when content is overflowing on the corresponding orientation. `always` - means that scrollbars are always visible regardless of whether the content is overflowing. `scroll` - means that scrollbars are visible when the user is scrolling along its corresponding orientation. `hover` - when the user is scrolling along its corresponding orientation and when the user is hovering over the scroll area.

Methods	Type
`scrollTop`	`() => void` Scroll viewport to top
`scrollTopLeft`	`() => void` Scroll viewport to top-left

Viewport

滚动区域的视口区域。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`nonce`		`string` Will add `nonce` attribute to the style tag which can be used by Content Security Policy. If omitted, inherits globally from `ConfigProvider`.

Scrollbar

垂直滚动条。添加第二个设置 orientation 属性为 horizontal 的 Scrollbar 可实现水平滚动。

tip

Built with Presence component - supports any animation techniques while maintaining access to presence emitted events.

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`forceMount`		`boolean` Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.
`orientation`	`'vertical'`	`'vertical' \| 'horizontal'` The orientation of the scrollbar

Data Attribute	Value
`[data-state]`	`"visible" \| "hidden"`
`[data-orientation]`	`"vertical" \| "horizontal"`

Thumb

用于 ScrollAreaScrollbar 中的滚动滑块。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-state]`	`"visible" \| "hidden"`

Corner

垂直和水平滚动条交汇的角落部件。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

示例

自定义滚动

使用暴露的 viewport 在默认方法之外修改或设置滚动位置

vue

<script setup lang="ts">
import { ScrollAreaRoot, ScrollAreaScrollbar, ScrollAreaThumb, ScrollAreaViewport } from 'reka-ui'

const scrollArea = useTemplateRef('scrollArea')
function scrollToBottom() {
  const viewport = scrollArea.value?.viewport
  if (viewport) {
    const top = scrollArea.value?.$el.scrollHeight
    container.scrollTo({
      top,
      behavior: 'smooth'
    })
  }
}
</script>

<template>
  <ScrollAreaRoot ref="scrollArea">
    <ScrollAreaViewport />
    <ScrollAreaScrollbar orientation="horizontal">
      <ScrollAreaThumb />
    </ScrollAreaScrollbar>
    <ScrollAreaScrollbar orientation="vertical">
      <ScrollAreaThumb />
    </ScrollAreaScrollbar>
    <ScrollAreaCorner />
  </ScrollAreaRoot>
</template>

无障碍访问

在大多数情况下，最佳实践是依赖原生滚动功能并使用 CSS 中可用的自定义选项。当这些选项不足以满足需求时，ScrollArea 在保持浏览器原生滚动行为（以及键盘滚动等无障碍功能）的同时，提供了额外的可定制性。

键盘交互

由于组件依赖原生滚动，默认支持键盘滚动。不同平台的具体键盘交互可能有所差异，因此我们不在此具体说明，也不添加特定的事件监听器来处理通过按键事件触发的滚动。

ScrollArea ​

功能特性 ​

安装 ​

结构构成 ​

API 参考 ​

Root ​

Viewport ​

Scrollbar ​

Thumb ​

Corner ​

示例 ​

自定义滚动 ​

无障碍访问 ​

键盘交互 ​