AtomUI/docs/releases/6.2.3-api-changes.zh-CN.md

AtomUI 6.2.3 API 变更示例

虽然版本号是补丁版本，AtomUI 6.2.3 仍包含日期上下文、旧 CalendarView、主题和生成 Token 的破坏性变更。本文说明从 6.2.2 升级的方法。消费方和自定义主题需要一起重新编译，仅替换包二进制不足以完成迁移。

English version: AtomUI 6.2.3 API Change Examples。

快速对照

范围	6.2.2	6.2.3 迁移
Calendar 单元格类型	CalendarCellType.Date/Month	DateViewerCellType.Date/Month；更新 C# 与 AXAML 类型引用。
Calendar 上下文	八个字段的位置记录 CalendarCellContext	继承 DateViewerCellContext；更新构造、具名参数、派生记录和解构。
旧 Picker 命名空间	AtomUI.Desktop.Controls.CalendarView 下的公共类型	使用独立 DateViewer/RangeDateViewer 及其公共上下文、范围和事件。
事件扩展	可继承的 ChoosingStatusEventArgs 和旧 DateSelectedEventArgs	当前两个事件参数类均已密封；以组合代替继承。
日期面板模板	CalendarView/CalendarItem/Button 主题和 PART_CalendarView	共享 Viewer 主题及 PART_DateViewer / PART_RangeDateViewer；重建完整自定义模板。
Semantic Parts	旧 Header/Body/Content/Cell 目标和 marker 路由	重新编译生成的专用 Style，并按新目标契约检查 Setter。
DatePicker Token	Cell/Header/Panel Token 与 RangeCalendarSpacing	DateViewer 拥有日期面板资源；Picker 间距更名为 RangePanelSpacing。
生成注册组	版本相关的公共 ControlPackageGroup_* 类型	重新编译消费方并重新发布裁剪/AOT 产物；不直接引用生成组名。
生成 Token 枚举	原 Calendar/DatePicker 整数常量	重新编译消费方，使用具名成员，迁移已序列化的整数值。

1. 迁移 Calendar 单元格上下文

CalendarCellType 已移除。CalendarCellContext 现在继承 DateViewerCellContext，构造函数接收 DateViewerCellType 和可选的 isFocused 参数。LunarCalendarCellContext 同样改用 DateViewerCellType。

升级前：

var context = new CalendarCellContext(date, DateTime.Today,
    CalendarCellType.Date, "5", false, true, false, false);

升级后：

var context = new CalendarCellContext(date, DateTime.Today,
    DateViewerCellType.Date, "5", false, true, false, false);

旧位置记录的构造参数采用 PascalCase；新 Calendar 构造参数使用 camelCase（value、today、cellType、displayValue、isToday、isInView、isSelected、isDisabled、isFocused）。请更新具名参数和派生记录的构造函数。记录继承变化也改变生成的克隆、相等性和打印方法的 override 元数据；消费方派生记录应重新编译，不复用旧二进制。旧八输出生成 Deconstruct 已移除；改为读取具名属性，或使用继承的十五字段上下文结构。单元格属性改为继承成员，依赖旧声明类型的二进制必须重新编译。

比较 CalendarCellType 的强类型 AXAML 表达式也需要改用 DateViewerCellType。新枚举插入了 Week：旧 CalendarCellType.Month 的值为 1，新 DateViewerCellType.Month 的值为 2。存储的单元格类型整数必须先按旧成员名称映射，不能直接强转为新枚举。Calendar 的 Value、Mode、单元格/Header 模板和业务事件仍由 Calendar 拥有，普通值绑定不迁移到内嵌 Viewer。

2. 替换旧 CalendarView 公共类型和事件子类

AtomUI.Desktop.Controls.CalendarView 下的以下公共类型已移除：

• CalendarMode（旧 Month/Year/Decade 面板枚举）。
• CalendarDateRange（旧非空范围类型）。
• DateSelectedEventArgs 与 RangeDateSelectedEventArgs。

独立日期面板接入请使用 DateViewer 或 RangeDateViewer。选择粒度使用 DateViewerSelectionUnit，当前面板类型使用 DateViewerPanelKind。旧 Month/Year/Decade 面板浏览分别对应 Date/Month/Year 面板。面板类型是只读状态，应通过 DisplayDate、选择配置和 Header 导航控制浏览，不再赋值给已删除的显示模式 API。

新范围 Viewer 使用原子 DateViewerRange 值：

var viewer = new RangeDateViewer
{
    SelectionUnit = DateViewerSelectionUnit.Date,
    Value = new DateViewerRange(new DateTime(2026, 10, 5), new DateTime(2026, 10, 9))
};
viewer.Selected += (_, args) => Console.WriteLine(args.Value);

Viewer 选择事件使用 DateViewerSelectedEventArgs / RangeDateViewerSelectedEventArgs，值变更使用对应的 ValueChanged 参数。被移除的 RangeDateSelectedEventArgs.IsFixedRange 不对应新 Viewer 的确认标志：Picker 拥有确认流程，Viewer 报告面板选择。应用自己的确认状态应保留在应用模型中。

DateSelectedEventArgs 现在位于 AtomUI.Desktop.Controls，并已密封。AtomUI.Desktop.Controls.ChoosingStatusEventArgs 也已密封。请移除子类，将附加状态放在应用模型或包装对象中。普通应用应消费 DatePicker/RangeDatePicker 的公共 owner 事件和值，不依赖内部 Presenter 事件。Calendar 使用的另一个 AtomUI.Desktop.Controls.CalendarMode 和 CalendarDateRange 契约仍然保留。

3. 重建自定义日期模板和 Semantic Part 样式

旧 CalendarView、CalendarViewCell、LunarCalendarViewCell、CalendarItem、CalendarButton、CalendarDayButton、HeadTextButton、范围和双月主题资产已移除。带时间和双月 Picker Presenter 变体已合并。删除自定义资源包含和对这些资产的引用，包括编译器生成的 AXAML Build/Populate 方法，并按当前 Viewer 主题重建。

Calendar 日期模板部件从 PART_CalendarView 改为 PART_DateViewer。Picker Presenter 组合 PART_DateViewer 或 PART_RangeDateViewer、时间控件和 Picker Footer。只改部件名称无法迁移完整模板；应参考当前组合结构并保留绑定和资源 owner。详见 Calendar 实现和 DatePicker 实现。

Semantic Part 名称仍可识别，但目标契约和路由发生变化：

部件	原目标	当前目标
Calendar / LunarCalendar body	DockPanel	Panel
Calendar / LunarCalendar item、itemContent	Calendar Cell 直接拓扑	共享 Viewer/Panel/Cell 模板；生成路由跨越嵌套 owner。
Picker popup.header	Border	TemplatedControl；RangeDatePicker Header 为 Multiple。
Picker popup.body	UniformGrid	Panel
Picker popup.content	Grid	TemplatedControl
Picker popup.cell	Button	TemplatedControl

删除依赖 .semantic-popup-header、.semantic-popup-body、.semantic-popup-content、.semantic-item 或旧模板层次的原始选择器。重新编译并声明式应用生成的专用 Style：

<atom:DatePicker xmlns="https://github.com/avaloniaui"
                 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                 xmlns:atom="https://atomui.net">
    <atom:DatePicker.Styles>
        <Style Selector="atom|DatePicker">
            <atom:DatePickerPopupCellStyle x:SetterTargetType="TemplatedControl">
                <Setter Property="Background" Value="AliceBlue" />
            </atom:DatePickerPopupCellStyle>
        </Style>
    </atom:DatePicker.Styles>
</atom:DatePicker>

这里 atom 对应 xmlns:atom="https://atomui.net"。原 Button、Grid 或 Border 特有属性可能已不适用，应逐项检查 Setter。支持的定制表面见 DatePicker Semantic Part 契约和 Calendar Semantic Part 契约。

4. 迁移生成 Token 与资源所有权

DatePicker 现在只拥有 PanelContentPadding、ButtonsPanelMargin 和 RangePanelSpacing。以下旧日期面板名称对应的 DatePicker TokenKind/TokenKey 成员和资源入口已移除：

CellHoverBg、CellActiveWithRangeBg、CellHoverWithRangeBg、CellBgDisabled、CellRangeBorderColor、CellHeight、CellWidth、CellLineHeight、CellMargin、ItemPanelMinWidth、MonthViewMinWidth、ItemPanelMinHeight、TextHeight、YearMonthCellWidth、WithoutTimeCellHeight、DayTitleHeight、HeaderMargin、HeaderPadding、RangeCalendarSpacing。

迁移示例：

原 DatePicker 资源	当前定制方式
CellHoverBg	DateViewer CellHoverBg
CellActiveWithRangeBg	DateViewer CellRangeBg
CellHeight、CellWidth	DateViewer 同名成员
YearMonthCellWidth	DateViewer PeriodCellWidth
RangeCalendarSpacing	DatePicker RangePanelSpacing
其他移除的尺寸、Header 或状态颜色	按当前 DateViewer 几何、共享 Token 和专用 Semantic Style 重建，不存在通用一对一别名。

局部覆盖应作用于真实日期面板资源 owner；旧 Picker 资源不再影响共享面板。详见 DateViewer Token和 DatePicker Token。

Calendar 新增 WeekHeaderHeight 和 WeekHeaderPadding，插入位置改变后续生成 Calendar Token 成员的整数值；DatePicker Token 的移除和重排也改变生成常量。请重新编译所有 Token 消费方。不要将枚举整数作为稳定标识；升级前根据 6.2.2 的成员名称迁移已序列化的数值。

5. 重新编译生成注册的消费方

AtomUI.Controls、AtomUI.Desktop.Controls、AtomUI.Toolkits.GalleryBase、AtomUI.Desktop.Controls.DataGrid、AtomUI.Desktop.Controls.ColorPicker 和 AtomUI.Desktop.Controls.Extras 中的公共 ControlPackageGroup_* 标识发生变化。TypeMap writer 根据包含版本的包程序集标识生成这些名称。比对 6.2.3 产物时，ApiCompat 检测到六个旧 6.2.2 注册组类型移除。

保留普通 UseAtomUI() 和包注册调用，同步升级相关包，并重新编译消费生成注册元数据的应用和自定义控件包。重新发布 trimming/NativeAOT 产物，使链接过程使用当前注册组。对 AtomUI.Generated.*.ControlPackageGroup_* 的直接引用应改为受支持的包注册 API，旧哈希名称没有稳定别名。注册机制仍为 TypeMap；这是生成公共标识的兼容性变化，不是另一套注册系统。

6. 验证升级

1. 同步升级 AtomUI 包并重新编译应用和自定义控件包。
2. 更新上下文、旧命名空间引用、事件子类、模板资产和 Token 覆盖。
3. 验证单值/范围/带时间 Picker、关闭/重开确认、反向预览、语言切换、Calendar/LunarCalendar 模板和范围条。
4. 在真实应用中验证专用 Semantic Style、主题切换、键盘焦点和指针输入。
5. 重新发布 trimming/NativeAOT 应用，并在产物中实际使用日期控件。

产品 TFM 仍为 net10.0，Avalonia 仍为 12.1.3，.NET 10 SDK 要求与 6.2.2 一致。以 6.2.2 为基线的包 API 校验预期会发现上述有意破坏，不能抑制这些诊断或宣称兼容性通过。包布局与 NativeAOT 检查属于独立发布门禁。

发布门禁审计记录

20 个 Release 包均已生成，布局与 6.2.2 一致。ApiCompat 报告 11 个移除类型（CP0001）、52 个移除成员（CP0002）、一个新增密封类型（CP0009）、六个变化的枚举常量（CP0011）和四个虚成员变化诊断（CP0012）。移除类型包含五个日期类型和六个生成注册组。移除成员涵盖日期上下文构造/访问器/解构、DatePicker Token 和旧生成 AXAML 入口方法。虚成员诊断对应 CalendarCellContext 记录继承变化，密封诊断对应 ChoosingStatusEventArgs。未报告无法解析引用的诊断。这些兼容性错误完整保留且没有抑制；发布不能宣称与 6.2.2 二进制兼容。