# 日期范围 · DateRangeInput

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

## API 与上游详细参考

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

## Date Range Input

DateRangeInput lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | Label text. |
| isLabelHidden | boolean | false | Visually hide the label. |
| description | string |  | Helper text displayed below the label. |
| isOptional | boolean | false | Show an "(optional)" indicator. |
| isRequired | boolean | false | Mark the field as required. |
| isDisabled | boolean | false | Disable the trigger and picker. |
| disabledMessage | string |  | Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateRangeInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs. |
| value * | DateRange \| null |  | Selected date range or null. Import the `DateRange` type from `@astryxdesign/core/DateRangeInput`; it is `{start: ISODateString, end: ISODateString}`. Do NOT redeclare your own DateRange type; use the exported one so TypeScript structurally matches. |
| onChange * | (value: DateRange \| null) => void |  | Callback when the range changes. Called with null on clear. |
| changeAction | (value: DateRange \| null) => void \| Promise<void> |  | Async action fired after onChange. Drives optimistic UI updates via useTransition. |
| isLoading | boolean | false | Whether the input is in a loading state. Disables interaction and shows a spinner. |
| min | ISODateString |  | Minimum selectable date. `ISODateString` is a template literal type (`\`${number}${number}${number}${number}-${number}${number}-${number}${number}\``). Pass a string literal like `"2026-01-28"`, not a runtime string variable. Import it from `@astryxdesign/core/Calendar` or use `as ISODateString` if computing the value dynamically. |
| max | ISODateString |  | Maximum selectable date. Same template literal type as `min`: use a YYYY-MM-DD string literal or cast with `as ISODateString`. |
| dateConstraints | Array<(date: Date) => boolean> |  | Custom constraint functions to disable specific dates. |
| maxRangeSpan | number |  | Maximum days a selected range may span, counting both endpoints (`7` = a 7-day window, start + 6). Once a start is picked, days beyond this distance are disabled so the range cannot stretch past the cap. Rolling window relative to the start; for fixed calendar bounds use `min`/`max`. Constrains selection only; it never rewrites a `value` already wider than the cap (flag that with `status`). |
| minRangeSpan | number |  | Minimum days a selected range must span, counting both endpoints (`2` forbids a single-day range). Once a start is picked, days closer than this are disabled. Clicking the start again commits a one-day range when allowed, or cancels the in-progress selection when the minimum is longer. Defaults to 1 (same-day start and end allowed). |
| presets | Array<DateRangePreset> |  | Preset ranges shown as quick-select options beside the calendar. A preset is disabled when either endpoint violates min, max, or dateConstraints, or when its span violates minRangeSpan or maxRangeSpan. |
| hasClear | boolean | true | Shows a clear button when a range is selected. |
| placeholder | string | 'Select date range' | Placeholder text when no range is selected. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Size of the trigger. |
| status | {type: 'warning' \| 'error' \| 'success', message?: string} |  | Status indicator for error, warning, or success states. |
| statusVariant | 'attached' \| 'detached' \| 'tooltip' | 'attached' | How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon. |
| labelTooltip | string |  | Tooltip text via info icon at label end. |
| numberOfMonths | 1 \| 2 | 2 | Number of months in the calendar. |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat' | 0 | First day of week in the calendar. A number (0 = Sunday to 6 = Saturday) or a three-letter day name. |
| 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 |  | StyleX styles for the Field box around the label, control, and status. containerClassName and containerStyle take a class name and inline styles for the same box. No effect (development warning) where no Field box renders: inside InputGroup (style the group) and in a horizontal-labels FormLayout. |
| controlXstyle | StyleXStyles |  | StyleX styles for the visual control box: the bordered element that holds the text, icons, and end controls, never the native input. controlClassName and controlStyle take a class name and inline styles for the same box. Replaces root xstyle, className, and style, which this component does not accept. |

### 使用建议

- Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the range trigger, the element that is focused and announced. A DOM handler runs after DateRangeInput'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.
- Use presets for common ranges like "Last 7 days" to speed up selection.
- Use min/max to constrain selectable dates to valid ranges.
- Keep hasClear enabled (default) so users can reset the filter.
- Provide clear labels and descriptions so users understand what the range controls.
- 避免：Use DateRangeInput when only a single date is needed; use DateInput instead.
- 避免：Hide the label without surrounding context that makes the purpose obvious.
- 避免：Wrap a disabled DateRangeInput 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-range-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-date-range-input-toggle-icon",
      "states": [
        "state"
      ]
    },
    {
      "className": "astryx-date-range-input-presets"
    },
    {
      "className": "astryx-date-range-input-preset",
      "states": [
        "selected",
        "disabled"
      ]
    }
  ]
}
```

### 组件结构

- **Label**: Text above the trigger describing what date range is expected.
- **Field surface**: Bordered control containing the calendar toggle, range trigger, and end affordances.
- **Trigger button**: A button showing the formatted range or placeholder. Clicking opens the popover.
- **Calendar icon**: A trailing icon that also opens the popover.
- **Calendar popover**: A dual-month calendar grid with range selection and hover preview.
- **Preset sidebar**: A list of preset range options beside the calendar.
- **Preset button**: A quick-select action for one preset range, reflecting current and disabled states.
- **Clear button**: A × button that resets the range to null.
- **Status message**: An error, warning, or success message below the trigger.

---

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