字段组件

字段组件允许用户通过键盘输入日期和时间值，并提供精细的键盘导航。

介绍

这些字段是 React 组件，允许您通过键盘输入日期或时间，而无需使用任何弹出窗口或模态 UI。它们通过箭头键提供精细的导航，并支持本地化和验证等高级行为。

编辑单个元素的字段

DateField

TimeField

DateTimeField

编辑范围的字段

所有用于编辑范围的字段都提供单输入版本和多输入版本。

MultiInputDateRangeField

–

SingleInputDateRangeField

MultiInputTimeRangeField

–

SingleInputTimeRangeField

MultiInputDateTimeRangeField

–

SingleInputDateTimeRangeField

无障碍 DOM 结构

默认情况下，字段的 DOM 结构由一个 <input /> 组成，它保存组件的整个值。不幸的是，它存在无法解决的无障碍访问限制。

从 v7.x 版本开始，我们引入了一种新的 DOM 结构，允许字段组件在各个部分设置 aria 属性，从而为屏幕阅读器提供更好的体验。您可以使用 enableAccessibleFieldDOMStructure 属性在任何字段或选择器组件上选择加入新的实验性 DOM 结构。

从 v8.x 版本开始，新的 DOM 结构将成为所有字段的默认结构。

<DateField enableAccessibleFieldDOMStructure />
<DatePicker enableAccessibleFieldDOMStructure />
<DateRangePicker enableAccessibleFieldDOMStructure />

W3C ARIA 示例推荐使用这种方法，原生日期 HTML 输入元素也在底层使用了这种方法。

日期字段

MM/DD/YYYY

与 `slotProps.field` 一起使用

当使用 slotProps.field 将 props 传递给您的字段组件时，该字段会消耗一些 props（例如：shouldRespectLeadingZeros），并将其余 props 转发到 TextField。

对于字段消耗的 props，在两种 DOM 结构下，行为应保持完全相同。

以下两个组件都将遵守数字部分的开头零

<DatePicker
  slotProps={{ field: { shouldRespectLeadingZeros: true } }}
  enableAccessibleFieldDOMStructure
/>
<DatePicker
  slotProps={{ field: { shouldRespectLeadingZeros: true } }}
/>

对于转发到 TextField 的 props，您可以查看下一节，了解迁移如何影响它们。

以下两个组件都将渲染小尺寸 UI

<DatePicker
  slotProps={{ field: { size: 'small' } }}
  enableAccessibleFieldDOMStructure
/>
<DatePicker
  slotProps={{ field: { size: 'small' } }}
/>

与 `slotProps.textField` 一起使用

如果您将 props 传递给 slotProps.textField，这些 props 现在将由 PickersTextField 接收，并且应保持与以前相同的工作方式。

以下两个组件都将渲染小尺寸 UI

<DatePicker
  slotProps={{ textField: { size: 'small' } }}
  enableAccessibleFieldDOMStructure
/>
<DatePicker
  slotProps={{ textField: { size: 'small' } }}
/>

与 `slots.field` 一起使用

如果您将自定义字段组件传递给您的选择器，则需要创建一个新的组件，该组件使用无障碍 DOM 结构。这个新组件将需要使用 PickersSectionList 组件而不是 <input /> HTML 元素。

您可以查看自定义 PickersTextField 以获得具体示例。

与 `slots.textField` 一起使用

如果您将自定义 TextField 组件传递给您的字段和选择器，则需要创建一个新的组件，该组件使用无障碍 DOM 结构。

您可以查看Material PickersTextField 部分的第二个演示，以获得具体示例。

与主题一起使用

如果您使用主题自定义 MuiTextField，则需要将相同的配置传递给 MuiPickersTextField

const theme = createTheme({
  components: {
    MuiTextField: {
      defaultProps: {
        variant: 'outlined',
      },
      styleOverrides: {
        root: {
          '& .MuiInputLabel-outlined.Mui-focused': {
            color: 'red',
          },
        },
      },
    },
    MuiPickersTextField: {
      defaultProps: {
        variant: 'outlined',
      },
      styleOverrides: {
        root: {
          '& .MuiInputLabel-outlined.Mui-focused': {
            color: 'red',
          },
        },
      },
    },
  },
});

如果您使用主题自定义 MuiInput、MuiOutlinedInput 或 MuiFilledInput，则需要将相同的配置传递给 MuiPickersInput、MuiPickersOutlinedInput 或 MuiPickersFilledInput

const theme = createTheme({
  components: {
    // Replace with `MuiOutlinedInput` or `MuiFilledInput` if needed
    MuiInput: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
    // Replace with `MuiPickersOutlinedInput` or `MuiPickersFilledInput` if needed
    MuiPickersInput: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
  },
});

如果您使用主题自定义 MuiInputBase，则需要将相同的配置传递给 MuiPickersInputBase

const theme = createTheme({
  components: {
    MuiInputBase: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
    MuiPickersInputBase: {
      defaultProps: {
        margin: 'dense',
      },
      styleOverrides: {
        root: {
          color: 'red',
        },
      },
    },
  },
});

高级

什么是 section？

在字段组件中，日期被分成几个 section，每个 section 负责编辑一个日期标记。例如，如果传递给字段的格式是 MM/DD/YYYY，则该字段将创建 3 个 section

一个用于标记 MM 的 month section
一个用于标记 DD 的 day section
一个用于标记 YYYY 的 year section

这些 section 是独立的，在聚焦 day section 时按 ArrowUp 键将为日期增加一天，但永远不会更改月份或年份。

控制选定的 section

使用 selectedSections 和 onSelectedSectionsChange props 来控制当前正在选择哪些 section。

此 prop 接受以下格式

如果提供一个数字，则将选择此索引处的 section。
如果提供 "all"，则将选择所有 section。
如果提供具有 startIndex 和 endIndex 字段的对象，则将选择这两个索引之间的 section。
如果提供 FieldSectionType 类型的字符串，则将选择具有该名称的第一个 section。
如果提供 null，则不会选择任何 section

与多输入范围字段一起使用

对于多输入范围字段，您只需确保在更新选定的 section 之前正确的输入已聚焦。否则，section 可能会在错误的输入上被选中。

开始

结束

–

与单输入范围字段一起使用

对于单输入范围字段，您将无法使用 section 名称来选择单个 section，因为每个 section 都同时存在于开始日期和结束日期中。相反，您可以使用 unstableFieldRef 属性传递 section 的索引来访问 section 的完整列表

开始

结束

可清除行为

您可以使用 clearable 属性在字段上启用清除行为。您还可以使用 onClear 回调属性添加事件处理程序。

DateField

您还可以自定义要显示在清除 IconButton 内的图标。

日期字段

日期范围字段

<DateField
  label="Date Field"
  clearable
  slots={{ clearIcon: HighlightOffIcon }}
/>
<SingleInputDateRangeField
  label="Date Range Field"
  clearable
  slots={{ clearIcon: BackspaceIcon }}
/>

<DateField
  label="Date Field"
  clearable
  slots={{ clearIcon: HighlightOffIcon }}
/>
<SingleInputDateRangeField
  label="Date Range Field"
  clearable
  slots={{ clearIcon: BackspaceIcon }}
/>

按 Enter 键开始编辑

API

请参阅下面的文档，以获取此处提及的组件可用的所有 props 和类的完整参考。