日期时间输入 · DateTimeInput

组合日期与时间输入。

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 日期时间输入 · 综合展示 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.

使用建议

• 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

{
  "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。