Lzh on GitHub

Date Picker

通过输入和基于日历的界面方便选择日期。
<script setup lang="ts">
import { Icon } from '@iconify/vue'
import {
  DatePickerArrow,
  DatePickerCalendar,
  DatePickerCell,
  DatePickerCellTrigger,
  DatePickerContent,
  DatePickerField,
  DatePickerGrid,
  DatePickerGridBody,
  DatePickerGridHead,
  DatePickerGridRow,
  DatePickerHeadCell,
  DatePickerHeader,
  DatePickerHeading,
  DatePickerInput,
  DatePickerNext,
  DatePickerPrev,
  DatePickerRoot,
  DatePickerTrigger,
  Label,
} from 'reka-ui'
</script>

<template>
  <div class="flex flex-col gap-2">
    <Label
      class="text-sm text-stone-700 dark:text-white"
      for="birthday"
    >
      Birthday
    </Label>
    <DatePickerRoot
      id="birthday"
      :is-date-unavailable="date => date.day === 19"
    >
      <DatePickerField
        v-slot="{ segments }"
        class="w-36 flex select-none bg-white items-center rounded-lg shadow-sm text-center justify-between text-green10 border p-1 data-[invalid]:border-red-500"
      >
        <div class="flex items-center">
          <template
            v-for="item in segments"
            :key="item.part"
          >
            <DatePickerInput
              v-if="item.part === 'literal'"
              :part="item.part"
            >
              {{ item.value }}
            </DatePickerInput>
            <DatePickerInput
              v-else
              :part="item.part"
              class="rounded p-0.5 focus:outline-none focus:shadow-[0_0_0_2px] focus:shadow-black data-[placeholder]:text-green9"
            >
              {{ item.value }}
            </DatePickerInput>
          </template>
        </div>

        <DatePickerTrigger class="focus:shadow-[0_0_0_2px] rounded p-1 focus:shadow-black">
          <Icon
            icon="radix-icons:calendar"
            class="text-base"
          />
        </DatePickerTrigger>
      </DatePickerField>

      <DatePickerContent
        :side-offset="4"
        class="rounded-xl bg-white border shadow-sm will-change-[transform,opacity] data-[state=open]:data-[side=top]:animate-slideDownAndFade data-[state=open]:data-[side=right]:animate-slideLeftAndFade data-[state=open]:data-[side=bottom]:animate-slideUpAndFade data-[state=open]:data-[side=left]:animate-slideRightAndFade"
      >
        <DatePickerArrow class="fill-white stroke-gray-300" />
        <DatePickerCalendar
          v-slot="{ weekDays, grid }"
          class="p-4"
        >
          <DatePickerHeader class="flex items-center justify-between">
            <DatePickerPrev
              class="inline-flex items-center cursor-pointer text-black justify-center rounded-md bg-transparent w-7 h-7 hover:bg-stone-50 active:scale-98 active:transition-all focus:shadow-[0_0_0_2px] focus:shadow-black"
            >
              <Icon
                icon="radix-icons:chevron-left"
                class="w-4 h-4"
              />
            </DatePickerPrev>

            <DatePickerHeading class="text-black font-medium" />
            <DatePickerNext
              class="inline-flex items-center cursor-pointer text-black justify-center rounded-md bg-transparent w-7 h-7 hover:bg-stone-50 active:scale-98 active:transition-all focus:shadow-[0_0_0_2px] focus:shadow-black"
            >
              <Icon
                icon="radix-icons:chevron-right"
                class="w-4 h-4"
              />
            </DatePickerNext>
          </DatePickerHeader>
          <div
            class="flex flex-col space-y-4 pt-4 sm:flex-row sm:space-x-4 sm:space-y-0"
          >
            <DatePickerGrid
              v-for="month in grid"
              :key="month.value.toString()"
              class="w-full border-collapse select-none space-y-1"
            >
              <DatePickerGridHead>
                <DatePickerGridRow class="mb-1 flex w-full justify-between">
                  <DatePickerHeadCell
                    v-for="day in weekDays"
                    :key="day"
                    class="w-8 rounded-md text-xs text-green8"
                  >
                    {{ day }}
                  </DatePickerHeadCell>
                </DatePickerGridRow>
              </DatePickerGridHead>
              <DatePickerGridBody>
                <DatePickerGridRow
                  v-for="(weekDates, index) in month.rows"
                  :key="`weekDate-${index}`"
                  class="flex w-full"
                >
                  <DatePickerCell
                    v-for="weekDate in weekDates"
                    :key="weekDate.toString()"
                    :date="weekDate"
                  >
                    <DatePickerCellTrigger
                      :day="weekDate"
                      :month="month.value"
                      class="relative flex items-center justify-center whitespace-nowrap rounded-[9px] border border-transparent bg-transparent text-sm font-normal text-black w-8 h-8 outline-none focus:shadow-[0_0_0_2px] focus:shadow-black hover:border-black data-[selected]:bg-black data-[selected]:font-medium data-[outside-view]:text-black/30 data-[selected]:text-white data-[unavailable]:pointer-events-none data-[unavailable]:text-black/30 data-[unavailable]:line-through before:absolute before:top-[5px] before:hidden before:rounded-full before:w-1 before:h-1 before:bg-white data-[today]:before:block data-[today]:before:bg-green9 data-[selected]:before:bg-white"
                    />
                  </DatePickerCell>
                </DatePickerGridRow>
              </DatePickerGridBody>
            </DatePickerGrid>
          </div>
        </DatePickerCalendar>
      </DatePickerContent>
    </DatePickerRoot>
  </div>
</template>

功能特性 (Features)

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

前言 (Preface)

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

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

安装

安装日期包 (Install the date package)

$ npm add @internationalized/date

安装组件 (Install the component)

$ npm add reka-ui

结构 (Anatomy)

导入所有部件并将其组合在一起。

<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 参考 (API Reference)

根 (Root)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。
defaultOpenfalseboolean弹出框初始渲染时的打开状态。当您不需要控制其打开状态时使用。
defaultPlaceholderDateValue默认占位符日期。
defaultValueDateValue日历的默认值。
dir'ltr' | 'rtl'日期字段的阅读方向(如果适用)。如果省略,则全局继承自 ConfigProvider 或假定为 LTR(从左到右)阅读模式。
disabledfalseboolean日期字段是否禁用。
fixedWeeksfalseboolean日历是否始终显示 6 周。
granularity'day' | 'hour' | 'minute' | 'second'用于格式化时间的粒度。如果提供了 CalendarDate,则默认为天,否则默认为分钟。字段将渲染日期各部分的片段,直至并包括指定的粒度。
hideTimeZoneboolean是否隐藏字段的时区片段。
hourCycle12 | 24用于格式化时间的小时制。默认为本地偏好设置。
idstring元素的 ID。
isDateDisabledMatcher返回日期是否被禁用的函数。
isDateUnavailableMatcher返回日期是否不可用的函数。
locale'en'string用于格式化日期的区域设置。
maxValueDateValue可选择的最大日期。
minValueDateValue可选择的最小日期。
modalfalseboolean弹出框的模态性。当设置为 true 时,与外部元素的交互将被禁用,并且只有弹出框内容对屏幕阅读器可见。
modelValueDateValue | null日历的受控选中状态。可绑定为 v-model
namestring字段的名称。作为名称/值对的一部分随其所属的表单一起提交。
numberOfMonths1number一次显示的月份数量。
openboolean弹出框的受控打开状态。
pagedNavigationfalseboolean此属性使“上一页”和“下一页”按钮根据一次显示的月份数量而不是一个月进行导航。
placeholderDateValue占位符日期,用于在未选择日期时确定要显示的月份。它会随着用户导航日历而更新,可用于编程控制日历视图。
preventDeselectfalseboolean是否阻止用户在未选择另一个日期的情况下取消选择日期。
readonlyfalseboolean日期字段是否只读。
requiredbooleantrue 时,表示用户必须在提交所属表单之前设置值。
stepDateStep时间字段的步进间隔。默认为 1
weekdayFormat'narrow''narrow' | 'short' | 'long'用于通过 weekdays 插槽提供的星期几字符串的格式。
weekStartsOn00 | 1 | 2 | 3 | 4 | 5 | 6日历开始的星期几。

发送事件

事件名称Payload描述
update:modelValue[date: DateValue]modelValue 更改时调用的事件处理程序。
update:open[value: boolean]子菜单打开状态更改时调用的事件处理程序。
update:placeholder[date: DateValue]placeholder 值更改时调用的事件处理程序。

方法 (Methods)

方法名称类型描述
isDateDisabledMatcher返回日期是否被禁用的函数。
isDateUnavailableMatcher返回日期是否不可用的函数。

字段 (Field)

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

默认插槽

插槽参数插槽参数类型描述
segments{ part: SegmentPart; value: string; }[]日期字段片段内容。
modelValueDateValue | undefined字段的当前日期。

数据属性 (Data Attribute)

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

输入 (Input)

包含日期选择器日期字段片段。

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

数据属性 (Data Attribute)

描述
[data-disabled]禁用时存在
[data-invalid]无效时存在
[data-placeholder]未设置值时存在

触发器 (Trigger)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

内容 (Content)

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

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

发送事件

事件Payload描述
closeAutoFocus[event: Event]关闭时自动聚焦时调用的事件处理程序。可以阻止。
escapeKeyDown[event: KeyboardEvent]按下 Escape 键时调用的事件处理程序。可以阻止。
focusOutside[event: FocusOutsideEvent]焦点移出 DismissableLayer 时调用的事件处理程序。可以阻止。
interactOutside[event: PointerDownOutsideEvent | FocusOutsideEvent]DismissableLayer 外部发生交互时调用的事件处理程序。具体来说,当外部发生 pointerdown 事件或焦点移出时。可以阻止。
openAutoFocus[event: Event]打开时自动聚焦时调用的事件处理程序。可以阻止。
pointerDownOutside[event: PointerDownOutsideEvent]DismissableLayer 外部发生 pointerdown 事件时调用的事件处理程序。可以阻止。

箭头 (Arrow)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。
heightnumber箭头的像素高度。
roundedbooleantrue 时,渲染圆角版本的箭头。不适用于 as/asChild
widthnumber箭头的像素宽度。

关闭 (Close)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

锚点 (Anchor)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。
referenceReferenceElement被引用以进行定位的参考(或锚点)元素。如果未提供,将使用当前组件作为锚点。

日历 (Calendar)

包含日历的所有部分。

默认插槽

插槽参数插槽参数类型描述
dateDateValue日期。
gridGrid<DateValue>[]网格。
weekDaysstring[]星期几。
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 6周的开始。
localestring区域设置。
fixedWeeksboolean是否固定周数。

数据属性 (Data Attribute)

描述
[data-disabled]禁用时存在
[data-invalid]无效时存在
[data-readonly]只读时存在

头部 (Header)

包含导航按钮和标题段。

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

上一页按钮 (Prev Button)

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

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

默认插槽

插槽参数插槽参数类型描述
disabledboolean当前禁用状态

数据属性 (Data Attribute)

描述
[data-disabled]禁用时存在

下一页按钮 (Next Button)

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

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

默认插槽

插槽参数插槽参数类型描述
disabledboolean当前禁用状态

数据属性 (Data Attribute)

描述
[data-disabled]禁用时存在

标题 (Heading)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

默认插槽

插槽参数插槽参数类型描述
headingValuestring当前月份和年份。

网格 (Grid)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

数据属性 (Data Attribute)

描述
[data-disabled]禁用时存在
[data-readonly]只读时存在

网格头部 (Grid Head)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

网格体 (Grid Body)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

网格行 (Grid Row)

用于包裹网格行的容器。

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

头部单元格 (Head Cell)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。

单元格 (Cell)

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

属性默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可通过 asChild 覆盖。
asChildboolean将默认渲染的元素替换为作为子元素传递的元素,合并它们的 props 和行为。阅读我们的组合指南了解更多详情。
date*DateValue单元格的日期值。

数据属性 (Data Attribute)

描述
[data-disabled]禁用时存在

单元格触发器 (Cell Trigger)

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

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

默认插槽

插槽参数插槽参数类型描述
dayValuestring当前日期。
disabledboolean当前禁用状态。
selectedboolean当前选中状态。
todayboolean当前是否为今天。
outsideViewboolean当前是否在当前月份视图之外。
outsideVisibleViewboolean当前是否在日历可见月份之外。
unavailableboolean当前是否不可用。

数据属性 (Data Attribute)

描述
[data-selected]选中时存在
[data-value]日期的 ISO 字符串值。
[data-disabled]禁用时存在
[data-unavailable]不可用时存在
[data-today]今天时存在
[data-outside-view]日期在当前月份视图之外时存在。
[data-outside-visible-view]日期在日历可见月份之外时存在。
[data-focused]聚焦时存在

可访问性 (Accessibility)

键盘交互 (Keyboard Interactions)

按键描述
Tab当焦点移动到日期字段时,聚焦第一个片段。
Space当焦点位于 DatePickerNextDatePickerPrev 上时,导航日历。否则,选择日期。如果焦点位于 DatePickerTrigger 上,则打开/关闭弹出框。
Enter当焦点位于 DatePickerNextDatePickerPrev 上时,导航日历。否则,选择日期。如果焦点位于 DatePickerTrigger 上,则打开/关闭弹出框。
ArrowLeft ArrowRight在日期字段片段之间导航。如果焦点位于 DatePickerCalendar 上,则在日期之间导航。
ArrowUp ArrowDown增加/更改片段的值。如果焦点位于 DatePickerCalendar 上,则在日期之间导航。
0-9当焦点位于数字 DatePickerInput 上时,输入数字并聚焦下一个片段,如果下一个输入会导致无效值。
Backspace从聚焦的数字片段中删除一位数字。
A P当焦点位于日期间隔(上午/下午)时,将其设置为 AM 或 PM。