# 日期时间输入 · DateTimeInput

- 页面: https://jiguang132.com/zh/resources/astryx/docs/date-time-input
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

组合日期与时间输入。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **日期时间输入 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **日期时间输入 · 输入校验 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Date Time Input

DateTimeInput combines date and time selection in one field. With presentation="adaptive-native" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. presentation="native" uses both native controls on every pointer; presentation="adaptive-bottom-sheet" keeps Astryx's own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers; "popover" and "bottom-sheet" force one Astryx surface on every pointer. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 标签文本。 |
| isLabelHidden | boolean | false | 视觉隐藏标签。 |
| description | string |  | 显示在标签下方的辅助文本。 |
| isOptional | boolean | false | 在标签旁显示"(optional)"指示器。 |
| isRequired | boolean | false | 将字段标记为必填。 |
| isDisabled | boolean | false | 禁用输入框和选择器。 |
| disabledMessage | string |  | 说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持日期和时间字段可聚焦（仍阻止输入和激活）。请使用此属性，而不是用 Tooltip 包裹已禁用的 DateTimeInput。 |
| value | ISODateTimeString |  | 选中的日期时间，ISO 8601 格式。 |
| onChange * | (value: ISODateTimeString \| undefined) => void |  | 选中日期时间变更时调用的回调。 |
| changeAction | (value: ISODateTimeString \| undefined) => void \| Promise<void> |  | 在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。 |
| isLoading | boolean | false | 输入框是否处于加载状态。禁用交互并显示加载指示器。 |
| min | ISODateTimeString |  | 可选择的最早日期时间。同时约束日期和时间选择。 |
| max | ISODateTimeString |  | 可选择的最晚日期时间。同时约束日期和时间选择。 |
| dateConstraints | Array<(date: Date) => boolean> |  | 自定义约束函数数组，用于禁用特定日期。 |
| hasSeconds | boolean | false | 在时间部分包含秒。即使 nativePicker 选择原生界面，也会保留 Astryx 时间字段，因为 iOS 没有秒滚轮。 |
| hourFormat | '12h' \| '24h' | '12h' | 控制显示格式。'12h' 显示 AM/PM；'24h' 使用 24 小时制。 |
| timeIncrement | 1 \| 5 \| 10 \| 15 \| 30 | 1 | Astryx 可输入时间字段中箭头键的分钟步长。非默认值会在 nativePicker 模式下保留 Astryx 时间字段，因为 iOS 将原生 step 视为验证规则，而不是选择器步长。Astryx 触摸面板使用滚轮。 |
| timeOptionInterval | 5 \| 10 \| 15 \| 30 \| 60 |  | Minute cadence for the preset-time combobox on Astryx's fine-pointer time field. Setting it keeps that Astryx time field even in nativePicker modes because the OS picker has no equivalent preset list. The Astryx touch sheet uses wheels. |
| hasClear | boolean | false | 当有值时显示清除按钮。 |
| placeholder | string | 'Select a date' | 日期部分未选择日期时显示的占位符文本。 |
| timePlaceholder | string | 'Select a time' | 时间部分未选择时间时显示的占位符文本。在触摸设备上，这会显示在未选择时间的闭合时间段中。 |
| timeLabel | string |  | 时间部分的无障碍标签。默认为“{label} time”，与字段标签关联且可本地化。 |
| size | 'sm' \| 'md' \| 'lg' | 'md' | 输入控件的尺寸。 |
| status | {type: 'warning' \| 'error' \| 'success', message?: string} |  | 错误、警告或成功状态的状态指示对象，附带消息。 |
| labelTooltip | string |  | 通过标签末尾的信息图标显示的提示文本。 |
| numberOfMonths | 1 \| 2 | 1 | Astryx 指针日历弹出层中同时显示的月份数量。原生日期控件和移动触摸面板会忽略此属性；触摸面板的日期部分一次显示一个可滑动月份。 |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat' | 0 | Astryx 日历中每周的起始日。可为数字（0=周日……6=周六）或三字母星期缩写。原生日期控件会忽略此属性。 |
| presentation | 'popover' \| 'bottom-sheet' \| 'native' \| 'adaptive-bottom-sheet' \| 'adaptive-native' | 'adaptive-native' | 选择由哪些界面绘制日期和时间选择器。'adaptive-native'（默认）在精细指针上使用 Astryx 文本字段与弹出层、在粗指针上使用浏览器/操作系统控件，并按段回退：hasSeconds、非默认 timeIncrement 或 timeOptionInterval 会保留 Astryx 时间字段；'native' 始终使用两个原生控件且不回退；'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 协调底部面板；'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器；仅文本字段的呈现只属于 TimeInput。需要 numberOfMonths、weekStartsOn 或可见 dateConstraints 行为时请使用非原生呈现。约束会在提交时执行，min/max 作为提示传给原生控件。hourFormat 格式化关闭状态的时间，而操作系统选择器遵循用户区域设置。 |
| nativePicker | 'touch' \| 'always' \| 'never' | 'touch' | 已弃用：请使用 presentation（'touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet'）。仍按已发布行为工作；同时设置时以 presentation 为准。 |
| width | SizeValue |  | Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned. |
| containerXstyle | StyleXStyles |  | 作用于包含标签、控件和状态的 Field 容器的 StyleX 样式；containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时（InputGroup 内或 horizontal-labels FormLayout 中）不生效，并在开发环境发出警告。 |
| controlXstyle | StyleXStyles |  | 作用于可见控件框（容纳带边框的日期与时间分段及其图标和末端控件的行，而非原生 input）的 StyleX 样式；controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。 |

### 使用建议

- Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateTimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.
- Provide clear labels and descriptions so users understand what datetime is expected.
- Use min and max to restrict selectable datetimes to valid ranges.
- Use hasClear when the datetime is optional so the user can reset it.
- Choose the hour format (12h or 24h) that matches your audience's locale.
- 避免：Use DateTimeInput when only a date is needed; use DateInput instead.
- 避免：Use DateTimeInput when only a time is needed; use TimeInput instead.
- 避免：Hide the label without surrounding context that makes the field purpose obvious.
- 避免：Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-date-time-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-date-time-input-date-segment",
      "visualProps": [
        "size",
        "status"
      ]
    },
    {
      "className": "astryx-date-time-input-time-segment",
      "visualProps": [
        "size",
        "status"
      ]
    },
    {
      "className": "astryx-date-time-input-toggle-icon",
      "states": [
        "state"
      ]
    },
    {
      "className": "astryx-date-time-input-clock-icon"
    },
    {
      "className": "astryx-date-time-input-time-listbox"
    },
    {
      "className": "astryx-date-time-input-time-option"
    }
  ]
}
```

### 组件结构

- **Label**: Text above the input describing what datetime is expected.
- **Segment row**: The unbordered layout row that holds the two bordered segments and wraps them when its container is narrow.
- **Date input**: A typed date field with calendar popover on the fine-pointer Astryx surface, a real input type=date in native modes, or a read-only segment opening the Astryx touch sheet under presentation="adaptive-bottom-sheet" on a coarse pointer.
- **Calendar icon**: A button that opens the active date surface: the platform picker, Astryx calendar popover, or Astryx touch sheet.
- **Date picker**: The browser/OS picker in native modes, an Astryx month-grid popover on a fine pointer, or the Date panel of the Astryx bottom sheet on a coarse pointer with presentation="adaptive-bottom-sheet".
- **Time input**: A real input type=time for the default minute-precision native mode, a text/combobox time field when seconds, custom increments, or preset options are requested, or a read-only segment opening accessible time wheels under presentation="adaptive-bottom-sheet" on a coarse pointer.
- **Clock icon**: The time glyph shown as a leading identifier on the Astryx pointer field and as the picker affordance in native and touch-sheet time segments.
- **Time options popover**: A list of preset times at the timeOptionInterval cadence. Setting the prop retains Astryx's text/combobox time field even when nativePicker otherwise selects native controls; the Astryx touch sheet uses wheels instead.
- **Time option**: One selectable preset time in the optional time-options popover.
- **Clear button**: A × button that resets the datetime value.
- **Status message**: An error, warning, or success message below the inputs.


## 示例的 StyleX 编译要求

DateTimeInputWithValidation 包含 stylex.create，需要配置 StyleX 源码编译流程。仅引入 Core 预编译 CSS 不足以运行这些示例样式，复制前请阅读[样式与 Tailwind](/resources/astryx/docs/styling)。

---

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