React 组件
UGScrollbar 滚动容器
基于原生滚动实现稳定的纵向、横向和双向滚动，保留浏览器性能、键盘能力与命令式控制。
导入方式
按需从包入口导入组件，并在应用入口引入一次样式文件。
tsx
import { UGScrollbar } from '@ug666/ui-react'基础用法
固定高度后，内容超出容器才产生纵向滚动。可聚焦区域应提供清晰的 aria-label。
横向滚动
用于宽表格、时间轴和横向卡片，不压缩内容本身。
最大高度
内容较少时保持自然高度，超过最大高度后再滚动，适合动态列表和下拉面板。
手动滚动
ref 直接指向真实滚动元素；scrollTo 与原生滚动事件无需额外适配层。
scrollTop: 0px
到达边界
到达边界只触发一次，离开后再次抵达才重新触发，适合按需加载下一页。
最近到达：尚未触发
滚动条外观
外观不改变滚动行为；隐藏轨道时仍应保留键盘、滚轮和触控操作。
auto
thin
hidden
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| orientation | 'vertical' | 'horizontal' | 'both' | 'vertical' | 设置允许滚动的方向。both 适合二维画布或宽表格。 |
| height | number | string | — | 设置固定高度；数字自动转换为 px。 |
| maxHeight | number | string | — | 设置最大高度，内容不足时容器保持自然高度。 |
| width | number | string | — | 设置固定宽度；数字自动转换为 px。 |
| maxWidth | number | string | — | 设置最大宽度，常用于横向滚动区域。 |
| scrollbar | 'auto' | 'thin' | 'hidden' | 'thin' | 控制原生滚动条外观；hidden 只隐藏轨道，不关闭滚动。 |
| overscroll | 'auto' | 'contain' | 'none' | 'contain' | 控制滚动到边界后是否继续传递给外层页面。 |
| distance | number | 0 | 距边界多少像素时触发 onEndReached。 |
| onScroll | UIEventHandler<HTMLDivElement> | — | 原生滚动事件，可读取 currentTarget.scrollTop 和 scrollLeft。 |
| onScrollPosition | (position: ScrollbarPosition) => void | — | 直接返回 scrollTop 与 scrollLeft，与 Vue scroll 事件的数据合同一致。 |
| onEndReached | (direction: ScrollbarEndDirection) => void | — | 首次抵达 top、right、bottom 或 left 边界时触发；离开边界后可再次触发。 |
| ref | Ref<HTMLDivElement> | — | 获取真实滚动元素，可调用 scrollTo、scrollBy 或直接读取滚动尺寸。 |
| 原生属性 | HTMLAttributes<HTMLDivElement> | — | 透传 tabIndex、role、aria-*、data-*、className 和 style 等属性。 |