AtomUI/docs/Desktop.Controls/Calendar/CalendarUsage.md

Calendar 使用文档

本文档介绍 AtomUI Calendar 控件的各种使用方式。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/CalendarShowCase.axaml

---

前置准备

在 AXAML 中使用 Calendar，需要引入以下命名空间：

xmlns:atom="https://atomui.net"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // Calendar 控件及相关类型

---

1. 基本用法

最简单的日历，显示当前月份，默认允许单范围选择：

<atom:Calendar />

---

2. 选择模式

通过 SelectionMode 属性设置不同的选择行为：

单日选择

<atom:Calendar SelectionMode="SingleDate" />

只允许选择一个日期，点击新日期会取消之前的选择。

单范围选择（默认）

<atom:Calendar SelectionMode="SingleRange" />

允许选择一个连续日期范围：

• 点击第一个日期，然后 Shift+点击第二个日期
• 或按住鼠标拖动选择范围

多范围选择

<atom:Calendar SelectionMode="MultipleRange" />

允许选择多个不连续的日期范围：

• Ctrl+点击追加单个日期
• Ctrl+Shift+点击追加一个范围
• Ctrl+点击已选日期可取消选择

禁止选择

<atom:Calendar SelectionMode="None" />

日历仅供浏览，不允许选择任何日期。

---

3. 今日高亮

默认情况下，今天的日期会显示主色调边框高亮。可通过 IsTodayHighlighted 关闭：

<!-- 默认：今日高亮 -->
<atom:Calendar IsTodayHighlighted="True" />

<!-- 关闭今日高亮 -->
<atom:Calendar IsTodayHighlighted="False" />

---

4. 一周起始日

通过 FirstDayOfWeek 设置一周的起始日：

<!-- 以周一为一周起始日 -->
<atom:Calendar FirstDayOfWeek="Monday" />

<!-- 以周日为一周起始日（默认跟随系统区域） -->
<atom:Calendar FirstDayOfWeek="Sunday" />

---

5. 限制日期范围

通过 DisplayDateStart 和 DisplayDateEnd 限制可显示和可选择的日期：

<!-- 只允许选择 2025 年内的日期 -->
<atom:Calendar DisplayDateStart="2025/01/01" DisplayDateEnd="2025/12/31" />

<!-- 只允许选择从今天开始未来 30 天的日期 -->
<atom:Calendar x:Name="RangeCalendar" />

// Code-behind
RangeCalendar.DisplayDateStart = DateTime.Today;
RangeCalendar.DisplayDateEnd = DateTime.Today.AddDays(30);

---

6. 禁用日期（BlackoutDates）

通过 BlackoutDates 集合标记不可选的日期：

<atom:Calendar x:Name="BlackoutCalendar" />

// Code-behind：禁用所有过去的日期
BlackoutCalendar.BlackoutDates.AddDatesInPast();

// 禁用特定日期范围（如节假日）
BlackoutCalendar.BlackoutDates.Add(
    new CalendarDateRange(new DateTime(2025, 10, 1), new DateTime(2025, 10, 7)));

// 禁用特定单日
BlackoutCalendar.BlackoutDates.Add(
    new CalendarDateRange(new DateTime(2025, 12, 25)));

---

7. 指定初始显示日期

通过 DisplayDate 设置日历初始显示哪个月份：

<!-- 初始显示 2025 年 6 月 -->
<atom:Calendar DisplayDate="2025/06/01" />

---

8. 自定义头部背景

<!-- 头部导航区域使用浅蓝色背景 -->
<atom:Calendar HeaderBackground="#F0F5FF" />

---

9. 禁用状态

<!-- 日历整体禁用，呈灰色调 -->
<atom:Calendar IsEnabled="False" />

---

10. 数据绑定

Calendar 的关键属性支持双向绑定，适合 MVVM 架构：

SelectedDate 绑定

<atom:Calendar SelectionMode="SingleDate"
               SelectedDate="{Binding SelectedDate}" />

<TextBlock Text="{Binding SelectedDate, StringFormat='选中日期: {0:yyyy-MM-dd}'}" />

// ViewModel
public class CalendarViewModel : ReactiveObject
{
    [Reactive]
    public DateTime? SelectedDate { get; set; }
}

DisplayDate 绑定

<atom:Calendar DisplayDate="{Binding CurrentDisplayDate}" />

// ViewModel
[Reactive]
public DateTime CurrentDisplayDate { get; set; } = DateTime.Today;

---

11. 事件处理

监听选中日期变化

<atom:Calendar SelectionMode="SingleDate"
               SelectedDatesChanged="OnSelectedDatesChanged" />

private void OnSelectedDatesChanged(object? sender, SelectionChangedEventArgs e)
{
    foreach (DateTime added in e.AddedItems)
    {
        Console.WriteLine($"新选中: {added:yyyy-MM-dd}");
    }
    foreach (DateTime removed in e.RemovedItems)
    {
        Console.WriteLine($"取消选中: {removed:yyyy-MM-dd}");
    }
}

监听显示日期变化

<atom:Calendar DisplayDateChanged="OnDisplayDateChanged" />

private void OnDisplayDateChanged(object? sender, CalendarDateChangedEventArgs e)
{
    Console.WriteLine($"从 {e.RemovedDate:yyyy-MM} 切换到 {e.AddedDate:yyyy-MM}");
}

监听显示模式变化

<atom:Calendar DisplayModeChanged="OnDisplayModeChanged" />

private void OnDisplayModeChanged(object? sender, CalendarModeChangedEventArgs e)
{
    Console.WriteLine($"从 {e.OldMode} 切换到 {e.NewMode}");
}

---

12. 控制动画行为

<!-- 禁用单元格悬浮过渡动画 -->
<atom:Calendar IsMotionEnabled="False" />

---

键盘导航速查

Calendar 支持完整的键盘操作：

按键	Month 模式	Year/Decade 模式
←/→	前/后一天	前/后一个月/年
↑/↓	前/后一周	前/后一行
PageUp	上一年	上一年/十年
PageDown	下一年	下一年/十年
Home	月初	年首/十年首
End	月末	年末/十年末
Ctrl+↑	切换到 Year 视图	切换到上级视图
Ctrl+↓	—	切换到下级视图
Enter/Space	—	进入选中月/年
Shift+方向键	范围选择	—

---

常见组合模式

预约日期选择器

<StackPanel Spacing="8">
    <TextBlock Text="请选择预约日期：" />
    <atom:Calendar x:Name="BookingCalendar"
                   SelectionMode="SingleDate"
                   SelectedDatesChanged="OnBookingDateChanged" />
</StackPanel>

public BookingView()
{
    InitializeComponent();
    // 禁用过去的日期
    BookingCalendar.BlackoutDates.AddDatesInPast();
}

private void OnBookingDateChanged(object? sender, SelectionChangedEventArgs e)
{
    if (e.AddedItems.Count > 0)
    {
        var date = (DateTime)e.AddedItems[0]!;
        // 处理预约逻辑...
    }
}

日期范围筛选

<StackPanel Spacing="8">
    <TextBlock Text="选择日期范围：" />
    <atom:Calendar x:Name="FilterCalendar"
                   SelectionMode="SingleRange"
                   SelectedDatesChanged="OnFilterRangeChanged" />
</StackPanel>

private void OnFilterRangeChanged(object? sender, SelectionChangedEventArgs e)
{
    if (sender is Calendar calendar && calendar.SelectedDates.Count > 0)
    {
        var startDate = calendar.SelectedDates.Min();
        var endDate = calendar.SelectedDates.Max();
        // 使用 startDate ~ endDate 进行数据筛选...
    }
}