ScrollArea 滚动区域
包裹内容并接管滚动条外观的容器：细条自定义滚动条、hover 变粗，type 控制滚动条显示时机（auto / always / scroll / hover），滚动事件节流派发。
基础用法
height 固定视口高度，超出部分纵向滚动；滚动条细条展示，hover 变粗。
定高滚动
第 1 行内容：ScrollArea 支持自定义滚动条外观
第 2 行内容：细条 + hover 变粗
第 3 行内容：滚动事件节流派发 oas-scroll
第 4 行内容：wheel 平滑滚动
第 5 行内容：支持 auto-hide 自动隐藏
第 6 行内容：横向内容同样接管滚动条
第 7 行内容：颜色走主题 token
第 8 行内容：适合列表、日志、长文案
第 9 行内容：内容不足时不显示滚动条
第 10 行内容：自定义内容插槽
宽度与横向滚动
width 固定视口宽度，宽内容产生横向滚动条。
横向滚动
显示模式（type）
type 控制滚动条显示时机，四档：always（默认，溢出时常显，见基础用法）、auto（滚动/悬停时显示，停止后自动淡出）、scroll（仅滚动时显示，悬停不出）、hover（悬停时显示，离开立即隐藏）。旧 auto-hide 布尔属性向后兼容，等价 type="auto"；type 在场时以 type 为准，非法值回退 always。
type=auto（等价旧 auto-hide）
滚动我看看滚动条：平时隐藏，滚动时出现
停下来等一秒，滚动条自动淡出
悬停在区域内也会临时显示
旧写法 auto-hide 与 type="auto" 完全等价
适合不希望滚动条干扰阅读的界面
type=scroll（仅滚动时显示）
滚动时滚动条出现，停止后自动淡出
与 auto 的区别：悬停不显示滚动条
适合阅读类界面：滚动时有位置反馈
静止阅读时不被滚动条占据注意力
移动端长文阅读场景推荐
type=hover（悬停时显示）
鼠标悬停在区域内即显示滚动条
移开后立即隐藏（带淡出过渡）
与 auto 的区别：不滚动只悬停也会显示
适合需要随时观察滚动位置的场景
桌面端鼠标交互友好
滚动事件
滚动事件按 rAF 节流派发 oas-scroll，detail 携带 { scrollTop, scrollLeft }。
oas-scroll 事件
第 1 行：滚动事件节流派发
第 2 行：detail 包含 scrollTop / scrollLeft
第 3 行：适合做滚动监听、懒加载
第 4 行：与虚拟列表滚动逻辑互补
第 5 行：滚动条位置同步更新
第 6 行：继续滚动查看输出
第 7 行：节流避免高频事件
第 8 行：最后一个示例
scrollTop：0
编程滚动
组件实例暴露 scrollTo(options) / scrollToTop() / scrollToBottom() / scrollIntoView(selectorOrEl) 方法（委托视口原生滚动；仅 scrollToTop / scrollToBottom 默认平滑滚动、可传 behavior 覆盖，scrollTo / scrollIntoView 透传原生语义），宿主可按需程序化滚动。
编程滚动方法
第 1 行：编程滚动示例（下方按钮调用实例方法）
第 2 行：scrollTo 支持 { top, left, behavior }
第 3 行：scrollToTop / scrollToBottom 一键到位
第 4 行：scrollIntoView 定位容器内元素
目标行：被 scrollIntoView 定位到这里
第 6 行：平滑滚动由浏览器接管
第 7 行：适合「返回顶部」「加载更多定位」
第 8 行：继续滚到底部看看
第 9 行：更多内容撑开高度
第 10 行：最后一行
滚动边缘阴影
scroll-shadow 开启滚动边缘阴影（CSS-only，与 modal 同款实现）：滚动到边缘时对应方向的阴影渐隐，中部时上下边缘都有阴影提示。
scroll-shadow
第 1 行：scroll-shadow 显示滚动边缘阴影
第 2 行：顶部时上方阴影渐隐
第 3 行：滚到中部时上下边缘都有阴影
第 4 行：提示这个方向还有内容
第 5 行：滚到底部时下方阴影渐隐
第 6 行：适合长列表、聊天记录、新闻详情
第 7 行：纯 CSS 实现，零 JS 开销
第 8 行：继续滚动观察阴影变化
贴底（stick-to-bottom）
stick-to-bottom 时新内容追加后若用户本就停靠在底部（距底 ≤8px）自动滚到底；用户上翻阅读历史时追加不打断。适合聊天、日志等追加场景。
stick-to-bottom
点「追加一条消息」查看自动贴底；先向上翻到中间再追加，观察不会被拉回底部。
到底事件（oas-end-reached）
oas-end-reached 在滚动到达容器底部（横向为右边缘）时派发，detail: { direction: 'bottom' | 'right' }。end-distance 设置距边缘多少 px 内触发（默认 0）。离开边缘后再回到边缘才会再次触发，典型用于无限滚动加载。
end-reached 到底事件
初始项 1：滚到底部触发 oas-end-reached
初始项 2：end-distance=10 提前触发
初始项 3：触发后自动追加新内容
初始项 4：离开底部后回底再次触发
初始项 5：典型无限滚动加载场景
触发次数：0
RTL
宿主设置 dir="rtl" 时，横向滚动条位置与滚轮转译按 RTL 语义工作：Chromium/Firefox 下横向 scrollLeft 为负值区间 [-max, 0]，纵向滚轮转译为横向滚动时方向与 LTR 相反，thumb 位置按绝对值换算。
RTL 横向滚动
`dir="rtl"` 下内容右对齐起始；滚轮/触控板滚动方向与 LTR 相反。注：横向滚动条实际渲染位置遵循浏览器原生 RTL 行为。
API
方法
| 方法 | 说明 |
|---|---|
scrollTo(options) / scrollTo(x, y) | 滚动到指定位置，options: { top?, left?, behavior?: 'auto' | 'smooth' }（委托视口） |
scrollToTop(options?) / scrollToBottom(options?) | 滚到顶/底，options: { behavior? } 默认平滑 |
scrollIntoView(selectorOrEl, options?) | 容器内元素滚进视口，options 的 block / inline 透传 |
oas-scroll-area
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
auto-hide | 旧布尔用法：滚动条仅在滚动/悬停时显示，超时自动隐藏——无 type 时等价 type="auto"；type 在场时以 type 为准 | boolean | — |
end-distance | oas-end-reached 触发距离（px，默认 0）：距底/右边缘 N px 内即算到底 | string | 0 |
height | 视口高度（px），不设置时随内容自然撑开 | — | — |
scroll-shadow | 滚动边缘阴影（CSS-only）：滚动到边缘时阴影渐隐提示还有内容 | — | — |
stick-to-bottom | 贴底：新内容追加时若当前停靠在底部（距底 ≤8px）自动滚到底，上翻阅读时不打断 | boolean | — |
type | 滚动条显示模式（auto | always | scroll | hover，默认 always）：auto 滚动/悬停显示后延时隐藏；always 溢出常显；scroll 仅滚动时显示；hover 仅悬停时显示。非法值回退 always | ScrollAreaType | always |
width | 视口宽度（px），不设置时铺满宿主宽度 | — | — |
事件
| 事件 | 说明 |
|---|---|
oas-end-reached | 滚动到达容器底部（横向到达右边缘）时派发，detail: { direction: 'bottom' | 'right' }；离开边缘后再回到边缘才可再次触发 |
oas-scroll | 滚动事件（rAF 节流），detail: { scrollTop, scrollLeft } |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 可滚动内容 |
部件：::part(viewport) 滚动视口、::part(track-v) / ::part(track-h) 滚动轨道、::part(thumb-v) / ::part(thumb-h) 滚动块。视口可聚焦（tabindex="0"），方向键滚动。