日历 · Calendar

选择日期；查看不同选择模式、日期限制及键盘交互。

安装与前置条件

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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
日历 · 交互示例 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

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