ScrollShadow
基础布局基于 Bootstrap 5 的滚动阴影组件，在可滚动容器的边缘叠加渐变阴影提示剩余内容，支持垂直/水平/双向滚动、阴影尺寸与颜色自定义、可见性变化回调、RTL 布局，以及 useScrollShadow Hook 自定义组合
Component Demo
Basic usage and examples of the ScrollShadow component
基础用法
ScrollShadow 默认跟踪垂直方向：内部渲染一个 overflow-y: auto 的滚动容器，顶部阴影表示上方还有内容，底部阴影表示下方还有内容，滚动到两端时对应阴影自动淡出
横向滚动
direction="horizontal" 时跟踪左右两端：内部容器 overflow-x: auto、overflow-y: hidden，内容宽度超过容器宽度后即可横向滚动
双向滚动
direction="both" 同时跟踪垂直与水平两个方向，适合宽高都受限的内容（如宽表格、大画布），四边阴影独立显示
RTL 布局
在 dir="rtl" 布局下横向阴影自动换边：初始位置在右侧起点，左端显示阴影；滚动到最左端后右端阴影出现
自定义阴影
shadowSize 控制阴影层厚度，shadowColor 控制渐变起点颜色，disabled 可随时关闭阴影；两者通过 CSS 变量 --rbs-scroll-shadow-size 与 --rbs-scroll-shadow-color 生效，也可以在全局样式里统一覆盖
可见性回调
onChange 在四边阴影可见性发生变化时触发（挂载时若初始存在阴影也会触发一次），返回的 ScrollShadowVisibility 对象可用于渲染自定义提示或与其他状态联动
Hook 自定义组合
useScrollShadow 返回 ref 与 visibility，可挂载到任意已有的滚动容器（如 .table-responsive）上自行渲染阴影或提示，ScrollShadow 组件本身即基于该 Hook 实现
API Documentation
Complete API reference for the ScrollShadow component
Props
ScrollShadow
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
as | ElementType | 'div' | 外层包装元素，内部滚动容器始终渲染为 div |
direction | ScrollShadowDirection | 'vertical' | 阴影方向：vertical/horizontal/both；同时决定内部容器的滚动轴向，未跟踪的轴 overflow 为 hidden |
disabled | boolean | false | 禁用阴影：不渲染阴影层且不监听滚动，容器仍可正常滚动 |
shadowSize | number | 24 | 阴影层厚度（像素）：vertical 时为阴影高度，horizontal 时为阴影宽度 |
shadowColor | string | rgba(0, 0, 0, 0.05) | 阴影颜色，作为渐变起点自动生成“浓 → 淡 → 透明”的三段式渐变阴影，默认使用 10% 半透明黑色，在深浅背景上都自然可见；也可覆盖 CSS 变量 --rbs-scroll-shadow-color 全局调整 |
onChange | (visibility: ScrollShadowVisibility) => void | - | 阴影可见性变化回调，参数为四边可见性对象；挂载时若初始存在阴影也会触发一次（自动支持 RTL 方向） |
onScroll | UIEventHandler<HTMLElement> | - | 内部滚动容器的滚动事件回调（绑定在滚动元素上，而非外层包装元素） |
tabIndex | number | - | 内部滚动容器的键盘焦点序号，设置后容器可通过键盘滚动 |
children | ReactNode | - | 可滚动内容，渲染在内部滚动容器中 |
className | string | - | 外层包装元素的自定义类名 |
style | CSSProperties | - | 外层包装元素的内联样式，通常用来限制滚动区域的高度/宽度 |
useScrollShadow
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
direction | ScrollShadowDirection | 'vertical' | 跟踪的滚动方向，与组件的 direction 行为一致（自动支持 RTL） |
disabled | boolean | false | 禁用跟踪，可见性重置为四边均不可见 |
onChange | (visibility: ScrollShadowVisibility) => void | - | 可见性变化回调，行为与组件的 onChange 一致 |
ref | RefCallback<T> | - | 返回的 ref 回调，挂载到任意可滚动元素上开始跟踪（需自行处理监听期间的样式/滚动溢出） |
visibility | ScrollShadowVisibility | - | 返回的可见性对象，top/bottom/left/right 分别表示四边阴影是否可见（即对应方向是否还有可滚动内容） |
Common Props
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
...rest | HTMLAttributes | - | 透传原生元素属性（如 `onClick`、`dir`、`role` 等，作用于外层包装元素） |
Type Definitions
ScrollShadowProps
滚动阴影容器组件属性接口
export interface ScrollShadowProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
as?: ElementType;
children?: ReactNode;
className?: string;
direction?: ScrollShadowDirection;
disabled?: boolean;
onChange?: (visibility: ScrollShadowVisibility) => void;
onScroll?: UIEventHandler<HTMLElement>;
shadowColor?: string;
shadowSize?: number;
tabIndex?: number;
}ScrollShadowDirection
滚动阴影方向联合类型
export type ScrollShadowDirection = 'both' | 'horizontal' | 'vertical';ScrollShadowVisibility
四边阴影可见性状态
export interface ScrollShadowVisibility {
bottom: boolean;
left: boolean;
right: boolean;
top: boolean;
}UseScrollShadowOptions
滚动阴影跟踪 Hook 配置项
export interface UseScrollShadowOptions {
direction?: ScrollShadowDirection;
disabled?: boolean;
onChange?: (visibility: ScrollShadowVisibility) => void;
}UseScrollShadowResult
滚动阴影跟踪 Hook 返回值
export interface UseScrollShadowResult<T extends HTMLElement = HTMLElement> {
ref: RefCallback<T>;
visibility: ScrollShadowVisibility;
}