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

SliderAPI

React Slider 組件的 API 參考文件。了解此匯出模組的 props、CSS 和其他 API。

示範

導入

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

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

Props

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

滑桿的標籤。

aria-valuetextstring-

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

classesobject-

覆寫或擴展應用於組件的樣式。

詳情請參閱下方的 CSS 類別 API。

color'danger'
| 'neutral'
| 'primary'
| 'success'
| 'warning'
| string		'primary'

組件的顏色。它支援適用於此組件的那些主題顏色。

若要了解如何新增自己的顏色，請查看主題組件—擴展顏色。

componentelementType-

用於根節點的組件。可以是字串（使用 HTML 元素）或組件。

defaultValueArray<number>
| number		-

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

disabledboolfalse

如果 true，則組件停用。

disableSwapboolfalse

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

getAriaLabelfunc-

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

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

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

簽名：function(value: number, index: number) => string
  • value 要格式化的拇指標籤的值。
  • index 要格式化的拇指標籤的索引。
isRtlboolfalse

如果 true，Slider 將以從右至左的方式呈現（最小值在右側）。

marksArray<{ label?: node, value: number }>
| bool		false

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

maxnumber100

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

minnumber0

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

namestring-

隱藏 input 元素的 Name 屬性。

onChangefunc-

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

簽名：function(event: Event, value: number | Array, activeThumb: number) => void
  • event 回呼的事件來源。您可以透過存取 event.target.value (any) 來取出新值。警告：這是一般事件，而非變更事件。
  • value 新值。
  • activeThumb 目前移動的拇指的索引。
onChangeCommittedfunc-

當 mouseup 被觸發時觸發的回呼函數。

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

組件方向。

scalefuncfunction Identity(x) { return x; }

一個轉換函數，用於變更滑桿的比例。

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

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

    size'sm'
    | 'md'
    | 'lg'
    | string    		'md'

    組件的大小。它接受 'sm' 和 'lg' 之間的主題值。

    若要了解如何將自訂大小新增至組件，請查看主題組件—擴展大小。

    slotProps{ input?: func
    | object, mark?: func
    | object, markLabel?: func
    | object, rail?: func
    | object, root?: func
    | object, thumb?: func
    | object, track?: func
    | object, valueLabel?: func
    | object }    		{}

    用於內部每個 slot 的 props。

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

    用於內部每個 slot 的組件。

    詳情請參閱下方的 Slots API。

    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'

    track 呈現方式

    • normal track 將呈現一個代表滑桿值的長條。
    • inverted track 將呈現一個代表剩餘滑桿值的長條。
    • false track 將在沒有長條的情況下呈現。
    valueArray<number>
    | number    		-

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

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

    控制何時顯示值標籤

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

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

    variant'outlined'
    | 'plain'
    | 'soft'
    | 'solid'
    | string    		'solid'

    要使用的全域 variant。

    若要了解如何新增自己的 variant，請查看主題組件—擴展 variant。

    ref 會轉發到根元素。

    主題預設 props

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

    Slots

    若要了解如何自訂 slot，請查看覆寫組件結構指南。

    Slot 名稱類別名稱預設組件描述
    root.MuiSlider-root'span'呈現根的組件。
    track.MuiSlider-track'span'呈現 track 的組件。
    rail.MuiSlider-rail'span'呈現 rail 的組件。
    thumb.MuiSlider-thumb'span'呈現 thumb 的組件。
    mark.MuiSlider-mark'span'呈現 mark 的組件。
    markLabel.MuiSlider-markLabel'span'呈現 mark label 的組件。
    valueLabel'span'呈現值標籤的組件。
    input'input'呈現 input 的組件。

    CSS 類別

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

    類別名稱規則名稱描述
    .Mui-active如果拇指元素處於作用中狀態，則套用狀態類別。
    .Mui-disabled如果 disabled={true}，則套用至根和拇指元素的狀態類別。
    .Mui-focusVisible如果鍵盤聚焦，則套用至拇指元素的狀態類別。
    .MuiSlider-dragging拖曳中如果正在拖曳拇指，則套用至根的狀態類別。
    .MuiSlider-markActivemarkActive如果標記處於作用中狀態（取決於值），則套用至標記元素的類別名稱。
    .MuiSlider-marked已標記如果 marks 提供至少一個標籤，則套用至根元素的類別名稱。
    .MuiSlider-markLabelActivemarkLabelActive如果標記標籤處於作用中狀態（取決於值），則套用至標記標籤元素的類別名稱。
    .MuiSlider-trackFalsetrackFalse如果 track={false}，則套用至根元素的類別名稱。
    .MuiSlider-trackInvertedtrackInverted如果 track="inverted"，則套用至根元素的類別名稱。
    .MuiSlider-verticalvertical如果 orientation="vertical"，則套用至根元素的類別名稱。

    您可以使用下列其中一個自訂選項來覆寫組件的樣式

    原始碼

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