组件生命周期

此页面解释了何时调用 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 属性来扩展日期字段组件，该属性是 onChange 的防抖版本。您可以在专用文档部分中找到有关 onAccept 属性的更多信息。

防抖字段

onChange

onAccept