ScrollArea 滾動區域
可客製化樣式的滾動區塊元件，擴充瀏覽器原生捲動行為以便做一致的跨瀏覽器捲動樣式與控制。
基本使用
基本使用
基本的滾動區域，包含垂直和水平滾動
自定義滾動控制
透過組件 ref 取得滾動控制方法，可程式化控制滾動位置。
自定義滾動控制
透過組件方法控制滾動位置，支援滾動到頂部、底部等功能
捲軸顯示類型
支援四種不同的捲軸顯示策略。
捲軸顯示類型
展示不同的捲軸顯示策略：auto、always、scroll、hover
Auto（預設）
內容溢出時顯示捲軸
Always
總是顯示捲軸
Scroll
滾動時顯示捲軸
Hover
hover 或滾動時顯示捲軸
水平滾動
包含水平和垂直滾動的內容
滾動方向控制
透過 scrollX 和 scrollY props 控制允許的滾動方向。
滾動方向控制
透過 horizontal 和 vertical props 控制允許的滾動方向
僅垂直滾動
scrollY=true, scrollX=false（預設）
僅水平滾動
scrollY=false, scrollX=true
雙向滾動
scrollY=true, scrollX=true
禁用滾動
scrollY=false, scrollX=false
API
屬性
| 屬性 | 類型 | 預設值 | 說明 |
|---|---|---|---|
type | 'auto' | 'always' | 'scroll' | 'hover' | 'hover' | 捲軸顯示策略 |
scrollHideDelay | number | 600 | 停止互動後隱藏捲軸的延遲時間（毫秒） |
dir | 'ltr' | 'rtl' | 'ltr' | 讀取方向 |
scrollX | boolean | false | 是否允許水平滾動 |
scrollY | boolean | true | 是否允許垂直滾動 |
class | string | - | 自定義根元素的 class |
style | string | object | - | 自定義根元素的 style |
方法 Methods
透過 ref 取得組件實例後可呼叫以下方法：
| 方法 | 說明 |
|---|---|
scrollTop() | 滾動到頂部 |
scrollTopLeft() | 滾動到左上角 |
scrollBottom() | 滾動到底部 |
scrollTo(options) | 滾動到指定位置 |
getViewport() | 取得 viewport 元素 |
插槽 Slots
| 插槽 | 說明 |
|---|---|
default | 滾動區域的內容 |
樣式客製化
組件提供 CSS 變數供客製化樣式：
css
.sh-scroll-area {
--scroll-thumb-color: theme('colors.gray.400');
--scroll-thumb-hover-color: theme('colors.gray.500');
--scroll-thumb-active-color: theme('colors.gray.600');
--scroll-track-color: theme('colors.gray.100');
}無障礙
- 保留原生滾動行為以維持鍵盤導航支援
- 支援螢幕閱讀器等輔助技術
- 支援 RTL（right-to-left）布局
- 鍵盤滾動由平台原生提供（PageUp/PageDown/方向鍵等）
注意事項
- 滾動條置於內容之上，不佔用布局空間
- 使用原生滾動確保最佳效能與相容性
- 在
type="scroll"或type="hover"模式下，可調整scrollHideDelay控制隱藏延遲 - 支援同時水平與垂直滾動