滑桿

滑桿是一種 UI 元素，可讓使用者沿著一個長條選取單一值或值範圍。

滑桿 API

Import

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

透過閱讀這篇關於最小化套件大小的指南，來了解它們之間的差異。

Props

原生元件的 Props 也可使用。

名稱	類型	預設值	描述
aria-label	string	-	滑桿的標籤。
aria-labelledby	string	-	包含滑桿標籤的元素的 id。
aria-valuetext	string	-	一個字串值，為滑桿的目前值提供使用者友善的名稱。
defaultValue	Array<number> \| number	-	預設值。當元件不受控制時使用。
disabled	bool	false	若為 `true`，則元件為停用狀態。
disableSwap	bool	false	若為 `true`，當拖曳另一個拇指時，在拇指上方移動指標時，作用中的拇指不會交換。
getAriaLabel	func	-	接受一個函式，該函式傳回一個字串值，為滑桿的拇指標籤提供使用者友善的名稱。這對於螢幕閱讀器使用者來說非常重要。簽名：`function(index: number) => string` `index` 要格式化的拇指標籤的索引。
getAriaValueText	func	-	接受一個函式，該函式傳回一個字串值，為滑桿的目前值提供使用者友善的名稱。這對於螢幕閱讀器使用者來說非常重要。簽名：`function(value: number, index: number) => string` `value` 要格式化的拇指標籤的值。 `index` 要格式化的拇指標籤的索引。
isRtl	bool	false	若為 `true`，Slider 將會以從右到左的方式呈現 (最低值在右手邊)。
marks	Array<{ label?: node, value: number }> \| bool	false	標記指示使用者可以將滑桿移動到的預定值。若為 `true`，則標記會根據 `step` prop 的值間隔排列。若為陣列，則應包含具有 `value` 和可選 `label` 鍵的物件。
max	number	100	滑桿允許的最大值。不應等於最小值。
min	number	0	滑桿允許的最小值。不應等於最大值。
name	string	-	隱藏 `input` 元素的 Name 屬性。
onChange	func	-	當滑桿的值變更時觸發的回呼函式。簽名：`function(event: Event, value: number \| Array, activeThumb: number) => void` `event` 回呼的事件來源。您可以透過存取 `event.target.value` (any) 來提取新值。警告：這是一個通用事件，而不是變更事件。 `value` 新值。 `activeThumb` 目前移動的拇指的索引。
onChangeCommitted	func	-	當 `mouseup` 被觸發時觸發的回呼函式。簽名：`function(event: React.SyntheticEvent \| Event, value: number \| Array) => void` `event` 回呼的事件來源。警告：這是一個通用事件，而不是變更事件。 `value` 新值。
orientation	'horizontal' \| 'vertical'	'horizontal'	元件方向。
scale	func	function Identity(x) { return x; }	一個轉換函式，用於變更滑桿的比例。簽名：`function(x: any) => any`
shiftStep	number	10	當使用 Page Up/Page Down 或 Shift + 向上/向下箭頭時，滑桿可以逐步瀏覽值的粒度。
slotProps	{ input?: func \| object, mark?: func \| object, markLabel?: func \| object, rail?: func \| object, root?: func \| object, thumb?: func \| object, track?: func \| object, valueLabel?: any \| func }	{}	用於滑桿內部每個 slot 的 props。
slots	{ input?: elementType, mark?: elementType, markLabel?: elementType, rail?: elementType, root?: elementType, thumb?: elementType, track?: elementType, valueLabel?: elementType }	{}	用於滑桿內部每個 slot 的元件。可以是字串 (使用 HTML 元素) 或元件。請參閱下方的 Slots API 以取得更多詳細資訊。
step	number	1	滑桿可以逐步瀏覽值的粒度。(「離散」滑桿。) `min` prop 作為有效值的起點。我們建議 (max - min) 可以被 step 整除。當 step 為 `null` 時，拇指只能滑到使用 `marks` prop 提供的標記上。
tabIndex	number	-	隱藏 `input` 元素的 Tab index 屬性。
track	'inverted' \| 'normal' \| false	'normal'	軌跡呈現方式 `normal` 軌跡將呈現一個代表滑桿值的長條。 `inverted` 軌跡將呈現一個代表剩餘滑桿值的長條。 `false` 軌跡將不呈現長條。
value	Array<number> \| number	-	滑桿的值。對於範圍滑桿，請提供包含兩個值的陣列。
valueLabelFormat	func \| string	function Identity(x) { return x; }	值標籤值的格式化函式。當提供函式時，它應具有以下簽名 - {number} value 要格式化的值標籤的值 - {number} index 要格式化的值標籤的索引

ref 會轉發到根元素。

Slots

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

Slot 名稱	Class name	預設元件	描述
root	.base-Slider-root	`'span'`	呈現 root 的元件。
track	.base-Slider-track	`'span'`	呈現軌跡的元件。
rail	.base-Slider-rail	`'span'`	呈現軌道的元件。
thumb	.base-Slider-thumb	`'span'`	呈現拇指的元件。
mark	.base-Slider-mark	`'span'`	呈現標記的元件。
markLabel	.base-Slider-markLabel	`'span'`	呈現標記標籤的元件。
valueLabel			呈現值標籤的元件。
input		`'input'`	呈現輸入框的元件。

CSS classes

這些 class name 對於使用 CSS 設定樣式很有用。當觸發特定狀態時，它們會套用至元件的 slot。

Class name	描述
.base--active	如果拇指元素處於作用中狀態，則套用至該元素的狀態 class。
.base--disabled	如果 `disabled={true}`，則套用至 root 和拇指元素的狀態 class。
.base--focusVisible	如果拇指元素取得鍵盤焦點，則套用至該元素的狀態 class。
.base-Slider-dragging	如果正在拖曳拇指，則套用至 root 的狀態 class。
.base-Slider-markActive	如果標記處於作用中狀態 (取決於值)，則套用至標記元素的 Class name。
.base-Slider-marked	如果 `marks` 有提供至少一個標籤，則套用至 root 元素的 Class name。
.base-Slider-markLabelActive	如果標記標籤處於作用中狀態 (取決於值)，則套用至標記標籤元素的 Class name。
.base-Slider-trackFalse	如果 `track={false}`，則套用至 root 元素的 Class name。
.base-Slider-trackInverted	如果 `track="inverted"`，則套用至 root 元素的 Class name。
.base-Slider-vertical	如果 `orientation="vertical"`，則套用至 root 元素的 Class name。