Avalonia 中的
Calendar和
DatePicker（包括
CalendarDatePicker）是两个常用但用途不同的日期控件：前者是纯日历视图，后者是带文本输入 + 下拉日历的复合控件。正确使用需注意模板、样式、绑定和常见陷阱。
Calendar 基础用法与限制
Calendar是一个只读日历面板，不自带输入框，适合嵌入仪表板或作为独立日历展示： 基本写法：
<calendar selectionmode="SingleDate"></calendar>，支持单选、多选、范围选等模式 默认显示当前月，可通过
DisplayDate属性指定初始显示日期 禁用日期用
BlackoutDates集合，例如：
<calendar.blackoutdates><calendardaterange start="2025-12-25" end="2026-01-01"></calendardaterange></calendar.blackoutdates>它不自动响应日期变更事件，需监听
SelectedDatesChanged或绑定
SelectedDate
DatePicker / CalendarDatePicker 正确配置
Avalonia 官方推荐的是
CalendarDatePicker（常简称为 DatePicker），它由文本框 + 下拉弹窗组成，但默认行为较“轻”，需手动补全关键配置才能稳定工作： 基础使用：
<calendardatepicker selecteddate="{Binding MyDate}"></calendardatepicker>，必须绑定 SelectedDate才能双向生效 日期格式显示依赖
DisplayFormat（仅影响文本框内显示），如：
DisplayFormat="yyyy-MM-dd"；若未设，可能显示为系统默认短格式（如 “12/15/2025”） 下拉弹窗默认只显示月份视图，首次点击后需再点年份才能切换——可通过设置
DisplayMode="Year"或在代码中预设 弹窗关闭逻辑有缺陷：点击外部区域不会自动关闭，需自行处理焦点丢失或添加遮罩层拦截
Ursa 主题 DateTimePicker 快速上手
如果需要年月日 + 时分秒一体化选择，官方
CalendarDatePicker不支持时间部分，此时推荐 Ursa 主题的
DateTimePicker： 先安装 NuGet 包：
Semi.Avalonia和
Ursa.Avalonia在
App.axaml中声明命名空间：
xmlns:ursa="https://irihi.tech/ursa"关键属性不能省略：
DisplayFormat（文本显示）、
PanelFormat（弹窗内格式）、
Watermark（占位提示） 示例：
<datetimepicker displayformat="yyyy-MM-dd HH:mm:ss" panelformat="HH:mm:ss" watermark="请选择完整时间"></datetimepicker>注意：漏掉
PanelFormat可能导致时间选择器顺序错乱（如秒在前、时在后）
自定义与避坑要点
遇到样式不符、关闭异常或输入失效等问题，多数源于底层实现细节：
空格键在日历弹窗中被拦截（用于关闭弹窗），导致内部TextBox无法输入空格——需重写
Calendar_KeyDown或改用其他触发方式 动态修改
MonthFormat不刷新界面，必须同步触发
SelectedDate更新（哪怕赋值自身）才能重绘 重绘模板时，务必复制完整默认
ControlTemplate，尤其注意
Popup的
IsOpen绑定和关闭逻辑，原生控件缺少外部点击关闭机制
Width="Auto"在 Avalonia 中非法，设为
Width="{Binding ActualWidth, ElementName=Parent}" 或直接给固定值更稳妥
