日期行事曆

日期行事曆元件讓使用者無需任何輸入或彈出視窗/對話框即可選擇日期。

基本用法

2025年3月

日一二三四五六

<DateCalendar />

<DateCalendar />

按下 Enter 鍵開始編輯

非受控與受控值

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

非受控行事曆

2022年4月

日一二三四五六

受控行事曆

2022年4月

日一二三四五六

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

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

按下 Enter 鍵開始編輯

表單屬性

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

停用

2022年4月

日一二三四五六

唯讀

2022年4月

日一二三四五六

<DemoItem label="disabled">
  <DateCalendar defaultValue={dayjs('2022-04-17')} disabled />
</DemoItem>
<DemoItem label="readOnly">
  <DateCalendar defaultValue={dayjs('2022-04-17')} readOnly />
</DemoItem>

<DemoItem label="disabled">
  <DateCalendar defaultValue={dayjs('2022-04-17')} disabled />
</DemoItem>
<DemoItem label="readOnly">
  <DateCalendar defaultValue={dayjs('2022-04-17')} readOnly />
</DemoItem>

按下 Enter 鍵開始編輯

檢視

元件可以包含三種檢視：day、month 和 year。預設情況下，僅啟用 day 和 year 檢視。

您可以使用 views 屬性自訂啟用的檢視。檢視將按照它們在 views 陣列中包含的順序顯示。

"year"、"month" 和 "day"

2022年4月

日一二三四五六

"day"

2025年3月

日一二三四五六

"month" 和 "year"

2022年4月

<DemoItem label={'"year", "month" and "day"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['year', 'month', 'day']}
  />
</DemoItem>
<DemoItem label={'"day"'}>
  <DateCalendar views={['day']} />
</DemoItem>
<DemoItem label={'"month" and "year"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['month', 'year']}
    openTo="month"
  />
</DemoItem>

<DemoItem label={'"year", "month" and "day"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['year', 'month', 'day']}
  />
</DemoItem>
<DemoItem label={'"day"'}>
  <DateCalendar views={['day']} />
</DemoItem>
<DemoItem label={'"month" and "year"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['month', 'year']}
    openTo="month"
  />
</DemoItem>

按下 Enter 鍵開始編輯

選擇初始年份/月份

如果 value 或 defaultValue 包含有效的日期，則此日期將用於選擇在 day 檢視中呈現的月份以及在 month 檢視中呈現的年份。如果 value 和 defaultValue 都不包含有效日期，則元件將嘗試尋找符合驗證規則的月份和年份。

您可以使用 referenceDate 覆寫此日期，在以下範例中，即使沒有視覺化選取日期，行事曆也會呈現 2022 年 4 月

2022年4月

日一二三四五六

<DateCalendar
  referenceDate={dayjs('2022-04-17')}
  views={['year', 'month', 'day']}
/>

<DateCalendar
  referenceDate={dayjs('2022-04-17')}
  views={['year', 'month', 'day']}
/>

按下 Enter 鍵開始編輯

月份和年份行事曆

如果您只需要 year 檢視或 month 檢視，則可以使用 YearCalendar / MonthCalendar 元件

年份行事曆

月份行事曆

年份順序

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

年份降序

日期檢視自訂

顯示額外天數

若要顯示所顯示週的所有天數，包括當前月份之外的天數，請使用 showDaysOutsideCurrentMonth。

預設情況下，僅顯示當前月份的週，但您可以使用 fixedWeekNumber 屬性提供要顯示的週總數。對於公曆來說，此值通常設定為 6，因為月份顯示可能在 4 到 6 週之間變化。

2025年3月

日一二三四五六

<DateCalendar showDaysOutsideCurrentMonth fixedWeekNumber={6} />

<DateCalendar showDaysOutsideCurrentMonth fixedWeekNumber={6} />

按下 Enter 鍵開始編輯

顯示週數

若要顯示週數，請使用 displayWeekNumber。您可以使用本地化鍵 localeText.calendarWeekNumberHeaderText 自訂行事曆週標題。您也可以使用本地化鍵 localeText.calendarWeekNumberText 的回呼來自訂呈現為行事曆週數的內容。

2025年3月

週日一二三四五六

10.

11.

12.

13.

14.

<DateCalendar displayWeekNumber />

<DateCalendar displayWeekNumber />

按下 Enter 鍵開始編輯

週選擇器

您可以使用 day 元件插槽選取整個星期

2022年4月

週日一二三四五六

<DateCalendar
  value={value}
  onChange={(newValue) => setValue(newValue)}
  showDaysOutsideCurrentMonth
  displayWeekNumber
  slots={{ day: Day }}
  slotProps={{
    day: (ownerState) =>
      ({
        selectedDay: value,
        hoveredDay,
        onPointerEnter: () => setHoveredDay(ownerState.day),
        onPointerLeave: () => setHoveredDay(null),
      }) as any,
  }}
/>

<DateCalendar
  value={value}
  onChange={(newValue) => setValue(newValue)}
  showDaysOutsideCurrentMonth
  displayWeekNumber
  slots={{ day: Day }}
  slotProps={{
    day: (ownerState) =>
      ({
        selectedDay: value,
        hoveredDay,
        onPointerEnter: () => setHoveredDay(ownerState.day),
        onPointerLeave: () => setHoveredDay(null),
      }) as any,
  }}
/>

按下 Enter 鍵開始編輯

動態資料

有時可能需要在行事曆中直接顯示額外資訊。以下示範展示如何根據伺服器端資料在某一天添加徽章

2022年4月

日一二三四五六

🌚🌚

🌚

<DateCalendar
  defaultValue={initialValue}
  loading={isLoading}
  onMonthChange={handleMonthChange}
  renderLoading={() => <DayCalendarSkeleton />}
  slots={{
    day: ServerDay,
  }}
  slotProps={{
    day: {
      highlightedDays,
    } as any,
  }}
/>

<DateCalendar
  defaultValue={initialValue}
  loading={isLoading}
  onMonthChange={handleMonthChange}
  renderLoading={() => <DayCalendarSkeleton />}
  slots={{
    day: ServerDay,
  }}
  slotProps={{
    day: {
      highlightedDays,
    } as any,
  }}
/>

按下 Enter 鍵開始編輯