组件Layout & Shells
ScrollArea
@mox-hub/ui 组件 · Layout & Shells · canonical
scroll-area@mox-hub/uiLayout & Shellscanonicalsrc/components/scroll-area.tsx变体演示scroll-area
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className* | string | ((state: ScrollAreaRootState) => string) | — | — |
| contentClassName* | string | — | — |
| children* | ReactNode | — | — |
| scrollFade* | boolean | false | — |
| scrollbarGutter* | boolean | false | — |
| fill* | boolean | false | — |
| clampContentMinWidth* | boolean | true | — |
| overscrollContain* | boolean | false | — |
源码
"use client"
import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
import type React from "react"
import { cn } from "../lib/utils"
/*
* coss ui ScrollArea(base-ui 配方移植,registry @coss/scroll-area)
* 根容器保持 `relative`(沿用项目旧版布局行为,不强占父级尺寸)。
*/
export function ScrollArea({
className,
contentClassName,
children,
scrollFade = false,
scrollbarGutter = false,
fill = false,
clampContentMinWidth = true,
overscrollContain = false,
...props
}: ScrollAreaPrimitive.Root.Props & {
/** 透传到 Content 包裹层的类(如滚动尾部留白 pb-*) */
contentClassName?: string
scrollFade?: boolean
scrollbarGutter?: boolean
fill?: boolean
clampContentMinWidth?: boolean
overscrollContain?: boolean
}): React.ReactElement {
return (
<ScrollAreaPrimitive.Root
data-slot="scroll-area"
className={cn("relative", className)}
{...props}
>
<ScrollAreaPrimitive.Viewport
className={cn(
"h-full rounded-[inherit] outline-none transition-shadow duration-fast focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-1 focus-visible:ring-offset-background",
overscrollContain &&
"data-has-overflow-y:overscroll-y-contain data-has-overflow-x:overscroll-x-contain",
scrollFade &&
"mask-t-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-start)))] mask-b-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-end)))] mask-l-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-start)))] mask-r-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-end)))] rtl:mask-l-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-end)))] rtl:mask-r-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-start)))] [--fade-size:1.5rem]",
scrollbarGutter &&
"data-has-overflow-y:pe-2.5 data-has-overflow-x:pb-2.5"
)}
data-slot="scroll-area-viewport"
>
<ScrollAreaPrimitive.Content
className={cn(
// fill:内容至少撑满视口(min-h-full)且贯通 flex 链——页面占满屏幕、
// 内容超出时自然撑高滚动;不用 size-full(锁死高度会裁断长内容)。
fill && "flex min-h-full w-full flex-col",
contentClassName,
)}
data-slot="scroll-area-content"
style={clampContentMinWidth ? { minWidth: 0 } : undefined}
>
{children}
</ScrollAreaPrimitive.Content>
</ScrollAreaPrimitive.Viewport>
<ScrollBar orientation="vertical" />
<ScrollBar orientation="horizontal" />
<ScrollAreaPrimitive.Corner data-slot="scroll-area-corner" />
</ScrollAreaPrimitive.Root>
)
}
export function ScrollBar({
className,
orientation = "vertical",
...props
}: ScrollAreaPrimitive.Scrollbar.Props): React.ReactElement {
return (
<ScrollAreaPrimitive.Scrollbar
className={cn(
"m-1 flex opacity-0 transition-opacity duration-fast delay-300 data-[orientation=horizontal]:h-1.5 data-[orientation=vertical]:w-1.5 data-[orientation=horizontal]:flex-col data-hovering:opacity-100 data-scrolling:opacity-100 data-hovering:delay-0 data-scrolling:delay-0",
className
)}
data-slot="scroll-area-scrollbar"
orientation={orientation}
{...props}
>
<ScrollAreaPrimitive.Thumb
className="relative flex-1 rounded-full bg-foreground/50"
data-slot="scroll-area-thumb"
/>
</ScrollAreaPrimitive.Scrollbar>
)
}
export { ScrollAreaPrimitive }
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
自定义滚动区,配合固定高度使用;横向滚动用 orientation 控制方向。