Calendar 日历

用于输入与编辑日期的日期组件。单元格随可用空间放大；滑动网格或使用 PageUp / PageDown 切换月份，方向键在日期间移动。

基础用法

@Local date: SparkDate | undefined = SparkDates.today();

SCalendar({ selected: this.date!!, bordered: true })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

多系列

mode: 'multiple'——点按日期即可切换选中。

@Local days: SparkDate[] = [];

SCalendar({ mode: 'multiple', selectedDates: this.days!!, bordered: true })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

范围

SRangeCalendar 足够宽时并排显示两个月，否则显示一个月。

@Local range: SparkDateRange = new SparkDateRange(SparkDates.today(),
  SparkDates.addDays(SparkDates.today(), 6));

// two months side by side when there is room, otherwise one
SRangeCalendar({ range: this.range!!, bordered: true })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

语言与约束

locale、weekStartsOn、minDate / maxDate、disabledDates（此处禁用周末）与 showOutsideDays。

SCalendar({
  selected: this.date!!,
  locale: 'zh',
  weekStartsOn: 1,
  minDate: SparkDates.today(),
  disabledDates: (d: SparkDate) => SparkDates.weekday(d) === 0 || SparkDates.weekday(d) === 6,
  showOutsideDays: false,
  bordered: true
})

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SCalendar

shadcn-vue 的 Calendar（v4 外观，react-day-picker 语义）。

• 每种模式使用一个值属性，让类型保持简单：selected（单选）、selectedDates（多选）、range（范围）。每个都支持 $name 用于 !!，并有一个 on…Change 事件。保持它们未设置，则日历会自行管理选中状态。
• month / defaultMonth：（第一个）显示的月份；onMonthChange 报告翻页。
• 自测量（D11）：日期格的大小随日历获得的宽度变化（32–44vp）；当 numberOfMonths > 1 时，能放下则并排显示月份，否则上下堆叠。cellSize 可固定日期格大小。
• 翻页：头部箭头、网格上的水平滑动、PageUp / PageDown（配合 Shift 则按年）。方向键移动焦点所在的日期（Home / End：周的开始 / 结束），Enter / Space 选中它。
• 动效 key calendar：切换月份时网格滑动并淡入淡出（同一个容器）；选中的日期始终立即切换。
• weekStartsOn：1 表示周一（默认），0 表示周日。locale：'en' | 'zh' 标签。

属性	类型	默认值	说明
mode	SparkCalendarMode SparkCalendarMode = 'single' | 'multiple' | 'range'	'single'
selected!!	SparkDate | undefined	undefined	单选模式
selectedDates!!	SparkDate[]	[]	多选模式
range!!	SparkDateRange	new SparkDateRange()	范围模式
month!!	SparkDate | undefined	undefined	显示的（第一个）月份——该月中的任意一天即可。设置后即为受控。
defaultMonth	SparkDate | undefined	undefined	初始显示的月份（默认：选中项所在的月份，否则为今天所在的月份）。
minDate	SparkDate | undefined	undefined
maxDate	SparkDate | undefined	undefined
disabledDates	SparkDateMatcher | undefined	undefined	额外禁用的日期，例如周末。
required	boolean	false	单选 / 多选：再次点击已选中的日期会保持选中（不取消选择）。
weekStartsOn	SparkWeekStart SparkWeekStart = 0 | 1	1
locale	SparkDateLocale SparkDateLocale = 'en' | 'zh'	'en'
showOutsideDays	boolean	true
numberOfMonths	number	1
cellSize	number | undefined	undefined	固定的日期格大小，单位 vp；undefined 表示根据可用宽度自适应（32–44）。
bordered	boolean	false	卡片外观：rounded-lg border shadow-sm（在弹出框内关闭）。

事件	类型	默认值	说明
onSelectedChange	(d: SparkDate | undefined) => void	() => { }
onSelectedDatesChange	(d: SparkDate[]) => void	() => { }
onRangeChange	(r: SparkDateRange) => void	() => { }
onMonthChange	(m: SparkDate) => void	() => { }

SRangeCalendar

shadcn-vue 的 RangeCalendar：处于范围模式的 {@link SCalendar}；当自身宽度允许（≥ 2 × 7 × 36vp + 间距 + 内边距）时并排显示两个月份，否则只显示一个。

numberOfMonths 可固定月份数量（undefined 表示自动）。

属性	类型	默认值	说明
range!!	SparkDateRange	new SparkDateRange()
month!!	SparkDate | undefined	undefined
defaultMonth	SparkDate | undefined	undefined
minDate	SparkDate | undefined	undefined
maxDate	SparkDate | undefined	undefined
disabledDates	SparkDateMatcher | undefined	undefined
weekStartsOn	SparkWeekStart SparkWeekStart = 0 | 1	1
locale	SparkDateLocale SparkDateLocale = 'en' | 'zh'	'en'
showOutsideDays	boolean	true
numberOfMonths	number | undefined	undefined	undefined 表示能放下则为 2，否则为 1
cellSize	number | undefined	undefined
bordered	boolean	false

事件	类型	默认值	说明
onRangeChange	(r: SparkDateRange) => void	() => { }
onMonthChange	(m: SparkDate) => void	() => { }