欄位元件

欄位元件讓使用者可以使用鍵盤輸入日期和時間值，並進行精細的鍵盤導航。

簡介

這些欄位是 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 範例中推薦了這種方法，原生 date HTML 輸入元素在底層也使用了這種方法。

日期欄位

MM/DD/YYYY

搭配 `slotProps.field` 使用

當使用 slotProps.field 將 props 傳遞到您的欄位元件時，欄位會消耗一些 props（例如：shouldRespectLeadingZeros），並將其餘的轉發到 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',
        },
      },
    },
  },
});

進階

什麼是區段？

在欄位元件中，日期分為多個區段，每個區段負責編輯日期符記。例如，如果傳遞到欄位的格式為 MM/DD/YYYY，則欄位將建立 3 個區段

month 區段用於符記 MM
day 區段用於符記 DD
year 區段用於符記 YYYY

這些區段是獨立的，在焦點位於 day 區段時按下 向上箭頭 將會為日期增加一天，但永遠不會更改月份或年份。

控制選取的區段

使用 selectedSections 和 onSelectedSectionsChange props 來控制目前選取了哪些區段。

此 prop 接受以下格式

如果提供數字，則將選取此索引處的區段。
如果提供 "all"，則將選取所有區段。
如果提供具有 startIndex 和 endIndex 欄位的物件，則將選取這兩個索引之間的區段。
如果提供 FieldSectionType 類型的字串，則將選取具有該名稱的第一個區段。
如果提供 null，則不會選取任何區段

搭配多個輸入範圍欄位使用

對於多個輸入範圍欄位，您只需確保在更新選取的區段之前，正確的輸入已聚焦即可。否則，區段可能會在錯誤的輸入上選取。

開始

結束

–

搭配單一輸入範圍欄位使用

對於單一輸入範圍欄位，您將無法使用區段名稱來選取單一區段，因為每個區段在開始日期和結束日期中都存在。相反地，您可以使用索引傳遞區段，並使用 unstableFieldRef prop 來存取區段的完整清單

開始

結束

可清除行為

您可以使用 clearable prop 在欄位上啟用清除行為。您也可以使用 onClear 回呼 prop 新增事件處理常式。

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 和類別的完整參考。