日期选择器

Alpha

通过输入框和日历界面辅助选择日期。

View code

Birthday

yyyy

功能特性

完整的键盘导航
可受控或非受控
焦点完全受控
本地化支持
默认具备无障碍访问性
同时支持日期和日期时间格式

前言

该组件依赖于 @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 参考

Root

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`closeOnSelect`	`false`	`boolean` Whether or not to close the popover on date select
`defaultOpen`	`false`	`boolean` The open state of the popover when it is initially rendered. Use when you do not need to control its open state.
`defaultPlaceholder`		`DateValue` The default placeholder date
`defaultValue`		`DateValue` The default value for the calendar
`dir`		`'ltr' \| 'rtl'` The reading direction of the date field when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
`disabled`	`false`	`boolean` Whether or not the date field is disabled
`fixedWeeks`	`false`	`boolean` Whether or not to always display 6 weeks in the calendar
`granularity`		`'day' \| 'hour' \| 'minute' \| 'second'` The granularity to use for formatting times. Defaults to day if a CalendarDate is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity
`hideTimeZone`		`boolean` Whether or not to hide the time zone segment of the field
`hourCycle`		`12 \| 24` The hour cycle used for formatting times. Defaults to the local preference
`id`		`string` Id of the element
`isDateDisabled`		`Matcher` A function that returns whether or not a date is disabled
`isDateUnavailable`		`Matcher` A function that returns whether or not a date is unavailable
`locale`	`'en'`	`string` The locale to use for formatting dates
`maxValue`		`DateValue` The maximum date that can be selected
`minValue`		`DateValue` The minimum date that can be selected
`modal`	`false`	`boolean` The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers.
`modelValue`		`DateValue \| null` The controlled checked state of the calendar. Can be bound as `v-model`.
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`numberOfMonths`	`1`	`number` The number of months to display at once
`open`		`boolean` The controlled open state of the popover.
`pagedNavigation`	`false`	`boolean` This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month
`placeholder`		`DateValue` The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar and can be used to programmatically control the calendar view
`preventDeselect`	`false`	`boolean` Whether or not to prevent the user from deselecting a date without selecting another date first
`readonly`	`false`	`boolean` Whether or not the date field is readonly
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`step`		`DateStep` The stepping interval for the time fields. Defaults to `1`.
`weekdayFormat`	`'narrow'`	`'narrow' \| 'short' \| 'long'` The format to use for the weekday strings provided via the weekdays slot prop
`weekStartsOn`	`0`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` The day of the week to start the calendar on

Emit	Payload
`update:modelValue`	`[date: DateValue]` Event handler called whenever the model value changes
`update:open`	`[value: boolean]` Event handler called when the open state of the submenu changes.
`update:placeholder`	`[date: DateValue]` Event handler called whenever the placeholder value changes

Methods	Type
`isDateDisabled`	`Matcher` A function that returns whether or not a date is disabled
`isDateUnavailable`	`Matcher` A function that returns whether or not a date is unavailable

Field

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

Slots (default)	Payload
`segments`	`{ part: SegmentPart; value: string; }[]`
`modelValue`	`DateValue \| undefined`

Data Attribute	Value
`[data-readonly]`	只读时存在
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在

Input

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`part*`		`'day' \| 'month' \| 'year' \| 'hour' \| 'minute' \| 'second' \| 'dayPeriod' \| 'literal' \| 'timeZoneName'` The part of the date to render

Data Attribute	Value
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在
`[data-placeholder]`	未设置值时存在

Trigger

用于切换弹出框的按钮。默认情况下，DatePickerContent 将相对于触发器进行定位。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Content

弹出框打开时弹出的组件。

Prop	Default	Type
`align`		`'start' \| 'center' \| 'end'` The preferred alignment against the trigger. May change when collisions occur.
`alignFlip`		`boolean` Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true.
`alignOffset`		`number` An offset in pixels from the `start` or `end` alignment options.
`arrowPadding`		`number` The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners.
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`avoidCollisions`		`boolean` When `true`, overrides the side and align preferences to prevent collisions with boundary edges.
`collisionBoundary`		`Element \| (Element \| null)[] \| null` The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check.
`collisionPadding`		`number \| Partial<Record<'top' \| 'right' \| 'bottom' \| 'left', number>>` The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }.
`disableOutsidePointerEvents`		`boolean` When `true`, hover/focus/click interactions will be disabled on elements outside the `DismissableLayer`. Users will need to click twice on outside elements to interact with them: once to close the `DismissableLayer`, and again to trigger the element.
`disableUpdateOnLayoutShift`		`boolean` Whether to disable the update position for the content when the layout shifted.
`forceMount`		`boolean` Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.
`hideWhenDetached`		`boolean` Whether to hide the content when the trigger becomes fully occluded.
`portal`		`PopoverPortalProps` Props to control the portal wrapped around the content.
`positionStrategy`		`'fixed' \| 'absolute'` The type of CSS position property to use.
`prioritizePosition`		`boolean` Force content to be position within the viewport. Might overlap the reference element, which may not be desired.
`reference`		`ReferenceElement` The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element.
`side`		`'top' \| 'right' \| 'bottom' \| 'left'` The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled.
`sideFlip`		`boolean` Flip to the opposite side when colliding with boundary.
`sideOffset`		`number` The distance in pixels from the trigger.
`sticky`		`'partial' \| 'always'` The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless.
`updatePositionStrategy`		`'always' \| 'optimized'` Strategy to update the position of the floating element on every animation frame.

Emit	Payload
`closeAutoFocus`	`[event: Event]` Event handler called when auto-focusing on close. Can be prevented.
`escapeKeyDown`	`[event: KeyboardEvent]` Event handler called when the escape key is down. Can be prevented.
`focusOutside`	`[event: FocusOutsideEvent]` Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.
`interactOutside`	`[event: PointerDownOutsideEvent \| FocusOutsideEvent]` Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented.
`openAutoFocus`	`[event: Event]` Event handler called when auto-focusing on open. Can be prevented.
`pointerDownOutside`	`[event: PointerDownOutsideEvent]` Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.

Arrow

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`height`		`number` The height of the arrow in pixels.
`rounded`		`boolean` When `true`, render the rounded version of arrow. Do not work with `as`/`asChild`
`width`		`number` The width of the arrow in pixels.

Close

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Anchor

一个可选元素，用于定位 DatePickerContent。如果未使用此部件，内容将相对于 DatePickerTrigger 进行定位。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`reference`		`ReferenceElement` The reference (or anchor) element that is being referred to for positioning. If not provided will use the current component as anchor.

Calendar

包含日历的所有部件

Slots (default)	Payload
`date`	`DateValue`
`grid`	`Grid<DateValue>[]`
`weekDays`	`string[]`
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`
`locale`	`string`
`fixedWeeks`	`boolean`

Data Attribute	Value
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在
`[data-readonly]`	只读时存在

包含导航按钮和标题段。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Prev Button

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`prevPage`		`((placeholder: DateValue) => DateValue)` The function to be used for the prev page. Overwrites the `prevPage` function set on the `CalendarRoot`.

Slots (default)	Payload
`disabled`	`boolean` Current disable state

Data Attribute	Value
`[data-disabled]`	禁用时存在

Next Button

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`nextPage`		`((placeholder: DateValue) => DateValue)` The function to be used for the next page. Overwrites the `nextPage` function set on the `CalendarRoot`.

Slots (default)	Payload
`disabled`	`boolean` Current disable state

Data Attribute	Value
`[data-disabled]`	禁用时存在

Heading

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Slots (default)	Payload
`headingValue`	`string` Current month and year

Grid

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-disabled]`	禁用时存在
`[data-readonly]`	只读时存在

Grid Head

用于包装网格头部的容器。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Grid Body

用于包装网格主体的容器。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Grid Row

用于包装网格行的容器。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Head Cell

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Cell

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`date*`		`DateValue` The date value for the cell

Data Attribute	Value
`[data-disabled]`	禁用时存在

Cell Trigger

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

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`day*`		`DateValue` The date value provided to the cell trigger
`month*`		`DateValue` The month in which the cell is rendered

Slots (default)	Payload
`dayValue`	`string` Current day
`disabled`	`boolean` Current disable state
`selected`	`boolean` Current selected state
`today`	`boolean` Current today state
`outsideView`	`boolean` Current outside view state
`outsideVisibleView`	`boolean` Current outside visible view state
`unavailable`	`boolean` Current unavailable state

Data Attribute	Value
`[data-selected]`	选中时存在
`[data-value]`	日期的 ISO 字符串值。
`[data-disabled]`	禁用时存在
`[data-unavailable]`	不可用时存在
`[data-today]`	今天时存在
`[data-outside-view]`	日期不在当前显示的月份内时存在。
`[data-outside-visible-view]`	日期不在日历上可见的月份内时存在。
`[data-focused]`	聚焦时存在

无障碍访问

键盘交互

Key	Description
`Tab`	当焦点移动到日期字段上时，聚焦第一个段。
`Space`	当焦点位于 `DatePickerNext` 或 `DatePickerPrev` 上时，它会导航日历。否则，它会选择日期。如果焦点位于 `DatePickerTrigger` 上，它会打开/关闭弹出框。
`Enter`	当焦点位于 `DatePickerNext` 或 `DatePickerPrev` 上时，它会导航日历。否则，它会选择日期。如果焦点位于 `DatePickerTrigger` 上，它会打开/关闭弹出框。
`ArrowLeftArrowRight`	在日期字段段之间导航。如果焦点位于 `DatePickerCalendar` 上，则在日期之间导航。
`ArrowUpArrowDown`	增加/更改段的值。如果焦点位于 `DatePickerCalendar` 上，则在日期之间导航。
`0-9`	当焦点位于数字 `DatePickerInput` 上时，输入数字，如果下一个输入会导致无效值，则聚焦下一个段。
`Backspace`	从聚焦的数字段中删除一位数字。
`AP`	当焦点位于日周期段上时，将其设置为 AM 或 PM。

日期选择器 ​

功能特性 ​

前言 ​

安装 ​

结构 ​

API 参考 ​

Root ​

Field ​

Input ​

Trigger ​

Content ​

Arrow ​

Close ​

Anchor ​

Calendar ​

Header ​

Prev Button ​

Next Button ​

Heading ​

Grid ​

Grid Head ​

Grid Body ​

Grid Row ​

Head Cell ​

Cell ​

Cell Trigger ​

无障碍访问 ​

键盘交互 ​