組件生命週期

本頁說明了 onChange、onAccept 和 onClose 回呼函式何時被呼叫。

簡單欄位的生命週期

欄位組件具有控制可見值的內部狀態。

只有在以下情況，才會呼叫 onChange 回呼函式

使用者填寫空欄位的一個部分。值等於 Invalid date。
使用者完成欄位的所有部分。值反映該欄位。
使用者清除已完成欄位的一個部分。值等於 Invalid date。
使用者清除欄位的所有部分。值等於 null。

以下範例顯示 onChange 收到的最後一個值。

值null

範圍欄位的生命週期

在範圍欄位（SingleInputDateRangeField / MultiInputDateRangeField / ... ）上，如果您正在修改的日期符合上述條件之一，則會呼叫 onChange，而與另一個日期的狀態無關。

以下範例顯示 onChange 收到的最後一個值。請注意，即使結束日期為空或部分填寫，更改開始日期部分的值也會呼叫 onChange。

值 04/17/2022 – null

選擇器的生命週期：「onClose」

何時呼叫「onClose」？

當最後一個視圖完成時

當在最後一個視圖中進行選擇時，只有當 closeOnSelect 屬性等於 true 時，才會呼叫 onClose。預設情況下，在桌面上設定為 true，在行動裝置上設定為 false。

以下是一些範例

```
<DesktopDatePicker />
```
- 預設 views 屬性：['year', 'day']
- 預設 closeOnSelect 屬性：true
行為： 選擇日期時，選擇器將會關閉。
```
<DesktopDatePicker closeOnSelect={false} />
```
- 預設 views 屬性：['year', 'day']
- 明確的 closeOnSelect 屬性：false
行為： 選擇日期時，選擇器不會關閉。使用者必須點擊確認動作才能關閉它。
如果您想在桌面選擇器上將 closeOnSelect 設定為 false，您應該考慮啟用動作列，以允許使用者驗證值
```
<DesktopDatePicker
  closeOnSelect={false}
  slotProps={{ actionBar: { actions: ['cancel', 'accept'] } }}
/>
```
```
<MobileDatePicker />
```
- 預設 views 屬性：['year', 'day']
- 預設 closeOnSelect 屬性：false
行為： 選擇日期時，選擇器不會關閉。使用者必須點擊確認動作才能關閉它。
```
<DesktopDatePicker views={['day', 'month', 'year']} />
```
- 明確的 views 屬性：['day', 'month', 'year']
- 預設 closeOnSelect 屬性：true
行為： 選擇年份時，選擇器將會關閉。
```
<DesktopTimePicker />
```
- 預設 views 屬性：['hours', 'minutes']（如果地區設定為 12 小時制，則還包括 meridiem 視圖）
- 預設 closeOnSelect 屬性：true
行為： 選擇分鐘或子午線（如果使用 12 小時制時鐘）時，選擇器將會關閉。

當手動關閉選擇器時

按下 Escape 鍵或點擊選擇器外部會關閉選擇器。

當使用動作列選擇值時

點擊動作列的任何內建按鈕都會關閉選擇器。

當選擇快捷鍵時

點擊快捷鍵將會關閉選擇器，除非 changeImportance 屬性已設定為 "set" 而不是預設值 "accept"。您可以在專門的文件章節中找到更多資訊。

選擇器的生命週期：「onChange」

用法

每當目前值變更時，都會呼叫 onChange 回呼函式。

如果您不想監聽中介步驟，請考慮改用 onAccept 屬性。

<DatePicker onChange={(value) => setValue(value)} />

您可以使用傳遞給 onChange 回呼函式的第二個參數，來取得與目前值相關聯的驗證錯誤

<DatePicker
  onChange={(newValue, context) => {
    setValue(value);
    if (context.validationError == null) {
      runSomeLogic();
    }
  }}
/>

何時呼叫「onChange」？

當欄位呼叫「onChange」時

當透過欄位的輸入框編輯值時，選擇器只會重新發布 onChange 回呼函式。請查看專門章節以取得更多資訊。

當使用者與視圖互動時

如果組件是受控的（即：如果它具有 value 屬性），則當要發布的值與目前值不同時，點擊值將會呼叫 onChange（例如：點擊 day 視圖中已選取的日期將不會呼叫 onChange）。

如果組件不受控，則行為相同，除非從未發布任何值，在這種情況下，點擊目前值將會觸發 onChange（例如：如果之前從未呼叫過 onChange，則點擊 day 視圖中已選取的日期將會呼叫 onChange）。

某些視圖可能會決定不針對某些值修改呼叫 onChange。最常見的範例是行動裝置時間視圖（使用 TimeClock 組件）。即使 UI 在每個位置變更時都會更新，onChange 也只會在時鐘指針的拖曳（觸摸）結束時觸發一次。

當使用動作列選擇值時

如果組件是受控的（即：如果它具有 value 屬性），則當要發布的值與目前值不同時，點擊任何內建動作都會呼叫 onChange。

如果組件不受控，則行為相同，但清除、今天和確認動作除外，即使目前值等於要發布的值，如果從未發布任何值，它們也會呼叫 onChange。

當選擇快捷鍵時

點擊快捷鍵將會呼叫 onChange。您可以在專門的文件章節中找到更多資訊。

選擇器的生命週期：「onAccept」

用法

onAccept 回呼函式可讓您取得使用者選取的最終值，而無需關心中介步驟。

<DatePicker onAccept={(value) => sendValueToServer(value)} />

您可以使用傳遞給 onAccept 回呼函式的第二個參數，來取得與目前值相關聯的驗證錯誤

<DatePicker
  onAccept={(newValue, context) => {
    if (context.validationError == null) {
      runSomeLogic();
    }
  }}
/>

何時呼叫「onAccept」？

當最後一個視圖完成時

當在最後一個視圖中進行選擇時，只有當 closeOnSelect 屬性等於 true 且自上次呼叫 onAccept 以來值已修改時，才會呼叫 onAccept。預設情況下，closeOnSelect 在桌面上設定為 true，在行動裝置上設定為 false。

以下是一些範例

```
<DesktopDatePicker />
```
- 預設 views 屬性：['year', 'day']
- 預設 closeOnSelect 屬性：true
行為： 選擇日期時，選擇器將會呼叫 onAccept。
```
<DesktopDatePicker closeOnSelect={false} />
```
- 預設 views 屬性：['year', 'day']
- 明確的 closeOnSelect 屬性：false
行為： 選擇值時，選擇器不會呼叫 onAccept。
如果您想在桌面選擇器上將 closeOnSelect 設定為 false，您應該考慮啟用動作列，以允許使用者驗證值
```
<DesktopDatePicker
  closeOnSelect={false}
  slotProps={{ actionBar: { actions: ['cancel', 'accept'] } }}
/>
```
```
<DesktopDatePicker views={['day', 'month', 'year']} />
```
- 明確的 views 屬性：['day', 'month', 'year']
- 預設 closeOnSelect 屬性：true
行為： 選擇年份時，選擇器將會呼叫 onAccept。
```
<DesktopTimePicker />
```
- 預設 views 屬性：['hours', 'minutes']（如果地區設定為 12 小時制，則還包括 meridiem 視圖）
- 預設 closeOnSelect 屬性：true
行為： 選擇分鐘或子午線（如果使用 12 小時制時鐘）時，選擇器將會呼叫 onAccept。

當手動關閉選擇器時

當使用者按下 Escape 鍵或點擊選擇器外部時，會使用以下內容呼叫 onAccept

目前值，如果最後一個視圖已完成
上次接受的值，如果最後一個視圖尚未完成

當使用動作列選擇值時

如果組件是受控的（即：如果它具有 value 屬性），則當要發布的值與目前值不同時，點擊任何內建動作都會呼叫 onAccept。

如果組件不受控，則行為相同，但清除、今天和確認動作除外，即使目前值等於要發布的值，如果從未發布任何值，它們也會呼叫 onAccept。

當選擇快捷鍵時

點擊快捷鍵將會呼叫 onAccept，除非 changeImportance 屬性已設定為 "set" 而不是 "accept"。您可以在專門的文件章節中找到更多資訊。

經典情境

桌上型「DatePicker」

受控「DesktopDatePicker」：基本用法

<DesktopDatePicker value={value} onChange={(newValue) => setValue(newValue)} />

動作 1： 開啟選擇器

在 day 視圖上開啟選擇器

動作 2： 點擊日期

觸發 onClose（如果 open 屬性不受控，則關閉選擇器）
觸發 onChange，並帶有選取的日期（保留先前值的時間）
觸發 onAccept，並帶有選取的日期（保留先前值的時間）

受控「DesktopDatePicker」：選擇年份、月份和日期

<DesktopDatePicker
  value={value}
  onChange={(newValue) => setValue(newValue)}
  views={['year', 'month', 'day']}
/>

動作 1： 開啟選擇器

在 day 視圖上開啟選擇器

動作 2： 在標頭上切換到 year 視圖

動作 3： 點擊年份

觸發 onChange，並帶有選取的年份（保留先前值的月份、日期和時間）
移動到 month 視圖

動作 4： 點擊月份

觸發 onChange，並帶有選取的月份（保留先前值的日期和時間）
移動到 day 視圖

動作 4： 點擊日期

觸發 onClose（如果 open 屬性不受控，則關閉選擇器）
觸發 onChange，並帶有選取的日期（保留先前值的時間）
觸發 onAccept，並帶有選取的日期（保留先前值的時間）

行動裝置「DatePicker」

受控「MobileDatePicker」：基本用法

<MobileDatePicker value={value} onChange={(newValue) => setValue(newValue)} />

動作 1： 開啟選擇器

在 day 視圖上開啟選擇器

動作 2： 點擊日期

觸發 onChange，並帶有選取的日期（保留先前值的時間）

動作 3： 點擊確認動作

觸發 onClose（如果 open 屬性不受控，則關閉選擇器）
觸發 onAccept，並帶有選取的日期（保留先前值的時間）

僅針對有效值更新

onChange 回呼函式接收第二個參數（上下文物件），其中包含與目前值相關聯的驗證錯誤。如果您只想在值有效時更新狀態，您可以忽略任何具有非空 validationError 的 onChange 呼叫。

在以下範例中，只有當日期有效且年份為 2022 年時，才會呼叫 onChange

值null

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    value={value}
    onChange={(newValue, context) => {
      if (context.validationError == null) {
        setValue(newValue);
      }
    }}
    minDate={dayjs('2022-01-01')}
    maxDate={dayjs('2022-12-31')}
  />
</LocalizationProvider>
<Typography>Value: {value == null ? 'null' : value.format('L')}</Typography>

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <DatePicker
    value={value}
    onChange={(newValue, context) => {
      if (context.validationError == null) {
        setValue(newValue);
      }
    }}
    minDate={dayjs('2022-01-01')}
    maxDate={dayjs('2022-12-31')}
  />
</LocalizationProvider>
<Typography>Value: {value == null ? 'null' : value.format('L')}</Typography>

按下 Enter 鍵開始編輯

伺服器互動

如果選取的值用於與伺服器互動，您可能想要避免發送所有中介狀態。

尤其是在使用者使用鍵盤方向鍵互動設定日期時。

在這種情況下，建議的 UI 是新增一個按鈕來驗證表單。如果由於某些原因，您需要在使用者未按下驗證按鈕的情況下將資料發送到伺服器，您可以按以下方式對 onChange 進行防抖處理。

以下演示展示如何透過新增 onAccept 屬性來擴展 Date Field 組件，onAccept 屬性是 onChange 的防抖版本。您可以在專門的文件章節中找到有關 onAccept 屬性的更多資訊。

防抖欄位

onChange

onAccept