日期范围选择器

Alpha

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

View code

Booking

yyyy

功能特性

完整的键盘导航支持
可控制或非控制模式
完善的焦点管理
本地化支持
默认具备可访问性
同时支持日期和日期时间格式

前置说明

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

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

安装

安装日期包。

$ npm add @internationalized/date

从命令行安装组件。

$ npm add reka-ui

结构

导入所有部件并进行组合。

vue

<script setup>
import {
  DateRangePickerAnchor,
  DateRangePickerArrow,
  DateRangePickerCalendar,
  DateRangePickerCell,
  DateRangePickerCellTrigger,
  DateRangePickerClose,
  DateRangePickerContent,
  DateRangePickerField,
  DateRangePickerGrid,
  DateRangePickerGridBody,
  DateRangePickerGridHead,
  DateRangePickerGridRow,
  DateRangePickerHeadCell,
  DateRangePickerHeader,
  DateRangePickerHeading,
  DateRangePickerInput,
  DateRangePickerNext,
  DateRangePickerPrev,
  DateRangePickerRoot,
  DateRangePickerTrigger,
} from 'reka-ui'
</script>

<template>
  <DateRangePickerRoot>
    <DateRangePickerField>
      <DateRangePickerInput />
      <DateRangePickerTrigger />
    </DateRangePickerField>

    <DateRangePickerAnchor />

    <DateRangePickerContent>
      <DateRangePickerClose />
      <DateRangePickerArrow />

      <DateRangePickerCalendar>
        <DateRangePickerHeader>
          <DateRangePickerPrev />
          <DateRangePickerHeading />
          <DateRangePickerNext />
        </DateRangePickerHeader>

        <DateRangePickerGrid>
          <DateRangePickerGridHead>
            <DateRangePickerGridRow>
              <DateRangePickerHeadCell />
            </DateRangePickerGridRow>
          </DateRangePickerGridHead>

          <DateRangePickerGridBody>
            <DateRangePickerGridRow>
              <DateRangePickerCell>
                <DateRangePickerCellTrigger />
              </DateRangePickerCell>
            </DateRangePickerGridRow>
          </DateRangePickerGridBody>
        </DateRangePickerGrid>
      </DateRangePickerCalendar>
    </DateRangePickerContent>
  </DateRangePickerRoot>
</template>

API 参考

Root

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

Prop	Default	Type
`allowNonContiguousRanges`	`false`	`boolean` When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`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 range 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`	`{ start: undefined, end: undefined }`	`DateRange` 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
`fixedDate`		`'start' \| 'end'` Which part of the range should be fixed
`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
`isDateHighlightable`		`Matcher` A function that returns whether or not a date is hightable
`isDateUnavailable`		`Matcher` A function that returns whether or not a date is unavailable
`locale`	`'en'`	`string` The locale to use for formatting dates
`maximumDays`		`number` The maximum number of days that can be selected in a range
`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`		`DateRange \| 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: DateRange]` 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
`update:startValue`	`[date: DateValue]` Event handler called whenever the start value changes

Slots (default)	Payload
`modelValue`	`DateRange`
`open`	`boolean`

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
`isDateHighlightable`	`Matcher` A function that returns whether or not a date is hightable

Field

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

Slots (default)	Payload
`segments`	`{ start: { part: SegmentPart; value: string; }[]; end: { part: SegmentPart; value: string; }[]; }`
`modelValue`	`DateRange \| null`

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
`type*`		`'start' \| 'end'` The type of field to render (start or end)

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

Trigger

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

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

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

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

用于定位 DateRangePickerContent 的可选元素。如果未使用此部件，内容将相对于 DateRangePickerTrigger 进行定位。

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-readonly]`	只读时存在
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在

包含导航按钮和标题段。

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 `RangeCalendarRoot`.

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 `RangeCalendarRoot`.

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

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

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-readonly]`	只读时存在
`[data-disabled]`	禁用时存在

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`

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`
`month*`		`DateValue`

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
`highlighted`	`boolean` Current highlighted state
`highlightedStart`	`boolean` Current highlighted start state
`highlightedEnd`	`boolean` Current highlighted end state
`selectionStart`	`boolean` Current selection start state
`selectionEnd`	`boolean` Current selection end state

Data Attribute	Value
`[data-selected]`	选中时存在
`[data-value]`	日期的 ISO 字符串值。
`[data-disabled]`	禁用时存在
`[data-unavailable]`	不可用时存在
`[data-today]`	为今天时存在
`[data-outside-view]`	当日期不在其显示的当前月份内时存在。
`[data-outside-visible-view]`	当日期不在日历上可见的月份内时存在。
`[data-selection-start]`	当日期是选择的起点时存在。
`[data-selection-end]`	当日期是选择的终点时存在。
`[data-highlighted]`	当用户选择范围时突出显示该日期时存在。
`[data-highlighted-start]`	当日期是用户突出显示范围的起点时存在。
`[data-highlighted-end]`	当日期是用户突出显示范围的终点时存在。
`[data-focused]`	获得焦点时存在

可访问性

键盘交互

Key	Description
`Tab`	当焦点移动到日期字段上时，聚焦第一个段。
`Space`	当焦点位于 `DateRangePickerNext` 或 `DateRangePickerPrev` 上时，它导航日历。否则，它选择日期。如果焦点位于 `DateRangePickerTrigger` 上，则打开/关闭弹出框。
`Enter`	当焦点位于 `DateRangePickerNext` 或 `DateRangePickerPrev` 上时，它导航日历。否则，它选择日期。如果焦点位于 `DateRangePickerTrigger` 上，则打开/关闭弹出框。
`ArrowLeftArrowRight`	在日期字段段之间导航。如果焦点位于 `DateRangePickerCalendar` 上，则在日期之间导航。
`ArrowUpArrowDown`	递增/更改段的值。如果焦点位于 `DateRangePickerCalendar` 上，则在日期之间导航。
`0-9`	当焦点位于数字 `DateRangePickerInput` 上时，输入数字并在下一个输入将导致无效值时聚焦下一个段。
`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 ​

可访问性 ​

键盘交互 ​