Radix Vue

外观

日期选择器 ​

Alpha
通过输入和基于日历的界面来促进日期选择。
mm
dd
yyyy
vue
<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 'radix-vue'
</script>

<template>
  <div class="flex flex-col gap-2">
    <Label
      class="text-sm text-white"
      for="date-field"
    >Birthday</Label>
    <DatePickerRoot
      id="date-field"
      :is-date-unavailable="date => date.day === 19"
    >
      <DatePickerField
        v-slot="{ segments }"
        class="flex select-none bg-white items-center justify-between rounded-lg text-center text-green10 border border-transparent p-1 w-40 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-md 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-md text-xl p-1 focus:shadow-black">
          <Icon icon="radix-icons:calendar" />
        </DatePickerTrigger>
      </DatePickerField>

      <DatePickerContent
        :side-offset="4"
        class="rounded-xl bg-white shadow-[0_10px_38px_-10px_hsla(206,22%,7%,.35),0_10px_20px_-15px_hsla(206,22%,7%,.2)] focus:shadow-[0_10px_38px_-10px_hsla(206,22%,7%,.35),0_10px_20px_-15px_hsla(206,22%,7%,.2),0_0_0_2px_theme(colors.green7)] 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" />
        <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-[9px] bg-transparent w-8 h-8 hover:bg-black hover:text-white active:scale-98 active:transition-all focus:shadow-[0_0_0_2px] focus:shadow-black"
            >
              <Icon
                icon="radix-icons:chevron-left"
                class="w-6 h-6"
              />
            </DatePickerPrev>

            <DatePickerHeading class="text-black font-medium" />
            <DatePickerNext
              class="inline-flex items-center cursor-pointer text-black justify-center rounded-[9px] bg-transparent w-8 h-8 hover:bg-black hover:text-white active:scale-98 active:transition-all focus:shadow-[0_0_0_2px] focus:shadow-black"
            >
              <Icon
                icon="radix-icons:chevron-right"
                class="w-6 h-6"
              />
            </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-[disabled]: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>

学分

该组件在构建时借鉴了 melt-ui 中的实现。

功能 ​

  • 完整的键盘导航
  • 可以是受控或不受控的
  • 焦点完全管理
  • 本地化支持
  • 默认情况下无障碍
  • 支持日期和日期时间格式

前言 ​

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

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

安装 ​

安装日期包。

sh
$ npm add @internationalized/date

从命令行安装组件。

sh
$ npm add radix-vue

解剖学 ​

导入所有部分并将它们拼凑在一起。

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 'radix-vue'
</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 | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

defaultOpen
false
布尔值

首次渲染时弹出窗口的打开状态。当您不需要控制其打开状态时使用。

defaultPlaceholder
DateValue

默认占位符日期

defaultValue
DateValue

日历的默认值

dir
'ltr' | 'rtl'

日期字段的阅读方向（如果适用）。
如果省略，则从 ConfigProvider 全局继承或假设 LTR（从左到右）阅读模式。

disabled
false
布尔值

日期字段是否禁用

fixedWeeks
false
布尔值

是否始终在日历中显示 6 周

granularity
'day' | 'hour' | 'minute' | 'second'

用于格式化时间的粒度。如果提供 CalendarDate，则默认为 day，否则默认为 minute。该字段将为日期的每个部分渲染段，直到并包括指定的粒度

hideTimeZone
布尔值

是否隐藏字段的时区段

hourCycle
12 | 24

用于格式化时间的时钟周期。默认为本地首选项

id
字符串

元素的 ID

isDateDisabled
匹配器

返回日期是否禁用的函数

isDateUnavailable
匹配器

返回日期是否不可用的函数

locale
'en'
字符串

用于格式化日期的区域设置

maxValue
DateValue

可以选择的最大日期

minValue
DateValue

可以选择的最早日期

modal
false
布尔值

弹出窗口的模态性。当设置为 true 时，将禁用与外部元素的交互，并且只有弹出窗口内容对屏幕阅读器可见。

modelValue
DateValue

日历的受控选中状态。可以绑定为 v-model。

name
字符串

日期字段的名称。作为名称/值对的一部分与其所属的表单一起提交。

numberOfMonths
1
数字

一次显示的月份数

open
布尔值

弹出窗口的受控打开状态。

pagedNavigation
false
布尔值

此属性会导致上一个和下一个按钮按一次显示的月份数进行导航，而不是一个月份

placeholder
DateValue

占位符日期，用于确定未选择日期时显示哪个月份。这会在用户浏览日历时更新，并可用于以编程方式控制日历视图

preventDeselect
false
布尔值

是否阻止用户在不先选择另一个日期的情况下取消选择日期

readonly
false
布尔值

日期字段是否只读

required
布尔值

当 true 时，表示用户必须在提交所属表单之前检查日期字段。

weekdayFormat
'narrow'
'narrow' | 'short' | 'long'

用于通过 weekdays 插槽道具提供的星期字符串的格式

weekStartsOn
0
0 | 1 | 2 | 3 | 4 | 5 | 6

日历开始的星期几

发出有效载荷
update:modelValue
[date: DateValue]

每当模型值更改时都会调用的事件处理程序

update:open
[value: 布尔值]

当子菜单的打开状态更改时调用的事件处理程序。

update:placeholder
[date: DateValue]

每当占位符值更改时都会调用的事件处理程序

字段 ​

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

插槽（默认）有效载荷
segments
{ part: SegmentPart; value: string; }[]
modelValue
DateValue | 未定义
数据属性值
[data-readonly]当只读时存在
[data-disabled]当禁用时存在
[data-invalid]当无效时存在

输入 ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

part*
'day' | 'month' | 'year' | 'hour' | 'minute' | 'second' | 'dayPeriod' | 'literal' | 'timeZoneName'

要渲染的日期部分

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

触发器 ​

切换弹出窗口的按钮。默认情况下，DatePickerContent 将定位到触发器。

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

内容 ​

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

道具默认类型
align
'start' | 'center' | 'end'

相对于触发器的首选对齐方式。当发生碰撞时可能会更改。

alignOffset
数字

从 start 或 end 对齐选项的像素偏移量。

arrowPadding
数字

箭头与内容边缘之间的填充。如果您的内容有 border-radius，这将阻止它溢出角落。

as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

avoidCollisions
布尔值

当 true 时，会覆盖侧边和对齐偏好，以防止与边界边缘发生碰撞。

collisionBoundary
元素 | (元素 | 空)[] | 空

用作碰撞边界的元素。默认情况下，这是视口，但您可以提供其他元素以包含在此检查中。

collisionPadding
数字 | 部分<记录<'top' | 'right' | 'bottom' | 'left', 数字>>

从边界边缘到应发生碰撞检测的距离（以像素为单位）。接受一个数字（所有边都相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。

disableOutsidePointerEvents
布尔值

当 true 时，将在 DismissableLayer 外部的元素上禁用悬停/焦点/点击交互。用户需要在外部元素上单击两次才能与它们交互：一次关闭 DismissableLayer，另一次触发元素。

forceMount
布尔值

用于在需要更多控制时强制安装。当使用 Vue 动画库控制动画时很有用。

hideWhenDetached
布尔值

当触发器被完全遮挡时是否隐藏内容。

prioritizePosition
布尔值

强制内容在视窗内定位。

可能与参考元素重叠，这可能不是期望的结果。

side
'top' | 'right' | 'bottom' | 'left'

打开时，触发器首选渲染的侧边。当发生碰撞并且启用 avoidCollisions 时，将反转。

sideOffset
数字

距触发器的像素距离。

sticky
'partial' | 'always'

对齐轴上的粘性行为。partial 将使内容保持在边界内，只要触发器至少部分在边界内，而 "always" 将始终使内容保持在边界内。

trapFocus
布尔值

是否应将焦点限制在 MenuContent 内

updatePositionStrategy
'always' | 'optimized'

在每个动画帧上更新浮动元素位置的策略。

发出有效载荷
closeAutoFocus
[event: Event]

关闭时自动聚焦时调用的事件处理程序。可以阻止。

escapeKeyDown
[event: KeyboardEvent]

按下 Esc 键时调用的事件处理程序。可以阻止。

focusOutside
[event: FocusOutsideEvent]

焦点移出 DismissableLayer 时调用的事件处理程序。可以阻止。

interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]

在 DismissableLayer 外部发生交互时调用的事件处理程序。具体来说，当 pointerdown 事件发生在外部或焦点移出其外部时。可以阻止。

openAutoFocus
[event: Event]

打开时自动聚焦时调用的事件处理程序。可以阻止。

pointerDownOutside
[event: PointerDownOutsideEvent]

在 DismissableLayer 外部发生 pointerdown 事件时调用的事件处理程序。可以阻止。

Arrow ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

height
数字

箭头的像素高度。

width
数字

箭头的像素宽度。

Close ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

Anchor ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

element
Measurable

Calendar ​

包含日历的所有部分

插槽（默认）有效载荷
date
DateValue
grid
Grid<DateValue>[]
weekDays
string[]
weekStartsOn
0 | 1 | 2 | 3 | 4 | 5 | 6
locale
字符串
fixedWeeks
布尔值
数据属性值
[data-disabled]当禁用时存在
[data-invalid]当无效时存在
[data-readonly]当只读时存在

包含导航按钮和标题段。

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

Prev Button ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

prevPage
((placeholder: DateValue) => DateValue)

用于上页的函数。覆盖 CalendarRoot 上设置的 prevPage 函数。

step
'month' | 'year'

要后退的日历单位

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

Next Button ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

nextPage
((placeholder: DateValue) => DateValue)

用于下一页的函数。覆盖 CalendarRoot 上设置的 nextPage 函数。

step
'month' | 'year'

要前进的日历单位

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

Heading ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

插槽（默认）有效载荷
headingValue
字符串

当前月份和年份

Grid ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

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

Grid Head ​

用于包装网格头的容器。

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

Grid Body ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

Grid Row ​

用于包装网格行的容器。

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

Head Cell ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

Cell ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

date*
DateValue

单元格的日期值

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

Cell Trigger ​

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

道具默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可以通过 asChild 覆盖。

asChild
布尔值

将默认渲染的元素更改为作为子元素传递的元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

day*
DateValue

提供给单元格触发器的日期值

month*
DateValue

渲染单元格的月份

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

Accessibility ​

Keyboard Interactions ​

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