數字輸入框
數字輸入元件為使用者提供整數值的欄位，以及增加或減少數值的按鈕。
簡介
數字輸入框是一種 UI 元素，可接受使用者輸入的數值。MUI Base 的數字輸入元件是原生 HTML <input type="number"> 的可自訂替代方案，可解決其原生對應元件的常見可用性問題，例如
- 步進按鈕在不同瀏覽器中的外觀和行為不一致
- 允許某些非數字字元 ('e'、'+'、'-'、'.') 並靜默捨棄其他字元
- 與輔助技術不相容且無障礙功能有限
元件
import { Unstable_NumberInput as NumberInput } from '@mui/base/Unstable_NumberInput';
以下範例展示了如何建立數字輸入元件、套用一些樣式，以及使用 onChange 屬性將最新值寫入狀態變數
結構
MUI Base 數字輸入元件由四個插槽組成
root：一個外部<div>，包含其他內部插槽input：一個<input>元素incrementButton：一個用於增加值的<button>decrementButton：一個用於減少值的<button>
<div class="base-NumberInput-root">
<button class="base-NumberInput-decrementButton" />
<button class="base-NumberInput-incrementButton" />
<input class="base-NumberInput-input" />
</div>
自訂結構
使用 slots 屬性來覆寫根插槽或任何內部插槽
<NumberInput
slots={{
root: 'aside',
incrementButton: CustomButton,
decrementButton: CustomButton,
}}
/>
使用 slotProps 屬性將自訂屬性傳遞給內部插槽。以下程式碼片段
- 將一個名為
my-num-input的 CSS 類別套用到輸入插槽 - 將
direction屬性傳遞給增加和減少按鈕插槽中的CustomButton元件
<NumberInput
slotProps={{
input: { className: 'my-num-input' },
incrementButton: { direction: 'UP' },
decrementButton: { direction: 'DOWN' },
}}
/>
Hook
import { unstable_useNumberInput as useNumberInput } from '@mui/base/unstable_useNumberInput';
useNumberInput Hook 讓您可以將數字輸入的功能應用於完全自訂的元件。它會傳回要放置在自訂元件上的屬性，以及代表元件內部狀態的欄位。
這是一個使用 useNumberInput Hook 和所有必要屬性建構的自訂元件範例
這是一個使用 Hook 的「精簡」數字輸入元件範例，該元件僅包含步進按鈕。在此範例中，onChange 用於將元件的最新值寫入狀態變數。
Current value:
自訂
最小值和最大值
使用 min 和 max 屬性定義可接受值的範圍。如果您只定義其中一個，則範圍的另一端將是開放式的。
// accepts any value:
<NumberInput />
// only accepts values between -10 and 10:
<NumberInput min={-10} max={10} />
// only accepts values greater than 0:
<NumberInput min={0} />
以下範例展示了一個可接受範圍為 1 到 99 的數字輸入框
增量步進
使用 step 屬性定義增加或減少時數值變化的粒度。例如，如果 min={0} 且 step={2}，則元件的有效值將為 0、2、4 等，因為該值只能以 2 的增量更改。
// valid values: 0, 2, 4, 6, 8...
<NumberInput min={0} step={2} />
當輸入欄位處於焦點時，您可以輸入超出有效範圍的值。一旦輸入欄位失去焦點，該值將根據 min、max 和 step 進行箝制。
Shift 鍵倍數
在與步進按鈕互動時，按住 Shift 鍵會將倍數（預設為 10 倍）應用於每個步進的值變化。
您可以使用 shiftMultiplier 屬性自訂此行為。在以下程式碼片段中，如果在點擊增加按鈕時按住 Shift 鍵，則值將從 0 變為 5、10，依此類推。
<NumberInput min={0} step={1} shiftMultiplier={5} />
事件
數字輸入元件和 Hook 提供兩個屬性 – onChange 和 onInputChange – 它們接受當元件的值變更時的事件處理常式。
onChange
onChange 接受一個自訂事件處理常式，該常式使用兩個參數呼叫：底層事件和最新的「箝制」值。
onChange: (
event: React.FocusEvent<HTMLInputElement> | React.PointerEvent | React.KeyboardEvent,
value: number | undefined,
) => void;
當 <input> 元素失去焦點且值已變更時，或當步進按鈕被點擊時，會呼叫它。這是值根據min、max 或 step 屬性箝制之後。
// ✅ Works
<NumberInput
onChange={(event, newValue) => console.log(`${event.type} event: the new value is ${newValue}`)}
/>
// ❌ Doesn't work
<NumberInput
slotProps={{
input: {
// expects a native input change event handler, newValue is always undefined
onChange: (event, newValue) => { ... },
},
}}
/>
onInputChange
onInputChange 接受一個原生輸入變更處理常式，該常式會傳遞到 <input> 元素
onInputChange: React.ChangeEventHandler<HTMLInputElement>;
每當文字框的值變更時，都會呼叫它 – 例如，在每次鍵入文字框的擊鍵時，在應用箝制之前。
換句話說，event.target.value 有可能包含超出範圍的值或非數字字元。
// ✅ Works
<NumberInput
onInputChange={(event) => console.log(`the input value is: ${event.target.value}`)}
/>
// ✅ Works
<NumberInput
slotProps={{
input: {
// this exactly the same as onInputChange above
onChange: (event) => console.log(`the input value is: ${event.target.value}`),
},
}}
/>
// ❌ Doesn't work
<NumberInput
slotProps={{
input: {
// This will throw "unknown event handler"
onInputChange: () => {},
},
}}
/>
裝飾
您可以使用 startAdornment 和 endAdornment 屬性，分別為數字輸入框新增前綴或後綴。裝飾可用於在值旁邊顯示度量單位，例如重量或貨幣。