跳到主要內容跳到主要內容
🚀 影響 Material UI 的 2025 年開發藍圖！參與最新的開發者問卷調查

滑桿API

React 滑桿元件的 API 參考文件。了解這個匯出模組的 props、CSS 和其他 API。

示範

匯入

import Slider from '@mui/material/Slider';
// or
import { Slider } from '@mui/material';

閱讀這份關於最小化 bundle 大小的指南，以了解差異。

Props

原生元件的 Props 也可用。

名稱類型預設描述
aria-labelstring-

滑桿的標籤。

aria-labelledbystring-

包含滑桿標籤之元素的 ID。

aria-valuetextstring-

一個字串值，為滑桿的目前值提供使用者友善的名稱。

classesobject-

覆寫或擴展套用至元件的樣式。

請參閱下方CSS 類別 API 以了解更多詳細資訊。

color'primary'
| 'secondary'
| 'error'
| 'info'
| 'success'
| 'warning'
| string		'primary'

元件的顏色。它同時支援預設和自訂主題顏色，這些顏色可以如調色盤自訂指南中所示新增。

components{ Input?: elementType, Mark?: elementType, MarkLabel?: elementType, Rail?: elementType, Root?: elementType, Thumb?: elementType, Track?: elementType, ValueLabel?: elementType }{}

用於每個 slot 內部的元件。

componentsProps{ input?: func
| object, mark?: func
| object, markLabel?: func
| object, rail?: func
| object, root?: func
| object, thumb?: func
| object, track?: func
| object, valueLabel?: func
| { children?: element, className?: string, open?: bool, style?: object, value?: node, valueLabelDisplay?: 'auto'
| 'off'
| 'on' } }		{}

slot 元件的額外 props。您可以覆寫現有的 props 或新增 props。

defaultValueArray<number>
| number		-

預設值。當元件不受控制時使用。

disabledboolfalse

如果為 true，則元件停用。

disableSwapboolfalse

如果為 true，當拖曳另一個滑桿時，將指標移動到滑桿上方時，作用中的滑桿不會交換。

getAriaLabelfunc-

接受一個函式，該函式傳回一個字串值，為滑桿的滑桿標籤提供使用者友善的名稱。這對於螢幕閱讀器使用者來說很重要。

簽名：function(index: number) => string
  • index 要格式化的滑桿標籤索引。
getAriaValueTextfunc-

接受一個函式，該函式傳回一個字串值，為滑桿的目前值提供使用者友善的名稱。這對於螢幕閱讀器使用者來說很重要。

簽名：function(value: number, index: number) => string
  • value 要格式化的滑桿標籤值。
  • index 要格式化的滑桿標籤索引。
marksArray<{ label?: node, value: number }>
| bool		false

刻度標記指示使用者可以將滑桿移動到的預定值。如果為 true，則刻度標記會根據 step prop 的值間隔。如果是陣列，則應包含具有 value 和選用 label 鍵的物件。

maxnumber100

滑桿允許的最大值。不應等於 min。

minnumber0

滑桿允許的最小值。不應等於 max。

namestring-

隱藏 input 元素的 Name 屬性。

onChangefunc-

當滑桿的值變更時觸發的回呼函式。

簽名：function(event: Event, value: Value, activeThumb: number) => void
  • event 回呼的事件來源。您可以透過存取 event.target.value (any) 來提取新值。警告：這是一個通用事件，而不是變更事件。
  • value 新值。
  • activeThumb 目前移動的滑桿索引。
onChangeCommittedfunc-

當觸發 mouseup 時觸發的回呼函式。

簽名：function(event: React.SyntheticEvent | Event, value: Value) => void
  • event 回呼的事件來源。警告：這是一個通用事件，而不是變更事件。
  • value 新值。
orientation'horizontal'
| 'vertical'		'horizontal'

元件方向。

scalefuncfunction Identity(x) { return x; }

轉換函式，用於變更滑桿的比例。

簽名：function(x: any) => any
    shiftStepnumber10

    當使用 Page Up/Page Down 或 Shift + 向上/向下箭頭時，滑桿可以逐步瀏覽值的精細度。

    size'small'
    | 'medium'
    | string    		'medium'

    滑桿的大小。

    slotProps{ input?: func
    | object, mark?: func
    | object, markLabel?: func
    | object, rail?: func
    | object, root?: func
    | object, thumb?: func
    | object, track?: func
    | object, valueLabel?: func
    | { children?: element, className?: string, open?: bool, style?: object, value?: node, valueLabelDisplay?: 'auto'
    | 'off'
    | 'on' } }    		{}

    用於滑桿內部每個 slot 的 props。

    slots{ input?: elementType, mark?: elementType, markLabel?: elementType, rail?: elementType, root?: elementType, thumb?: elementType, track?: elementType, valueLabel?: elementType }{}

    用於滑桿內部每個 slot 的元件。字串可使用 HTML 元素或元件。

    stepnumber1

    滑桿可以逐步瀏覽值的精細度。（「離散」滑桿。）min prop 作為有效值的起點。我們建議 (max - min) 可以被 step 整除。
    當 step 為 null 時，滑桿只能滑到使用 marks prop 提供的刻度標記上。

    sxArray<func
    | object
    | bool>
    | func
    | object    		-

    系統 prop，允許定義系統覆寫以及其他 CSS 樣式。

    請參閱 `sx` 頁面 以了解更多詳細資訊。

    tabIndexnumber-

    隱藏 input 元素的 Tab index 屬性。

    track'inverted'
    | 'normal'
    | false    		'normal'

    軌跡呈現方式

    • normal 軌跡將呈現代表滑桿值的長條。
    • inverted 軌跡將呈現代表剩餘滑桿值的長條。
    • false 軌跡將不呈現長條。
    valueArray<number>
    | number    		-

    滑桿的值。對於範圍滑桿，請提供包含兩個值的陣列。

    valueLabelDisplay'auto'
    | 'off'
    | 'on'    		'off'

    控制何時顯示值標籤

    • auto 當滑桿被懸停或聚焦時，值標籤將會顯示。
    • on 將持續顯示。
    • off 將永遠不顯示。
    valueLabelFormatfunc
    | string    		function Identity(x) { return x; }

    格式化值標籤值的格式化函式。
    當提供函式時，它應具有以下簽名
    - {number} value 要格式化的值標籤值 - {number} index 要格式化的值標籤索引

    ref 會轉發到根元素。

    主題預設 props

    您可以使用 MuiSlider 透過主題變更此元件的預設 props。

    CSS 類別

    這些類別名稱對於使用 CSS 設定樣式很有用。當觸發特定狀態時，它們會套用至元件的 slots。

    類別名稱規則名稱描述
    .Mui-active如果滑桿元素處於作用中狀態，則套用至滑桿元素的狀態類別。
    .Mui-disabled如果 disabled={true}，則套用至根元素和滑桿元素的狀態類別。
    .Mui-focusVisible如果鍵盤聚焦，則套用至滑桿元素的狀態類別。
    .MuiSlider-colorErrorcolorError如果 color="error"，則套用至根元素的樣式。
    .MuiSlider-colorInfocolorInfo如果 color="info"，則套用至根元素的樣式。
    .MuiSlider-colorPrimarycolorPrimary如果 color="primary"，則套用至根元素的樣式。
    .MuiSlider-colorSecondarycolorSecondary如果 color="secondary"，則套用至根元素的樣式。
    .MuiSlider-colorSuccesscolorSuccess如果 color="success"，則套用至根元素的樣式。
    .MuiSlider-colorWarningcolorWarning如果 color="warning"，則套用至根元素的樣式。
    .MuiSlider-draggingdragging如果正在拖曳滑桿，則套用至根元素的狀態類別。
    .MuiSlider-markmark套用至刻度標記元素的樣式。
    .MuiSlider-markActivemarkActive如果處於作用中狀態（取決於值），則套用至刻度標記元素的樣式。
    .MuiSlider-markedmarked如果 marks 提供至少一個標籤，則套用至根元素的樣式。
    .MuiSlider-markLabelmarkLabel套用至刻度標記標籤元素的樣式。
    .MuiSlider-markLabelActivemarkLabelActive如果處於作用中狀態（取決於值），則套用至刻度標記標籤元素的樣式。
    .MuiSlider-railrail套用至軌跡元素的樣式。
    .MuiSlider-rootroot套用至根元素的樣式。
    .MuiSlider-sizeSmallsizeSmall如果 size="small"，則套用至根元素的樣式。
    .MuiSlider-thumbthumb套用至滑桿元素的樣式。
    .MuiSlider-thumbColorErrorthumbColorError如果 color="error"，則套用至滑桿元素的樣式。
    .MuiSlider-thumbColorInfothumbColorInfo如果 color="info"，則套用至滑桿元素的樣式。
    .MuiSlider-thumbColorPrimarythumbColorPrimary如果 color="primary"，則套用至滑桿元素的樣式。
    .MuiSlider-thumbColorSecondarythumbColorSecondary如果 color="secondary"，則套用至滑桿元素的樣式。
    .MuiSlider-thumbColorSuccessthumbColorSuccess如果 color="success"，則套用至滑桿元素的樣式。
    .MuiSlider-thumbColorWarningthumbColorWarning如果 color="warning"，則套用至滑桿元素的樣式。
    .MuiSlider-thumbSizeSmallthumbSizeSmall如果 size="small"，則套用至滑桿元素的樣式。
    .MuiSlider-tracktrack套用至軌跡元素的樣式。
    .MuiSlider-trackFalsetrackFalse如果 track={false}，則套用至根元素的樣式。
    .MuiSlider-trackInvertedtrackInverted如果 track="inverted"，則套用至根元素的樣式。
    .MuiSlider-valueLabelvalueLabel套用至滑桿標籤元素的樣式。
    .MuiSlider-valueLabelCirclevalueLabelCircle套用至滑桿標籤圓形元素的樣式。
    .MuiSlider-valueLabelLabelvalueLabelLabel套用至滑桿標籤標籤元素的樣式。
    .MuiSlider-valueLabelOpenvalueLabelOpen如果滑桿標籤元素處於開啟狀態，則套用至滑桿標籤元素的樣式。
    .MuiSlider-verticalvertical如果 orientation="vertical"，則套用至根元素的樣式。

    您可以使用以下自訂選項之一覆寫元件的樣式

    原始碼

    如果您在此頁面中找不到資訊，請考慮查看元件的實作程式碼以取得更多詳細資訊。