使用方法

Calendar 用月历网格选日期。可以选一天，也可以选一段起止日期，并排显示一个月或两个月。打开时先落到指定的月份；没有指定时，落在已选日期或今天，并尽量落进最早和最晚日期之间。

最早日期、最晚日期、返回真值的判断，以及一组返回假值的约束，都会让对应的日子不能选。范围还可以限制最短和最长天数，天数把两端都算进去。周数可以显示在每一行左侧。相邻月份的日期可以留在格子里，但不能选。行数可以按当月缩短，也可以固定六行。一周从哪一天开始，用数字或星期缩写指定。外面也可以拿到一个句柄，直接把月份翻到某一天并聚焦它。

方向键按天或按周移动，到头会翻月，并跳过不能选的日子。Home 和 End 移到这一周里能选的第一天和最后一天。PageUp 和 PageDown 翻一个月。Enter 或空格确认。范围还没选完时，Escape 取消。每个月是一块带月份名字的网格，今天、选中和禁用都能被读屏读到。

基本用法只需要绑定一个日期值：

<script setup lang="ts">
import { Calendar } from '@astryx-vue/core/Calendar'
import { ref } from 'vue'

const date = ref<Date | null>(new Date(2026, 9, 11))
</script>

<template>
  <Calendar v-model="date" label="选择日期" />
</template>

绑定值是原生 Date。通过 min 和 max 限制可选日期范围，通过 isDateDisabled 函数禁用特定日期。月份标题和星期名称跟随当前语言。组件自带文案默认是英文，调用 provideAstryxLocale('zh-CN') 后改为中文。

解剖

部分	说明
日历根	装着月份标题和日期网格的容器。
月份标题	月份、年份，以及切换月份的箭头。dir="rtl" 时箭头会自动对调。
日期网格	七列的日期格，列头是星期名。
日期按钮	网格里的一天，用来选日期。
选中的日期	当前选中的日期，会高亮。范围模式下，还包括起止日期和中间那些天。
今天标记	标在当天上的淡提示，用来帮人定位。

最佳实践

指引	实践
推荐	为业务场景设置合理的日期范围限制。
推荐	使用 isDateDisabled 禁用范围内仍不可选的日期。
推荐	用固定的本地日期构造 Date，避免把带时区的时间戳直接当成日历上的某一天。
避免	在日历上层叠过多的装饰或自定义内容，保持日期网格清晰。

示例

日期限制

Jan 10 – Mar 20, weekdays only

2026年1月

周日

周一

周二

周三

周四

周五

周六

只能选择 2026 年 1 月 10 日到 3 月 20 日之间的工作日。

日期范围

2026-01-10 → 2026-01-20

2026年1月

周日

周一

周二

周三

周四

周五

周六

选择开始和结束日期，中间的日子会高亮。

单日

Selected: 2026-01-15

2026年1月

周日

周一

周二

周三

周四

周五

周六

在月历里选择一天。

两个月

2026-01-25 → 2026-02-05

2026年1月 – 2026年2月

周日

周一

周二

周三

周四

周五

周六

周日

周一

周二

周三

周四

周五

周六

并排显示两个月，用来选择跨月的日期范围。

周数和周起始

February 2026. Adjacent days stay visible but cannot be selected.

2026年2月

周

周一

周二

周三

周四

周五

周六

周日

5

6

7

8

9

可以打开周数、月外日期、按月缩短行数，并把一周的第一天改成周一。

跨度与翻月

At most three days, Sundays excluded. Escape cancels a range that is still open.

2026年1月

周日

周一

周二

周三

周四

周五

周六

这段范围最长三天，周日不可选。六月按钮会把月份翻过去。