日期選擇器

日期選擇器元件讓使用者可以選擇日期。

基本用法

基本日期選擇器

<DatePicker label="Basic date picker" />

<DatePicker label="Basic date picker" />

按下 Enter 鍵開始編輯

元件組成

此元件使用 DateField 進行鍵盤編輯，並使用 DateCalendar 進行檢視編輯。

查看其文件頁面以獲取更多資訊

您可以在專用的 API 頁面上查看組合元件的可用 props。某些 DateField props 在 Picker 元件上不可用，您可以使用 slotProps.field 將它們傳遞到欄位。

非受控值 vs. 受控值

元件的值可以是受控或非受控的。

非受控選擇器

受控選擇器

<DatePicker label="Uncontrolled picker" defaultValue={dayjs('2022-04-17')} />
<DatePicker
  label="Controlled picker"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

<DatePicker label="Uncontrolled picker" defaultValue={dayjs('2022-04-17')} />
<DatePicker
  label="Controlled picker"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

按下 Enter 鍵開始編輯

可用元件

此元件有四種變體可用

DesktopDatePicker 元件最適合滑鼠裝置和大型螢幕。它在彈出視窗中呈現檢視，並允許直接在欄位內編輯值。
MobileDatePicker 元件最適合觸控裝置和小螢幕。它在模態視窗中呈現檢視，並且不允許直接在欄位內編輯值。
DatePicker 元件根據其運行的裝置呈現 DesktopDatePicker 或 MobileDatePicker。
StaticDatePicker 元件在沒有彈出視窗/模態視窗和欄位的情況下呈現。

桌面變體

行動變體

響應式變體

靜態變體

2022年四月

日一二三四五六

<DemoItem label="Desktop variant">
  <DesktopDatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Mobile variant">
  <MobileDatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Responsive variant">
  <DatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Static variant">
  <StaticDatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>

<DemoItem label="Desktop variant">
  <DesktopDatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Mobile variant">
  <MobileDatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Responsive variant">
  <DatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Static variant">
  <StaticDatePicker defaultValue={dayjs('2022-04-17')} />
</DemoItem>

按下 Enter 鍵開始編輯

預設情況下，如果媒體查詢 @media (pointer: fine) 匹配，DatePicker 元件會呈現桌面版本。這可以使用 desktopModeMediaQuery prop 進行自訂。

表單 props

元件可以被禁用或設為唯讀。

已禁用

唯讀

名稱

<DatePicker label="disabled" disabled />
<DatePicker label="readOnly" readOnly />
<DatePicker label="name" name="startDate" />

<DatePicker label="disabled" disabled />
<DatePicker label="readOnly" readOnly />
<DatePicker label="name" name="startDate" />

按下 Enter 鍵開始編輯

檢視

此元件支援三種檢視：day、month 和 year。

預設情況下，day 和 year 檢視已啟用。使用 views prop 更改此行為

"year"、"month" 和 "day"

"day"

"month" 和 "year"

<DatePicker
  label={'"year", "month" and "day"'}
  views={['year', 'month', 'day']}
/>
<DatePicker label={'"day"'} views={['day']} />
<DatePicker label={'"month" and "year"'} views={['month', 'year']} />

<DatePicker
  label={'"year", "month" and "day"'}
  views={['year', 'month', 'day']}
/>
<DatePicker label={'"day"'} views={['day']} />
<DatePicker label={'"month" and "year"'} views={['month', 'year']} />

按下 Enter 鍵開始編輯

預設情況下，元件在掛載時呈現 day 檢視。使用 openTo prop 更改此行為

"year"

"month"

<DatePicker label={'"year"'} openTo="year" />
<DatePicker
  label={'"month"'}
  openTo="month"
  views={['year', 'month', 'day']}
/>

<DatePicker label={'"year"'} openTo="year" />
<DatePicker
  label={'"month"'}
  openTo="month"
  views={['year', 'month', 'day']}
/>

按下 Enter 鍵開始編輯

年份順序

預設情況下，年份以升序顯示，按時間順序從最小年份到最大年份。將 yearsOrder prop 設置為 desc 以按降序顯示年份。

降序年份

<DatePicker
  label="Years in descending order"
  maxDate={currentYear}
  openTo="year"
  views={['year', 'month']}
  yearsOrder="desc"
  sx={{ minWidth: 250 }}
/>

<DatePicker
  label="Years in descending order"
  maxDate={currentYear}
  openTo="year"
  views={['year', 'month']}
  yearsOrder="desc"
  sx={{ minWidth: 250 }}
/>

按下 Enter 鍵開始編輯

橫向方向

預設情況下，日期選擇器元件會根據 window.orientation 值自動設置方向。您可以使用 orientation prop 強制指定方向

2025年三月

日一二三四五六

<StaticDatePicker orientation="landscape" />

<StaticDatePicker orientation="landscape" />

按下 Enter 鍵開始編輯

輔助文字

您可以顯示帶有接受日期格式的輔助文字

輔助文字範例

MM/DD/YYYY

<DatePicker
  label="Helper text example"
  slotProps={{
    textField: {
      helperText: 'MM/DD/YYYY',
    },
  }}
/>

<DatePicker
  label="Helper text example"
  slotProps={{
    textField: {
      helperText: 'MM/DD/YYYY',
    },
  }}
/>

按下 Enter 鍵開始編輯

清除值

您可以啟用可清除行為

DesktopDatePicker

本地化

請參閱日期格式和本地化以及已翻譯元件的文件頁面以獲取更多詳細資訊。

驗證

請參閱驗證文件頁面以獲取更多詳細資訊。

自訂

您可以查看多個關於如何自訂日期選擇器及其子元件的範例。

2025年三月

#日一二三四五六

API

請參閱下面的文件，以獲取此處提及的元件可用的所有 props 和類別的完整參考。

日期選擇器

週日, 4月 17

––

––