# 日历 · Calendar

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

## API 与上游详细参考

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

## Calendar

Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| mode | 'single' \| 'range' | 'single' | 选择模式。 |
| value | ISODateString \| DateRange \| null |  | 受控选中值。null 表示没有选中值；省略或传入 undefined 为非受控模式。 |
| defaultValue | ISODateString \| DateRange |  | 非受控默认值。 |
| onChange | Function |  | 选择回调函数。 |
| numberOfMonths | 1 \| 2 | 1 | 显示的月份数量。 |
| min | ISODateString |  | 可选择的最早日期。 |
| max | ISODateString |  | 可选择的最晚日期。 |
| dateConstraints | Array<(date: Date) => boolean> |  | 自定义约束函数。 |
| maxRangeSpan | number |  | 范围模式：范围最多可跨越的天数，含首尾两端（7 = 7 天窗口）。选定起始日后限制窗口大小。 |
| minRangeSpan | number |  | 范围模式：范围最少需跨越的天数，含首尾两端（2 表示禁止单日范围）。再次点击开始日期时，若最小范围允许则提交单日范围；否则取消进行中的选择。默认为 1。 |
| focusDate | ISODateString |  | 受控可见月份。未设置时，日历打开时显示已选日期所在月份；若无选中值，则显示今天，并将其限制在 min/max 范围内。 |
| onFocusDateChange | (focusDate: ISODateString) => void |  | 导航回调函数。 |
| handleRef | React.Ref<CalendarHandle> |  | 日历导航的命令式句柄，包括 navigateTo()。 |
| hasOutsideDays | boolean | true | 显示相邻月份的日期。 |
| hasWeekNumbers | boolean | false | 显示 ISO 周数。 |
| hasVariableRowCount | boolean | false | 可变行数与固定 6 行网格。 |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat' | 0 | 每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。 |

### 使用建议

- Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.
- Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.
- Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.
- Show two months side by side when the user frequently selects dates that span a month boundary.
- 避免：Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.
- 避免：Disable large blocks of dates without context. The user should understand why dates are unavailable.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-calendar",
      "visualProps": [
        "mode"
      ]
    },
    {
      "className": "astryx-calendar-nav",
      "visualProps": [
        "nav"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-calendar-day",
      "states": [
        "selected",
        "today",
        "disabled",
        "in-range",
        "marker"
      ]
    }
  ]
}
```

### 组件结构

- **Calendar root**: The container that holds the month header and the day grid.
- **Month header**: The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".
- **Day grid**: A 7-column grid of days with column headers for the day names.
- **Day button**: One day in the grid; the control a date is picked with.
- **Selected day**: The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.
- **Today marker**: A subtle indicator on the current date for orientation.

---

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