DateField 日期字段

引入

import { DateField } from '@heroui/react';

用法

"use client";

import {DateField, Label} from "@heroui/react";

export function Basic() {

组件结构

import {DateField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <DateField>
    <Label />
    <DateField.Group>
      <DateField.Input>
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
    </DateField.Group>
    <Description />
    <FieldError />
  </DateField>
)

DateField 将标签、日期输入、说明与错误信息组合为单个无障碍组件。

带描述

"use client";

import {DateField, Description, Label} from "@heroui/react";

export function WithDescription() {

必填字段

"use client";

import {DateField, Description, Label} from "@heroui/react";

export function Required() {

校验

配合 FieldError，使用 isInvalid 展示校验信息。

"use client";

import {DateField, FieldError, Label} from "@heroui/react";

export function Invalid() {

带校验

DateField 支持使用 minValue、maxValue 及自定义校验逻辑。

"use client";

import type {DateValue} from "@internationalized/date";

import {DateField, Description, FieldError, Label} from "@heroui/react";

粒度

"use client";

import type {DateValue} from "@internationalized/date";

import {CircleQuestion} from "@gravity-ui/icons";

受控

通过受控 value 与其它组件或状态管理同步。

"use client";

import type {DateValue} from "@internationalized/date";

import {Button, DateField, Description, Label} from "@heroui/react";

禁用状态

"use client";

import {DateField, Description, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

带图标

通过前缀或后缀图标增强日期输入。

"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, Label} from "@heroui/react";

"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, Label} from "@heroui/react";

"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, Description, Label} from "@heroui/react";

全宽

"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, Label} from "@heroui/react";

变体

DateField.Group 提供两种视觉变体：

• primary（默认）：带阴影的标准样式，适用于大多数场景
• secondary：低强调、无阴影，适合放在 Surface 等表面背景上

"use client";

import {DateField, Label} from "@heroui/react";

export function Variants() {

在 Surface 中

在 Surface 内使用时，请在 DateField.Group 上使用 variant="secondary"，以应用适合表面背景的低强调变体。

"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, Description, Label, Surface} from "@heroui/react";

表单示例

包含校验与提交的完整表单示例。

"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar} from "@gravity-ui/icons";

自定义渲染函数

"use client";

import {DateField, Label} from "@heroui/react";

export function CustomRenderFunction() {

样式

传入 Tailwind CSS 类

import {DateField, Label, Description} from '@heroui/react';

function CustomDateField() {
  return (
    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Appointment date
      </Label>
      <DateField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <DateField.Input>
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
      </DateField.Group>
      <Description className="text-xs text-default-500">
        Select a date for your appointment.
      </Description>
    </DateField>
  );
}

自定义组件类

DateField 的默认样式很轻量。覆盖 .date-field 类即可自定义容器样式。

@layer components {
  .date-field {
    @apply flex flex-col gap-1;

    &[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

    [data-slot="label"] {
      @apply w-fit;
    }

    [data-slot="description"] {
      @apply px-1;
    }
  }
}

CSS 类

• .date-field – 轻量样式的根容器（flex flex-col gap-1）

说明： 子组件（Label、Description、FieldError）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。DateField.Group 的样式见下文 API 参考。

交互状态

DateField 会根据状态自动设置以下 data 属性：

• 无效：[data-invalid="true"] 或 [aria-invalid="true"] – 无效时自动隐藏 description 插槽
• 必填：[data-required="true"] – 当 isRequired 为 true 时添加
• 禁用：[data-disabled="true"] – 当 isDisabled 为 true 时添加
• 焦点在内：[data-focus-within="true"] – 任一子输入聚焦时添加

API 参考

DateField Props

DateField 继承 React Aria DateField 的全部 props。

Base Props

Value Props

Validation Props

Format Props

State Props

Form Props

Accessibility Props

组合组件

DateField 与以下独立组件配合使用，请分别导入并直接使用：

• Label – 来自 @heroui/react 的字段标签
• DateField.Group – 日期输入分组（详见下文）
• DateField.Input – 来自 @heroui/react 的分段位编辑输入
• DateField.InputContainer – 可横向滚动的容器，用于组合多个输入（例如开始/结束范围）
• DateField.Segment – 单个日期段位（年、月、日等）
• DateField.Prefix / DateField.Suffix – 输入组的前缀与后缀插槽
• Description – 来自 @heroui/react 的辅助说明
• FieldError – 来自 @heroui/react 的校验错误信息

这些组件各自有独立的 props API。在 DateField 中直接组合使用：

import {parseDate} from '@internationalized/date';
import {DateField, Label, Description, FieldError} from '@heroui/react';

<DateField
  isRequired
  isInvalid={hasError}
  minValue={today(getLocalTimeZone())}
  value={date}
  onChange={setDate}
>
  <Label>Appointment Date</Label>
  <DateField.Group>
    <DateField.Input>
      {(segment) => <DateField.Segment segment={segment} />}
    </DateField.Input>
  </DateField.Group>
  <Description>Select a date from today onwards.</Description>
  <FieldError>Please select a valid date.</FieldError>
</DateField>

DateValue 类型

DateField 使用 @internationalized/date 中的类型：

• CalendarDate – 不含时间与时区的日期
• CalendarDateTime – 含时间、不含时区
• ZonedDateTime – 含时间与时区
• Time – 仅时间

示例：

import {parseDate, today, getLocalTimeZone} from '@internationalized/date';

// Parse from string
const date = parseDate('2024-01-15');

// Today's date
const todayDate = today(getLocalTimeZone());

// Use in DateField
<DateField value={date} onChange={setDate}>
  {/* ... */}
</DateField>

说明： DateField 依赖 @internationalized/date 进行解析、运算与类型定义。更多类型与函数见 Internationalized Date 文档。

DateFieldRenderProps

对 className、style 或 children 使用渲染 prop 时，可使用以下值：

DateField.Group Props

DateField.Group 继承 React Aria Group 的全部 props，并额外支持：

DateField.Input Props

DateField.Input 继承 React Aria DateInput 的全部 props，并额外支持：

DateField.Input 接受渲染函数作为子节点，函数参数为日期段位；每个段位对应日期的一部分（年、月、日等）。

DateField.Segment Props

DateField.Segment 继承 React Aria DateSegment 的全部 props：

DateField.InputContainer Props

DateField.InputContainer 接受标准 HTML div 属性：

DateField.Prefix Props

DateField.Prefix 接受标准 HTML div 属性：

DateField.Suffix Props

DateField.Suffix 接受标准 HTML div 属性：

DateField.Group 样式

自定义组件类

基础类作用于所有实例，可通过 @layer components 一次性覆盖。

@layer components {
  .date-input-group {
    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-field-hover;
    }

    &[data-focus-within="true"],
    &:focus-within {
      @apply status-focused-field;
    }

    &[data-invalid="true"] {
      @apply status-invalid-field;
    }

    &[data-disabled="true"],
    &[aria-disabled="true"] {
      @apply status-disabled;
    }
  }

  .date-input-group__input {
    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

  .date-input-group__segment {
    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;

    &:focus,
    &[data-focused="true"] {
      @apply bg-accent-soft text-accent-soft-foreground;
    }
  }

  .date-input-group__input-container {
    @apply flex flex-1 items-center;
    overflow-x: auto;
    overflow-y: clip;
    scrollbar-width: none;
  }

  .date-input-group__prefix,
  .date-input-group__suffix {
    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
  }
}

DateField.Group CSS 类

• .date-input-group – 根容器样式
• .date-input-group__input – 输入包裹层样式
• .date-input-group__input-container – 用于组合多个输入的滚动容器
• .date-input-group__segment – 单个日期段位样式
• .date-input-group__prefix – 前缀元素样式
• .date-input-group__suffix – 后缀元素样式

DateField.Group 交互状态

• 悬停：:hover 或 [data-hovered="true"]
• 焦点在内：[data-focus-within="true"] 或 :focus-within
• 无效：[data-invalid="true"]（同时与 aria-invalid 同步）
• 禁用：[data-disabled="true"] 或 [aria-disabled="true"]
• 段位聚焦：段位上的 :focus 或 [data-focused="true"]
• 段位占位符：段位上的 [data-placeholder="true"]