日期范围日历

🔒 此组件被锁定为 私有 API。我们目前不建议在 Gutenberg 项目之外使用此组件。

DateRangeCalendar 是一个 React 组件，提供可定制的日历界面用于日期范围选择。

该组件在设计时考虑了无障碍访问，并遵循日历小部件的 ARIA 最佳实践。它提供键盘导航、屏幕阅读器支持以及用于国际化的可定制标签。

用法示例

import { DateRangeCalendar } from '@wordpress/components';

type DateRange = {
    from: Date | undefined;
    to?: Date | undefined;
};

function MyComponent() {
    const [ selected, setSelected ] = useState< DateRange >( {
        from: new Date( date.getFullYear(), date.getMonth(), 1 ),
        to: new Date(),
    } );

    return <DateRangeCalendar selected={ selected } onSelect={ setSelected } />;
}

属性

以下属性在单日期和日期范围日历模式下通用。

required

• 类型：boolean
• 是否必需：否
• 默认值：false

是否必须进行选择。当值为 true 时，必须始终选择一个日期。

selected

• 类型：DateRange | undefined | null
• 是否必需：否

选中的日期范围。DateRange 对象的结构如下：

{
  from: Date | undefined;
  to?: Date | undefined;
}

onSelect

• 类型：(selected: DateRange | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void
• 是否必需：否

选择更改时的事件处理程序。selected 参数将包含新的日期范围。

defaultSelected

• 类型：DateRange
• 是否必需：否

默认选中的范围（用于非受控模式）。

excludeDisabled

• 类型：boolean
• 是否必需：否

当值为 true 时，如果包含禁用的日期，范围将重置。这有助于防止用户选择包含不可用日期的范围。

min

• 类型：number
• 是否必需：否

范围内包含的最少天数。如果用户尝试选择的范围短于此值，选择将被调整以满足最低要求。

max

• 类型：number
• 是否必需：否

范围内包含的最多天数。如果用户尝试选择的范围长于此值，选择将被调整以满足最高要求。

defaultMonth

• 类型：Date
• 是否必需：否
• 默认值：当前月份

日历视图中显示的初始月份（非受控模式）。

month

• 类型：Date
• 是否必需：否

日历视图中显示的月份（受控模式）。与 onMonthChange 配合使用以编程方式更改月份。

numberOfMonths

• 类型：number
• 是否必需：否
• 默认值：1

一次显示的月份数量。

startMonth

• 类型：Date
• 是否必需：否

月份导航开始的最早月份。

endMonth

• 类型：Date
• 是否必需：否

月份导航结束的最新月份。

autoFocus

• 类型：boolean
• 是否必需：否

聚焦第一个选中的日期（如果已设置）或今天的日期（如果未禁用）。当需要在用户操作后聚焦日历时使用此属性（例如打开包含日历的对话框）。

disabled

• 类型：Matcher | Matcher[] | undefined
• 是否必需：否

指定哪些日期被禁用。使用 true 将禁用所有日期。有关更多详细信息，请参阅匹配器类型部分。

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 属性保持一致。

locale

• 类型：Locale
• 是否必需：否
• 默认值：@date-fns/locale 中的 enUS

用于本地化日期的区域设置对象。传递来自 @date-fns/locale 的区域设置以本地化日历。

重要提示：为了获得正确的本地化体验，使用者应确保用于翻译标签的区域设置与 locale 属性保持一致。

weekStartsOn

• 类型：0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
• 是否必需：否
• 默认值：基于 locale 属性

一周中第一天的索引（0 – 星期日）。覆盖区域设置的设置。

onMonthChange

• 类型：(month: Date) => void
• 是否必需：否

用户在月份之间导航时触发的事件。

timeZone

• 类型：string
• 是否必需：否

日历中使用的时区（IANA 名称或 UTC 偏移量）。可能的值请参阅 Wikipedia。

在处理时区时，请使用本包导出的 TZDate 对象，而不是原生的 Date 对象。

import { DateRangeCalendar, TZDate } from '@wordpress/components';

export function WithTimeZone() {
    const timeZone = 'America/New_York';
    const [ selected, setSelected ] = useState< Date | undefined >( {
        from: new TZDate( 2024, 12, 10, timeZone ), // 使用 `TZDate` 代替 `Date`
        to: new TZDate( 2024, 12, 8, timeZone ), // 使用 `TZDate` 代替 `Date`
    } );
    return (
        <DateRangeCalendar
            timeZone={ timeZone }
            selected={ selected }
            onSelect={ setSelected }
        />
    );
}

role

• 类型：'application' | 'dialog' | undefined
• 是否必需：否
• 默认值：'application'

添加到容器元素的 role 属性。

匹配器类型

日历组件使用灵活的匹配系统来确定哪些日期应被禁用或具有特定的修饰符。以下是可用的匹配器类型：

布尔匹配器

const booleanMatcher: Matcher = true; // 将始终匹配该日期

日期匹配器

const dateMatcher: Matcher = new Date(); // 将匹配今天的日期

数组匹配器

const arrayMatcher: Matcher = [
    new Date( 2019, 1, 2 ),
    new Date( 2019, 1, 4 ),
]; // 将匹配数组中的日期

日期之后匹配器

const afterMatcher: DateAfter = { after: new Date( 2019, 1, 2 ) }; // 将匹配 2019 年 2 月 2 日之后的日期

日期之前匹配器

const beforeMatcher: DateBefore = { before: new Date( 2019, 1, 2 ) }; // 将匹配 2019 年 2 月 2 日之前的日期

日期区间匹配器

const intervalMatcher: DateInterval = {
    after: new Date( 2019, 1, 2 ),
    before: new Date( 2019, 1, 5 ),
}; // 将匹配 2019 年 2 月 2 日至 5 日之间的日期（不包含边界）

日期范围匹配器

const rangeMatcher: DateRange = {
    from: new Date( 2019, 1, 2 ),
    to: new Date( 2019, 1, 5 ),
}; // 将匹配 2019 年 2 月 2 日至 5 日之间的日期（包含边界）

星期几匹配器

const dayOfWeekMatcher: DayOfWeek = { dayOfWeek: 0 }; // 将匹配星期日
const weekendMatcher: DayOfWeek = { dayOfWeek: [ 0, 6 ] }; // 将匹配周末

函数匹配器

const functionMatcher: Matcher = ( day: Date ) => {
    return day.getMonth() === 2; // 当月份为三月时匹配
};