# 日期输入 · DateInput

- 页面: https://jiguang132.com/zh/resources/astryx/docs/date-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**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **日期输入 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **日期输入 · 交互示例 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **日期输入 · 交互示例 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **日期输入 · 输入校验 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

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

## Date Input

DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 标签文本。 |
| isLabelHidden | boolean | false | 视觉隐藏标签。 |
| description | string |  | 显示在标签下方的辅助文本。 |
| isOptional | boolean | false | 在标签旁显示"(optional)"指示器。 |
| isRequired | boolean | false | 将字段标记为必填。 |
| isDisabled | boolean | false | 禁用输入框和日历。 |
| disabledMessage | string |  | 说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持输入框可聚焦（仍阻止输入和激活）。请使用此属性，而不是用 Tooltip 包裹已禁用的 DateInput。 |
| value | ISODateString |  | 选中的日期，YYYY-MM-DD 格式。 |
| onChange | (value: ISODateString \| undefined) => void |  | 选中日期变更时调用的回调。 |
| changeAction | (value: ISODateString \| undefined) => void \| Promise<void> |  | 在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。 |
| isLoading | boolean | false | 输入框是否处于加载状态。禁用交互并显示加载指示器。 |
| min | ISODateString |  | 可选择的最早日期（YYYY-MM-DD）。 |
| max | ISODateString |  | 可选择的最晚日期（YYYY-MM-DD）。 |
| dateConstraints | ReadonlyArray<(date: Date) => boolean> |  | 自定义约束函数数组，用于禁用特定日期。 |
| placeholder | string | 'Select a date' | 文本输入框中显示的占位符文本。 |
| size | 'sm' \| 'md' \| 'lg' | 'md' | 输入控件的尺寸。 |
| status | {type: 'warning' \| 'error' \| 'success', message?: string} |  | 错误、警告或成功状态的状态指示对象，附带消息。 |
| statusVariant | 'attached' \| 'detached' \| 'tooltip' | 'attached' | 状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。 |
| labelTooltip | string |  | 通过标签末尾的信息图标显示的提示文本。 |
| hasClear | boolean | false | 有日期值时显示清除按钮。点击后清除日期。 |
| numberOfMonths | 1 \| 2 | 1 | 日历弹出层中同时显示的月份数量。 |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat' | 0 | Astryx 日历表面中每周的起始日。可为数字（0=周日……6=周六）或三字母星期缩写；原生选择器仍由浏览器或操作系统控制。 |
| format | 'date' \| 'date_long' \| 'date_weekday' \| 'system_date' \| ((value: ISODateString) => string) | 'date_long' | 已选日期的显示格式。命名值复用 Timestamp 的格式词汇：'date' 显示 'Mar 21, 2026'，'date_long' 显示 'March 21, 2026'，'date_weekday' 显示 'Wed, Mar 21, 2026'，'system_date' 显示 '2026-03-21'。函数接收 ISO 值并返回自定义字符串。仅作用于已提交的值，不影响正在输入的文本。 |
| presentation | 'popover' \| 'bottom-sheet' \| 'native' \| 'adaptive-bottom-sheet' \| 'adaptive-native' | 'adaptive-native' | 由哪个界面绘制日期选择器。'adaptive-native'（默认）在精细指针上使用 Astryx 日历弹出层、在粗指针上使用浏览器/操作系统选择器（input type=date），且原生控件无法表达值时保留 Astryx 回退；'native' 始终使用浏览器/操作系统选择器且不回退；'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 底部选择器；'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器；仅输入字段的呈现只属于 TimeInput。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用非原生呈现，原生选择器无法表达这些。 |
| nativePicker | 'touch' \| 'always' \| 'never' | 'touch' | 已弃用：请使用 presentation（'touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet'）。仍按已发布行为工作；同时设置时以 presentation 为准。 |
| width | SizeValue |  | 字段宽度（数字按像素处理，字符串按原样使用，例如 “100%”）。统一调整标签、控件和状态消息的宽度。 |
| containerXstyle | StyleXStyles |  | 作用于包含标签、控件和状态的 Field 容器的 StyleX 样式；containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时（InputGroup 内或 horizontal-labels FormLayout 中）不生效，并在开发环境发出警告。 |
| containerClassName | string |  | Field 容器的类名，作用目标同 containerXstyle。 |
| containerStyle | CSSProperties |  | Field 容器的内联样式，作用目标同 containerXstyle。 |
| controlXstyle | StyleXStyles |  | 作用于可见控件框（带边框、包含文本、图标和末端控件的元素，而非原生 input）的 StyleX 样式；controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。 |
| controlClassName | string |  | 可见控件框的类名，作用目标同 controlXstyle。 |
| controlStyle | CSSProperties |  | 可见控件框的内联样式，作用目标同 controlXstyle。 |

### 使用建议

- 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 DateInput'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 date is expected.
- Use min, max, and dateConstraints to restrict selectable dates to valid ranges.
- Use hasClear when the date is optional so the user can reset it.
- Show a loading state with changeAction when the date triggers a server-side save.
- 避免：Use a DateInput for free-form text that does not represent a calendar date.
- 避免：Hide the label without surrounding context that makes the field purpose obvious.
- 避免：Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.
- 避免：Wrap a disabled DateInput 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-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-date-input-toggle-icon",
      "states": [
        "state"
      ]
    }
  ]
}
```

### 组件结构

- **Label**: Text above the input describing what date is expected.
- **Text input**: A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.
- **Calendar icon**: A button that opens the calendar popover for visual date picking.
- **Calendar popover**: A month grid that appears when the icon is clicked or the input is focused.
- **Clear button**: A × button that resets the date value. Shown when hasClear is true and a date is set.
- **Status message**: An error, warning, or success message below the input.

---

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