# DateField 日期字段 · HeroUI

> 基于 React Aria DateField 的日期输入字段，包含标签、说明与校验。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/components/date-field
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 引入

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

### 用法


> 示例 `date-field-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 组件结构

```tsx
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** 将标签、日期输入、说明与错误信息组合为单个无障碍组件。

### 带描述


> 示例 `date-field-with-description`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 必填字段


> 示例 `date-field-required`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 校验

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


> 示例 `date-field-invalid`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 带校验

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


> 示例 `date-field-with-validation`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 粒度


> 示例 `date-field-granularity`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 受控

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


> 示例 `date-field-controlled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 禁用状态


> 示例 `date-field-disabled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 带图标

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


> 示例 `date-field-with-prefix-icon`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


> 示例 `date-field-with-suffix-icon`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


> 示例 `date-field-with-prefix-and-suffix`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 全宽


> 示例 `date-field-full-width`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 变体

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

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


> 示例 `date-field-variants`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 在 Surface 中

在 [Surface](/systems/heroui/docs/components/surface) 内使用时，请在 `DateField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。


> 示例 `date-field-on-surface`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 表单示例

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


> 示例 `date-field-form-example`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


### 自定义渲染函数


> 示例 `date-field-custom-render-function`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/date-field


## 样式

### 传入 Tailwind CSS 类

```tsx
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` 类即可自定义容器样式。

```css
@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](/systems/heroui/docs/components/label)、[Description](/systems/heroui/docs/components/description)、[FieldError](/systems/heroui/docs/components/field-error)）拥有各自的 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](https://react-aria.adobe.com/DateField.md) 的全部 props。

#### Base Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `children` | `React.ReactNode \| (values: DateFieldRenderProps) => React.ReactNode` | - | 子组件（Label、DateField.Group 等）或渲染函数。 |
| `className` | `string \| (values: DateFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 |
| `style` | `React.CSSProperties \| (values: DateFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持渲染 prop。 |
| `fullWidth` | `boolean` | `false` | 日期字段是否占满容器宽度。 |
| `id` | `string` | - | 元素的唯一 id。 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

#### Value Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `value` | `DateValue \| null` | - | 当前值（受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
| `defaultValue` | `DateValue \| null` | - | 默认值（非受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
| `onChange` | `(value: DateValue \| null) => void` | - | 值变化时触发的事件处理函数。 |
| `placeholderValue` | `DateValue \| null` | - | 影响占位符格式的占位日期。 |

#### Validation Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `isRequired` | `boolean` | `false` | 是否在提交表单前要求用户输入。 |
| `isInvalid` | `boolean` | - | 值是否无效。 |
| `minValue` | `DateValue \| null` | - | 用户可选择最早日期。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
| `maxValue` | `DateValue \| null` | - | 用户可选择最晚日期。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 |
| `isDateUnavailable` | `(date: DateValue) => boolean` | - | 针对每个日期调用；返回 true 表示该日期不可用。 |
| `validate` | `(value: DateValue) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 |

#### Format Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `granularity` | `Granularity` | - | 显示的最小单位。日期默认为 `"day"`，时间默认为 `"minute"`。 |
| `hourCycle` | `12 \| 24` | - | 以 12 或 24 小时制显示时间；默认由语言环境决定。 |
| `hideTimeZone` | `boolean` | `false` | 是否隐藏时区缩写。 |
| `shouldForceLeadingZeros` | `boolean` | - | 是否始终为月、日、小时等显示前导零。 |

#### State Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `isDisabled` | `boolean` | - | 是否禁用输入。 |
| `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 |

#### Form Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `name` | `string` | - | 输入元素的 name，用于 HTML 表单提交；以 ISO 8601 字符串提交。 |
| `autoFocus` | `boolean` | - | 是否在渲染后自动聚焦该元素。 |
| `autoComplete` | `string` | - | 输入应提供的自动完成类型。 |

#### Accessibility Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `aria-label` | `string` | - | 无可见标签时的无障碍标签。 |
| `aria-labelledby` | `string` | - | 标注该字段的元素 id。 |
| `aria-describedby` | `string` | - | 描述该字段的元素 id。 |
| `aria-details` | `string` | - | 包含额外详情的元素 id。 |

### 组合组件

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 中直接组合使用：

```tsx
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`](https://react-aria.adobe.com/internationalized/date/) 中的类型：

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

示例：

```tsx
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`](https://react-aria.adobe.com/internationalized/date/) 进行解析、运算与类型定义。更多类型与函数见 [Internationalized Date 文档](https://react-aria.adobe.com/internationalized/date/)。

### DateFieldRenderProps

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

| Prop | 类型 | 描述 |
|------|------|------|
| `isDisabled` | `boolean` | 字段是否禁用。 |
| `isInvalid` | `boolean` | 字段当前是否无效。 |
| `isReadOnly` | `boolean` | 字段是否只读。 |
| `isRequired` | `boolean` | 字段是否必填。 |
| `isFocused` | `boolean` | 字段是否聚焦。 |
| `isFocusWithin` | `boolean` | 是否有子元素聚焦。 |
| `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 |

### DateField.Group Props

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
| `fullWidth` | `boolean` | `false` | 日期输入组是否占满容器宽度。 |
| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |

### DateField.Input Props

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
| `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 |

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

### DateField.Segment Props

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `segment` | `DateSegment` | - | 来自 DateField.Input 渲染函数的 `DateSegment` 对象。 |
| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |

### DateField.InputContainer Props

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 滚动容器中的内容（通常为多个 `DateField.Input`）。 |

### DateField.Prefix Props

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 |

### DateField.Suffix Props

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 后缀插槽中要显示的内容。 |

## DateField.Group 样式

### 自定义组件类

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

```css
@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"]`

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt