🔒 此组件被锁定为 私有 API。我们目前不建议在 Gutenberg 项目之外使用此组件。
DateCalendar 是一个 React 组件，为单个日期选择提供可定制的日历界面。
该组件在设计时考虑了无障碍性，并遵循日历小部件的 ARIA 最佳实践。它提供键盘导航、屏幕阅读器支持以及用于国际化的可定制标签。
用法示例
import { DateCalendar } from '@wordpress/components';
function MyComponent() {
const [ selected, setSelected ] = useState< Date >( new Date() );
return <DateCalendar selected={ selected } onSelect={ setSelected } />;
}
Props
这些 props 在单日期和日期范围日历模式下均适用。
required
- 类型：
boolean - 是否必需：否
- 默认值：
false
表示是否必须选择日期。当值为 true 时，始终需要选择一个日期。
selected
- 类型：
Date | undefined | null - 是否必需：否
已选中的日期。
onSelect
- 类型：
(selected: Date | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void - 是否必需：否
选中某日时触发的事件处理程序。
defaultSelected
- 类型：
Date - 是否必需：否
默认选中的日期（用于非受控模式）。
defaultMonth
- 类型：
Date - 是否必需：否
- 默认值：当前月份
日历视图中显示的初始月份（非受控模式）。
month
- 类型：
Date - 是否必需：否
日历视图中显示的月份（受控模式）。与 onMonthChange 配合使用以编程方式更改月份。
numberOfMonths
- 类型：
number - 是否必需：否
- 默认值：
1
一次性显示的月份数量。
startMonth
- 类型：
Date - 是否必需：否
月份导航的最早起始月份。
endMonth
- 类型：
Date - 是否必需：否
月份导航的最晚结束月份。
autoFocus
- 类型：
boolean - 是否必需：否
聚焦第一个选中的日期（如果设置）或今天的日期（如果未禁用）。当需要在用户操作后聚焦日历时使用此 prop（例如打开包含日历的对话框）。
disabled
- 类型：
Matcher | Matcher[] | undefined - 是否必需：否
指定哪些日期被禁用。传入 true 将禁用所有日期。有关更多详细信息，请参阅Matcher Types部分。
disableNavigation
- 类型：
boolean - 是否必需：否
禁用导航按钮。
labels
- 类型：
object - 是否必需：否
使用自定义标签进行国际化。所有标签均为可选，并具有合理的默认值：
{
labelNav?: () => string; // 导航工具栏标签
labelGrid?: (date: Date) => string; // 月份网格标签（默认："LLLL y"）
labelGridcell?: (date: Date, modifiers?: Modifiers) => string; // 网格单元格标签
labelNext?: (month: Date | undefined) => string; // 下月按钮标签
labelPrevious?: (month: Date | undefined) => string; // 上月按钮标签
labelDayButton?: (date: Date, modifiers?: Modifiers) => string; // 日期按钮标签
labelWeekday?: (date: Date) => string; // 星期标签
}
重要提示：为了获得正确的本地化体验，使用者应确保用于翻译标签的语言环境与 locale prop 保持一致。
locale
- 类型：
Locale - 是否必需：否
- 默认值：
@date-fns/locale中的enUS
用于本地化日期的语言环境对象。传递来自 @date-fns/locale 的语言环境以本地化日历。
重要提示：为了获得正确的本地化体验，使用者应确保用于翻译标签的语言环境与 locale prop 保持一致。
weekStartsOn
- 类型：
0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined - 是否必需：否
- 默认值：基于
localeprop
一周中第一天的索引（0 – 星期日）。覆盖语言环境的设置。
onMonthChange
- 类型：
(month: Date) => void - 是否必需：否
用户在月份之间导航时触发的事件。
timeZone
- 类型：
string - 是否必需：否
日历中使用的时区（IANA 名称或 UTC 偏移量）。可能的值请参阅 Wikipedia。
在处理时区时，请使用本包导出的 TZDate 对象，而不是原生的 Date 对象。
import { DateCalendar, TZDate } from '@wordpress/components';
export function WithTimeZone() {
const timeZone = 'America/New_York';
const [ selected, setSelected ] = useState< Date | undefined >(
new TZDate( 2024, 12, 10, timeZone ) // 使用 `TZDate` 代替 `Date`
);
return (
<DateCalendar
timeZone={ timeZone }
selected={ selected }
onSelect={ setSelected }
/>
);
}
role
- 类型：
'application' | 'dialog' | undefined - 是否必需：否
- 默认值：
'application'
添加到容器元素的 role 属性。
Matcher Types
日历组件使用灵活的匹配系统来确定哪些日期应被禁用或具有特定的修饰符。以下是可用的匹配器类型：
Boolean Matcher
const booleanMatcher: Matcher = true; // 将始终匹配该日期
Date Matcher
const dateMatcher: Matcher = new Date(); // 将匹配今天的日期
Array Matcher
const arrayMatcher: Matcher = [
new Date( 2019, 1, 2 ),
new Date( 2019, 1, 4 ),
]; // 将匹配数组中的日期
Date After Matcher
const afterMatcher: DateAfter = { after: new Date( 2019, 1, 2 ) }; // 将匹配 2019年2月2日之后的日期
Date Before Matcher
const beforeMatcher: DateBefore = { before: new Date( 2019, 1, 2 ) }; // 将匹配 2019年2月2日之前的日期
Date Interval Matcher
const intervalMatcher: DateInterval = {
after: new Date( 2019, 1, 2 ),
before: new Date( 2019, 1, 5 ),
}; // 将匹配 2019年2月2日和2月5日之间的日期（不包含边界）
Date Range Matcher
const rangeMatcher: DateRange = {
from: new Date( 2019, 1, 2 ),
to: new Date( 2019, 1, 5 ),
}; // 将匹配 2019年2月2日和2月5日之间的日期（包含边界）
Day of Week Matcher
const dayOfWeekMatcher: DayOfWeek = { dayOfWeek: 0 }; // 将匹配星期日
const weekendMatcher: DayOfWeek = { dayOfWeek: [ 0, 6 ] }; // 将匹配周末
Function Matcher
const functionMatcher: Matcher = ( day: Date ) => {
return day.getMonth() === 2; // 当月份为三月时匹配
};