PAYATHON 2026

在 WinUI 3 CalendarDatePicker 中使用阿富汗太阳历(Shamsi)

数据小陈

结论

WinUI 3 没有专门表示“阿富汗太阳历”的 CalendarIdentifier。阿富汗的 Solar Hijri(Shamsi)和伊朗的 Solar Hijri 共用 PersianCalendar 的历法算法,月份名不同,是因为语言/区域数据不同。配置时优先采用:

  • CalendarIdentifier="PersianCalendar"
  • Language="fa-AF"(阿富汗波斯语/达里语;如果目标系统支持,也可以测试 prs-AF,但兼容性要以实际 Windows 版本为准)
  • FlowDirection="RightToLeft"

FlowDirection 只控制布局方向,不负责月份名;CalendarIdentifier 决定历法算法;Language 决定本地化文本和月份名。绑定仍然用 DateTimeOffset?,不需要换成 PersianCalendar 类型。

推荐写法

<CalendarDatePicker
    x:Name="DatePicker"
    Header="Date"
    CalendarIdentifier="PersianCalendar"
    Language="fa-AF"
    FlowDirection="RightToLeft"
    Date="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}"
    PlaceholderText="Select date" />

等价的 C# 配置:

using Microsoft.UI.Xaml;
using Windows.Globalization;

DatePicker.CalendarIdentifier = CalendarIdentifiers.Persian;
DatePicker.Language = "fa-AF";
DatePicker.FlowDirection = FlowDirection.RightToLeft;

ViewModel 不用改:

// ViewModel property
public DateTimeOffset? SelectedDate { get; set; }

CalendarDatePicker.Date 仍然是 DateTimeOffset?。DateTimeOffset 表示的是时间点,不是某个日历类型;日历标识只影响控件如何显示、解析和导航日期。用户选中的 Shamsi 日期会由控件转换成 DateTimeOffset 值,ViewModel 继续接收标准 DateTimeOffset?。

注意事项

  1. 不要写成 CalendarIdentifier="AfghanCalendar" 或类似值,WinUI/WinRT 没有这个标识符。
  2. 只设置 PersianCalendar 时,通常会显示伊朗月份名,例如 Farvardin、Ordibehesht。要得到阿富汗月份名,关键是让控件使用阿富汗区域语言数据。
  3. FlowDirection="RightToLeft" 对波斯语 UI 更自然,但它不是月份名本地化的开关。
  4. 如果设置了 Language="fa-AF" 后仍然显示伊朗月份名,先检查目标 Windows 版本是否包含 fa-AF 的日历月份数据。WinUI 默认模板里的内部 CalendarView 是否会继承外层的 Language,也取决于版本;必要时重新模板化 CalendarDatePicker,并在内部 CalendarView 上显式设置 CalendarIdentifier、Language 和 FlowDirection。
  5. 如果系统区域数据确实无法提供阿富汗月份名,仅靠公开属性没法强制替换原生引擎的月份名。这时可以用 CalendarView + Flyout 自定义下拉,或者在重写模板后把月份标题/月份项文本映射为: حمل, ثور, جوزا, سرطان, اسد, سنبله, میزان, عقرب, قوس, جدی, دلو, حوت 导航和日期计算仍使用 PersianCalendar,数据绑定仍保持 DateTimeOffset?。

最小验证

设置完成后,可以先打印当前区域的月份名做初步验证:

var culture = new System.Globalization.CultureInfo("fa-AF");
var monthNames = culture.DateTimeFormat.MonthNames;

不过,CalendarDatePicker 的原生渲染使用的是 Windows.Globalization/CalendarView 的数据,和 .NET CultureInfo 不完全一样;最终应以目标 Windows 版本上控件的实际显示为准。

备注:内容仅供参考。