定价

ScrollArea 使用手册

v1.4.1 · @snowui-design-system/components

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

为内容提供可滚动区域与统一的滚动条，适合长列表、面板和受限空间中的正文。

使用选择

用于需要独立滚动的区域。页面不应无意创建多层嵌套滚动；表格的局部横向滚动优先沿用 Table。

  • axis 选择滚动方向；内容或宿主需要有限尺寸才能形成滚动区域。

  • bind:viewport 获取实际滚动元素，onscroll 接收滚动事件；用 ariaLabel 描述区域用途。

  • 滚动viewport默认名称随LocaleProvider更新，显式ariaLabel优先；children保持调用方内容。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { ScrollArea } from '@snowui-design-system/components';</script> <ScrollArea axis="vertical" ariaLabel="SnowUI documentation guide" style="width: min(100%, 30rem); height: 220px;">	<article style="display: flex; flex-direction: column; gap: var(--gap-4); padding: var(--padding-3); font-size: var(--text-14); line-height: var(--leading-14);">		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Getting started</h3>			<p>Install SnowUI in a Svelte 5 project and load the component stylesheet once at the application root.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Choose a component</h3>			<p>Start with the public components. Read their usage and API reference before adding custom layout or behavior.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Build with tokens</h3>			<p>Use the same typography, spacing, and color tokens across the SnowUI website and component documentation.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Compose the page</h3>			<p>Keep navigation, content, and supporting information in clear sections that remain readable on narrow screens.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Check interactions</h3>			<p>Try keyboard navigation, loading states, and disabled controls. Give every action a clear accessible name.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Review the result</h3>			<p>Compare the rendered page with its source, then verify light and dark themes before sharing the documentation.</p>		</section>	</article></ScrollArea>

API

关键字 类型 默认值 描述
axis ScrollAreaAxis "vertical" 允许滚动的方向
horizontalTrackPosition ScrollAreaHorizontalTrackPosition "container" 横向轨道停靠在容器底边，或在长容器经过页面视口时贴近视口底部
horizontalScrollbarVisibility "always" | "hover" "always" 横向滚动条在内容溢出时常显，或仅在鼠标移入区域时显示
ariaLabel string locale 文案 viewport 的无障碍标签；省略时随LocaleProvider更新，显式ariaLabel优先；viewport 使用 role="region"
viewport HTMLElement — 暴露内部可滚动 viewport，供读取或设置原生滚动位置
onscroll (event: Event) => void — viewport 原生 scroll 事件
children Snippet — 任意可滚动内容

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

功能概览

  • 支持纵向、横向和双轴滚动

  • 隐藏浏览器原生滚动条

  • 内容溢出时启用对应 SnowUI overlay scrollbar；纵向条在鼠标移入区域时使用 Frame 默认动效渐显、移出时渐隐，横向条默认常显并可配置为随区域 hover 显隐

  • 鼠标进入整条轨道（包括滑块外的空白区）即触发 Thumb hover；移出轨道后恢复，拖动期间保持 hover。

  • 点击轨道空白处将 Thumb 中心定位到点击处，到达边缘时夹到滚动起点或终点；按住可继续拖动。直接拖动 Thumb 保留原抓取位置，并与原生滚动位置同步。

  • 横向 Thumb 始终为 8px；纵向 Thumb 默认视觉宽 4px、hover 视觉宽 8px，整条轨道热区宽 16px，包含展开宽度 8px、靠边间距 4px 和内侧额外 4px；横向热区同样向上、下各扩展 4px

  • 长内容可把横向轨道贴近当前视口底部，容器离开视口后轨道仍收回到自身底边

  • 继承 Frame 的布局、状态、动效、响应式和属性透传能力

基础用法

<ScrollArea style="height: 20rem;">    <Frame column>...</Frame></ScrollArea>

双轴滚动

<ScrollArea axis="both" style="width: 100%; height: 100dvh;">    <Frame width="max-content" minWidth="100%">...</Frame></ScrollArea>

长内容保持横向轨道可达

<ScrollArea axis="horizontal" horizontalTrackPosition="viewport">    <Frame width="max-content">...</Frame></ScrollArea>

viewport 只改变横向轨道的停靠位置，不把内容最小宽度传播给页面，也不创建第二个滚动容器。轨道在 ScrollArea 穿过当前页面视口时贴近视口底部；到达 ScrollArea 底端后回到容器底边。

选择原则

  • 页面或普通容器需要 SnowUI 自建滚动条：使用 ScrollArea。

  • Table 已内置同源的局部横向 viewport 与视口贴底轨道：直接使用 Table，不再外包 ScrollArea。

  • 只需要浏览器原生滚动：直接使用 overflow，无需 ScrollArea。

  • 组件内部有特殊 Portal、固定头部或 Pin 区域时，可以继续直接复用 useOverlayScrollbar；不得复制滚动条算法或视觉 CSS。

ScrollArea 样式覆盖

先阅读 完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按 样式选择与改写顺序 使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

本组件源文件没有直接消费已登记的专属 override。组合子组件的样式通过公开 parts 或显式 child 配置；不要凭名称猜测变量。

设计指南 · Token · 组合边界

ScrollArea 类型与状态

必填属性：无具名必填属性。

可双向绑定：bind:viewport。

继承声明：Omit<FrameProps, "children" | "enableAutoLayout">。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。

ScrollAreaAxis

来源：components/src/components/ScrollArea.svelte

export type ScrollAreaAxis = "vertical" | "horizontal" | "both";

ScrollAreaHorizontalTrackPosition

来源：components/src/components/ScrollArea.svelte

export type ScrollAreaHorizontalTrackPosition = "container" | "viewport";