日期选择器

Alpha

通过输入框和日历界面方便地选择日期。

查看代码

生日

月

日

年

功能

完整的键盘导航
可控或非可控
焦点完全管理
本地化支持
默认可访问
支持日期和日期时间格式

前言

此组件依赖于 @internationalized/date 包，该包解决了在 JavaScript 中处理日期和时间时出现的许多问题。

我们强烈建议您阅读该包的文档，以便充分了解其工作原理，并且您需要将其安装到您的项目中才能使用日期相关组件。

安装

安装日期包。

$ npm add @internationalized/date

从命令行安装此组件。

$ npm add reka-ui

结构

导入所有部分并将其组合。

vue

<script setup>
import {
  DatePickerAnchor,
  DatePickerArrow,
  DatePickerCalendar,
  DatePickerCell,
  DatePickerCellTrigger,
  DatePickerClose,
  DatePickerContent,
  DatePickerField,
  DatePickerGrid,
  DatePickerGridBody,
  DatePickerGridHead,
  DatePickerGridRow,
  DatePickerHeadCell,
  DatePickerHeader,
  DatePickerHeading,
  DatePickerInput,
  DatePickerNext,
  DatePickerPrev,
  DatePickerRoot,
  DatePickerTrigger,
} from 'reka-ui'
</script>

<template>
  <DatePickerRoot>
    <DatePickerField>
      <DatePickerInput />
      <DatePickerTrigger />
    </DatePickerField>

    <DatePickerAnchor />
    <DatePickerContent>
      <DatePickerClose />
      <DatePickerArrow />

      <DatePickerCalendar>
        <DatePickerHeader>
          <DatePickerPrev />
          <DatePickerHeading />
          <DatePickerNext />
        </DatePickerHeader>

        <DatePickerGrid>
          <DatePickerGridHead>
            <DatePickerGridRow>
              <DatePickerHeadCell />
            </DatePickerGridRow>
          </DatePickerGridHead>

          <DatePickerGridBody>
            <DatePickerGridRow>
              <DatePickerCell>
                <DatePickerCellTrigger />
              </DatePickerCell>
            </DatePickerGridRow>
          </DatePickerGridBody>
        </DatePickerGrid>
      </DatePickerCalendar>
    </DatePickerContent>
  </DatePickerRoot>
</template>

API 参考

根

包含日期选择器的所有部分

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`defaultOpen`	`false`	`布尔值` 浮动窗口初始渲染时的打开状态。当您不需要控制其打开状态时使用。
`defaultPlaceholder`		`DateValue` 默认占位符日期
`defaultValue`		`DateValue` 日历的默认值
`dir`		`'ltr' \| 'rtl'` 日期字段适用的阅读方向。如果省略，则全局继承自 `ConfigProvider` 或假定为 LTR（从左到右）阅读模式。
`disabled`	`false`	`布尔值` 日期字段是否被禁用
`fixedWeeks`	`false`	`布尔值` 日历是否始终显示6周
`granularity`		`'day' \| 'hour' \| 'minute' \| 'second'` 用于格式化时间的粒度。如果提供了 CalendarDate，则默认为“天”，否则默认为“分钟”。字段将呈现日期中每个部分的片段，直到并包括指定的粒度
`hideTimeZone`		`布尔值` 是否隐藏字段的时区部分
`hourCycle`		`12 \| 24` 用于格式化时间的小时制。默认为本地偏好设置
`id`		`string` 元素的 ID
`isDateDisabled`		`Matcher` 一个函数，返回日期是否被禁用
`isDateUnavailable`		`Matcher` 一个函数，返回日期是否不可用
`locale`	`'en'`	`string` 用于日期格式化的区域设置
`maxValue`		`DateValue` 可选择的最大日期
`minValue`		`DateValue` 可选择的最小日期
`modal`	`false`	`布尔值` 浮动窗口的模态性。设置为 true 时，与外部元素的交互将被禁用，并且只有浮动窗口内容对屏幕阅读器可见。
`modelValue`		`DateValue \| null` 日历的受控选中状态。可以绑定为`v-model`。
`name`		`string` 字段的名称。随其所属的表单一起作为名称/值对提交。
`numberOfMonths`	`1`	`数字` 一次性显示的月份数量
`open`		`布尔值` 浮动窗口的受控打开状态。
`pagedNavigation`	`false`	`布尔值` 此属性使上一页和下一页按钮以一次显示的月份数量进行导航，而非按月导航
`placeholder`		`DateValue` 占位符日期，用于在未选择日期时确定要显示的月份。此值会随着用户导航日历而更新，可用于编程方式控制日历视图。
`preventDeselect`	`false`	`布尔值` 是否阻止用户在未选择其他日期的情况下取消选择日期
`readonly`	`false`	`布尔值` 日期字段是否只读
`required`		`布尔值` 当为 `true` 时，表示用户必须在所属表单提交前设置值。
`step`		`DateStep` 时间字段的步进间隔。默认为 `1`。
`weekdayFormat`	`'narrow'`	`'narrow' \| 'short' \| 'long'` 通过 `weekdays` 插槽属性提供的星期字符串的格式
`weekStartsOn`	`0`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` 日历开始的星期几

事件触发	载荷
`update:modelValue`	`[date: DateValue]` 每当模型值改变时调用的事件处理程序
`update:open`	`[value: boolean]` 子菜单打开状态改变时调用的事件处理程序。
`update:placeholder`	`[date: DateValue]` 每当占位符值改变时调用的事件处理程序

方法	类型
`isDateDisabled`	`Matcher` 一个函数，返回日期是否被禁用
`isDateUnavailable`	`Matcher` 一个函数，返回日期是否不可用

字段

包含日期选择器的日期字段分段和触发器

插槽（默认）	载荷
`segments`	`{ part: SegmentPart; value: string; }[]`
`modelValue`	`DateValue \| undefined`

数据属性	值
`[data-readonly]`	只读时存在
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在

输入

包含日期选择器的日期字段分段

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`part*`		`'day' \| 'month' \| 'year' \| 'hour' \| 'minute' \| 'second' \| 'dayPeriod' \| 'literal' \| 'timeZoneName'` 要渲染的日期部分

数据属性	值
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在
`[data-placeholder]`	未设置值时存在

触发器

切换弹出框的按钮。默认情况下，DatePickerContent 将根据触发器定位自身。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

内容

浮动窗口打开时弹出的组件。

属性	默认	类型
`align`		`'start' \| 'center' \| 'end'` 相对于触发器的首选对齐方式。当发生碰撞时可能会改变。
`alignOffset`		`数字` 与 `start` 或 `end` 对齐选项的像素偏移量。
`arrowPadding`		`数字` 箭头与内容边缘之间的内边距。如果您的内容有 border-radius，这将防止它溢出角落。
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`avoidCollisions`		`布尔值` 当为 `true` 时，覆盖侧边和对齐偏好，以防止与边界边缘发生碰撞。
`collisionBoundary`		`Element \| (Element \| null)[] \| null` 用作碰撞边界的元素。默认情况下是视口，但您可以提供其他元素以包含在此检查中。
`collisionPadding`		`数字 \| Partial<Record<'top' \| 'right' \| 'bottom' \| 'left', number>>` 碰撞检测应发生的距边界边缘的像素距离。接受一个数字（所有边相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。
`disableOutsidePointerEvents`		`布尔值` 当为 `true` 时，`DismissableLayer` 外部元素的悬停/焦点/点击交互将被禁用。用户需要点击外部元素两次才能与之交互：第一次关闭 `DismissableLayer`，第二次触发该元素。
`disableUpdateOnLayoutShift`		`布尔值` 当布局发生偏移时，是否禁用更新内容位置。
`forceMount`		`布尔值` 当需要更多控制时，用于强制挂载。在与 Vue 动画库控制动画时很有用。
`hideWhenDetached`		`布尔值` 当触发器完全被遮挡时，是否隐藏内容。
`portal`		`PopoverPortalProps` 用于控制包裹内容的 portal 的属性。
`positionStrategy`		`'fixed' \| 'absolute'` 要使用的 CSS position 属性类型。
`prioritizePosition`		`布尔值` 强制内容在视口内定位。可能与参考元素重叠，这可能不是期望的结果。
`reference`		`ReferenceElement` 将设置为浮动元素定位参考的自定义元素或虚拟元素。如果提供，它将替换默认的锚点元素。
`side`		`'top' \| 'right' \| 'bottom' \| 'left'` 打开时，相对于触发器渲染的首选侧边。当发生碰撞且启用 avoidCollisions 时，将反转。
`sideOffset`		`数字` 与触发器的像素距离。
`sticky`		`'部分' \| '始终'` 对齐轴上的粘性行为。`partial` 将使内容保持在边界内，只要触发器至少部分在边界内；而 "always" 则无论如何都会将内容保持在边界内。
`updatePositionStrategy`		`'始终' \| '优化'` 在每个动画帧更新浮动元素位置的策略。

事件触发	载荷
`closeAutoFocus`	`[事件: Event]` 关闭时自动聚焦调用的事件处理程序。可阻止其默认行为。
`escapeKeyDown`	`[事件: KeyboardEvent]` 按下 Esc 键时调用的事件处理程序。可阻止其默认行为。
`focusOutside`	`[事件: FocusOutsideEvent]` 当焦点移出 `DismissableLayer` 时调用的事件处理程序。可阻止其默认行为。
`interactOutside`	`[事件: PointerDownOutsideEvent \| FocusOutsideEvent]` 当 `DismissableLayer` 外部发生交互时调用的事件处理程序。具体来说，当 `pointerdown` 事件在外部发生或焦点移出时。可阻止其默认行为。
`openAutoFocus`	`[事件: Event]` 打开时自动聚焦调用的事件处理程序。可阻止其默认行为。
`pointerDownOutside`	`[事件: PointerDownOutsideEvent]` 当 `pointerdown` 事件在 `DismissableLayer` 外部发生时调用的事件处理程序。可阻止其默认行为。

箭头

一个可选的箭头元素，与弹出框一同渲染。这可用于帮助在视觉上将锚点与 DatePickerContent 连接起来。必须在 DatePickerContent 内部渲染。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`高度`		`数字` 箭头的像素高度。
`rounded`		`布尔值` 当为 `true` 时，渲染圆角版本的箭头。不适用于 `as`/`asChild`
`宽度`		`数字` 箭头的像素宽度。

关闭

关闭已打开的日期选择器的按钮。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

锚点

一个可选的元素，用于定位 DatePickerContent。如果未使用此部分，内容将与 DatePickerTrigger 并列定位。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`reference`		`ReferenceElement` 用于定位的参考（或锚点）元素。如果未提供，将使用当前组件作为锚点。

日历

包含日历的所有部分

插槽（默认）	载荷
`date`	`DateValue`
`grid`	`Grid<DateValue>[]`
`weekDays`	`string[]`
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`
`locale`	`string`
`fixedWeeks`	`布尔值`

数据属性	值
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在
`[data-readonly]`	只读时存在

包含导航按钮和标题部分。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

上一页按钮

日历导航按钮。它根据当前日历视图，将日历向前导航一个月/年/十年。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`prevPage`		`((placeholder: DateValue) => DateValue)` 用于上一页的函数。覆盖 `CalendarRoot` 上设置的 `prevPage` 函数。

插槽（默认）	载荷
`disabled`	`布尔值` 当前禁用状态

数据属性	值
`[data-disabled]`	禁用时存在

下一页按钮

日历导航按钮。它根据当前日历视图，将日历导航到未来一个月/年/十年。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`nextPage`		`((placeholder: DateValue) => DateValue)` 用于下一页的函数。覆盖 `CalendarRoot` 上设置的 `nextPage` 函数。

插槽（默认）	载荷
`disabled`	`布尔值` 当前禁用状态

数据属性	值
`[data-disabled]`	禁用时存在

标题

显示当前月份和年份的标题。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

插槽（默认）	载荷
`headingValue`	`string` 当前月份和年份

网格

用于包裹日历网格的容器。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

数据属性	值
`[data-disabled]`	禁用时存在
`[data-readonly]`	只读时存在

网格头部

用于包裹网格头的容器。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

网格主体

用于包裹网格体的容器。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

网格行

用于包裹网格行的容器。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

头部单元格

用于包裹表头单元格的容器。用于显示星期几。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

单元格

用于包裹日历单元格的容器。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`date*`		`DateValue` 单元格的日期值

数据属性	值
`[data-disabled]`	禁用时存在

单元格触发器

用于显示单元格日期的可交互容器。点击可选择日期。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`day*`		`DateValue` 提供给单元格触发器的日期值
`month*`		`DateValue` 渲染单元格所在的月份

插槽（默认）	载荷
`dayValue`	`string` 当前日期
`disabled`	`布尔值` 当前禁用状态
`selected`	`布尔值` 当前选中状态
`today`	`布尔值` 当前今日状态
`outsideView`	`布尔值` 当前视图外状态
`outsideVisibleView`	`布尔值` 当前可见视图外状态
`unavailable`	`布尔值` 当前不可用状态

数据属性	值
`[data-selected]`	选中时存在
`[data-value]`	日期的 ISO 字符串值。
`[data-disabled]`	禁用时存在
`[data-unavailable]`	不可用时存在
`[data-today]`	为今天时存在
`[data-outside-view]`	当日期不在显示月份范围内时存在。
`[data-outside-visible-view]`	当日期不在日历可见月份范围内时存在。
`[data-focused]`	聚焦时存在

可访问性

键盘交互

键	描述
`Tab`	当焦点移到日期字段时，聚焦第一个片段。
`空格键`	当焦点位于 `DatePickerNext` 或 `DatePickerPrev` 上时，它会导航日历。否则，它会选择日期。如果焦点位于 `DatePickerTrigger` 上，它会打开/关闭弹出框。
`回车键`	当焦点位于 `DatePickerNext` 或 `DatePickerPrev` 上时，它会导航日历。否则，它会选择日期。如果焦点位于 `DatePickerTrigger` 上，它会打开/关闭弹出框。
`向左箭头向右箭头`	在日期字段分段之间导航。如果焦点位于 `DatePickerCalendar` 上，它会在日期之间导航。
`向上箭头向下箭头`	增加/更改分段的值。如果焦点位于 `DatePickerCalendar` 上，它会在日期之间导航。
`0-9`	当焦点位于数字 `DatePickerInput` 上时，它会输入数字并在下一个输入会导致无效值时聚焦到下一个分段。
`Backspace`	从聚焦的数字片段中删除一位数字。
`AP`	当焦点位于日期时段时，将其设置为上午 (AM) 或下午 (PM)。

日期选择器 ​

功能 ​

前言 ​

安装 ​

结构 ​

API 参考 ​

根 ​

字段 ​

输入 ​

触发器 ​

内容 ​

箭头 ​

关闭 ​

锚点 ​

日历 ​

头部 ​

上一页按钮 ​

下一页按钮 ​

标题 ​

网格 ​

网格头部 ​

网格主体 ​

网格行 ​

头部单元格 ​

单元格 ​

单元格触发器 ​

可访问性 ​

键盘交互 ​