AtomUI 6.2.4 API 变更示例

AtomUI 6.2.4 恢复 .NET 8 Release 资产，并调整 TimePicker 默认配置、编辑提交行为和弹层几何。虽然版本号是补丁版本，升级仍需复核以下契约，并同步重编译消费方与自定义控件包。

English version: AtomUI 6.2.4 API Change Examples。

快速对照

范围	6.2.3	6.2.4 迁移
时间选择器确认	`IsNeedConfirm` 默认 False	默认 True；需要关闭/失焦提交时显式设置 False。
时间选择器时钟制	默认 `HourClock12`	默认 `HourClock24`；需要 12 小时制时显式设置。
时间列滚动	滚动更新选择	默认仅浏览、不改变候选；需要滚动选择时设 `IsChangeOnScroll=True`。
时间候选提交	无需确认模式下点选可立即确认	点选编辑候选；复核关闭、失焦、切换端点和 Now 的提交时机。
时间弹层几何	标准列宽 40（`PeriodHostWidth` Token 默认 50）、七行	标准列宽 56、新内边距和八行；复核自定义布局与 Token 覆盖。
Release 框架	产品库仅包含 `net10.0`	同时包含 `net8.0` 和 `net10.0`；构建工具仍需要 .NET 10 宿主。
源码构建工具	独立 Build.Tasks、TypeMap.Linker 工程	使用 AtomUI.Toolchain 及其准备入口；更新路径和自定义任务调用。
注册组	版本相关的公共 `ControlPackageGroup_*` 标识	重编译并重新发布裁剪/AOT 产物；不要直接引用生成类型名称。

1. TimePicker 默认值与候选提交

TimePicker 和 RangeTimePicker 现在默认 IsNeedConfirm=True、ClockIdentifier=HourClock24。点选行编辑候选值；确认模式下普通关闭丢弃未确认候选，显式确认提交有效候选。关闭确认时，有效候选在关闭或失焦提交；RangeTimePicker 切换活动端点时还会提交上一端点。

需要保留对应旧模式时，请显式设置：

<atom:TimePicker IsNeedConfirm="False"
                 ClockIdentifier="HourClock12"
                 IsChangeOnScroll="True" />
<atom:RangeTimePicker IsNeedConfirm="False"
                      ClockIdentifier="HourClock12"
                      IsChangeOnScroll="True" />

这些设置不会恢复全部旧事件时机。请复核依赖弹层打开期间立即提交的 TwoWay 绑定、选择事件处理和 Form 观察者。Now 在两种确认模式下均显式提交，并按分钟/秒增量对齐；单值 TimePicker 普通弹层随后关闭；RangeTimePicker 另一端为空时切换到另一端并保持打开，范围完整时才关闭。钉住弹层保持打开。确认、Enter 和有效编辑文本遵守统一提交规则。

新增 IsChangeOnScroll 默认 False：滚轮/触控板仅浏览列表，不改变候选。需要滚动产生候选时设为 True，它不会绕过确认模式。列内焦点滚动在弹层内处理，不再推动外围页面。

2. 时间弹层几何与自定义主题

TimePicker presenter 改为八行。时/分/秒列循环滚动，选中行保持居中且不显示纵向滚动条；AM/PM 列可以显示滚动条。依赖旧七行布局或滚动条行为的自定义弹层尺寸和模板需要复核。

TimePicker Token	旧默认值	新默认值
`ItemWidth`	`40`	`ControlHeightLG * 1.4`，标准主题为 56
`PeriodHostWidth`	`50`	`ItemWidth`
`ItemPadding`	纵向 `UniformlyPaddingXXS`	左侧 `(ItemWidth - ItemHeight) / 2`，其余为 0

标准行高仍为 28，因此标准内边距由 (0,4,0,4) 改为 (14,0,0,0)。应用需要其他尺寸时使用现有具名 Token 覆盖机制，修改列宽时同步重算内边距。Token 名称、既有 Token 枚举整数、Semantic Part 身份和 PART 名称保留。共享 DatePicker 宿主保留自己的高度与提交策略。

3. 恢复 .NET 8 包与 AOT 分流

Release 产品包恢复 lib/net8.0，同时保留 lib/net10.0；Debug 产品构建仍为 net10.0。AtomUI.Toolchain 自身运行于 .NET 10。.NET 8 应用不会增加 .NET 10 部署依赖，但只有 SDK8 的构建环境不能运行随包交付的工具。

目标框架自动决定依赖分析后端：

.NET 8 使用兼容后端，接入官方 ILLink8 或已准入的 ILC8 适配器。
.NET 10 及以上选择匹配的官方 TypeMap 引擎；实际框架 API、工具及能力必须通过校验，未知组合不会回退到 .NET 8。
AtomUIEnableNet8ManagedRegistration、AtomUIEnableNet8NativeRegistration 和 AtomUIEnableConditionalRegistrationBridge 属于未发布试验阶段的覆盖，不是 6.2.3 已发布的开关。自定义脚本应删除这类分流覆盖，使用应用实际目标框架与发布属性。

.NET 8 托管裁剪当前绑定 ILLink8.0.27，并使用 .NET 10 宿主。Native8 当前准入组合为 SDK10.0.300、runtime/ILC8.0.27、full trimming、osx-arm64 工具宿主及 osx-arm64/osx-x64 完整可执行应用。本版不准入 Windows/Linux Native8 消费及 net8 Browser。

现代应用会在官方分析前自动转换受支持的 net8-only 生成输入。当前混合输入要求 SDK10.0.300 和 full trimming，准入覆盖文档所列 net10/osx-arm64 托管与 NativeAOT 组合，以及 net10-browser/browser-wasm。NativeAOT 还要求 runtime10.0.8 和单模块可执行程序。Browser 要求 WasmEnableWebcil=False；桥接后的托管 ReadyToRun/单文件路径尚未准入。精确范围见框架分流和 .NET 8 后端。

请同步升级相关 AtomUI 包、Generator 与第三方生成控件包，重编译预编译消费方，并重新发布裁剪/AOT 应用。公共 ControlPackageGroup_* 名称依赖包含版本的程序集身份，6.2.4 会再次改变；应用不得依赖这些生成名称。迁移说明不代表与 6.2.3 二进制兼容；不得用 ApiCompat suppression 隐藏旧生成组被移除的诊断。

实际 6.2.3 基线比对在 AtomUI.Controls、AtomUI.Desktop.Controls、AtomUI.Toolkits.GalleryBase、AtomUI.Desktop.Controls.DataGrid、AtomUI.Desktop.Controls.ColorPicker 和 AtomUI.Desktop.Controls.Extras 中各发现一个旧生成组移除，其余发布包的 API 比对通过。这六项身份变化保留为明确的不兼容诊断，不生成 suppression；本版要求重编译，不声明与 6.2.3 二进制兼容。包布局仍以同一基线独立审查。

4. 源码构建与自定义任务接入

直接引用旧 src/AtomUI.Build.Tasks/AtomUI.Build.Tasks.csproj 或 src/AtomUI.TypeMap.Linker/AtomUI.TypeMap.Linker.csproj 的脚本，改为唯一 Toolchain 工程：

# 普通构建 worker
dotnet build src/AtomUI.Toolchain/AtomUI.Toolchain.csproj
# worker 和托管发布后端
dotnet build src/AtomUI.Toolchain/AtomUI.Toolchain.csproj -t:BuildManagedToolchain -c Release
# 完整维护者工具准备，包含 ILC8 托管 bundle
dotnet build src/AtomUI.Toolchain/AtomUI.Toolchain.csproj -t:BuildToolchain -c Release

仓库输出移动到 .artifacts/bin/<Configuration>/toolchain/tasks、illink8 和 illink10，各自带 net10 宿主子目录。普通 NuGet 消费方仍使用 tools/net10.0/AtomUI.Build.Tasks.dll，不构建编译器源码。自定义 AtomUIBuildTasksAssembly 覆盖指向 toolchain/tasks/net10.0/AtomUI.Build.Tasks.dll，deps.json、runtimeconfig.json 和 Microsoft.Build.Framework.dll 保持邻接；旧 AtomUITypeMapBackendProject 准备 hook 改为 Toolchain 构建入口。pack --no-build 只消费已准备的工具资产。

包新增框架/net8/bridge targets、统一 AtomUI.Toolchain.Tasks.targets 声明和按版本隔离的后端工具。由包专用 targets 导入它们，不要在自定义接入中仅复制旧版 buildTransitive 文件子集。

直接调用 ValidateRegistrationToolchainTask 时，现在必须传入应用的 TargetFrameworkIdentifier、TargetFrameworkVersion，例如 .NETCoreApp 与 v10.0；随包 targets 已自动传入。源码调用方在工具构建/恢复边界过滤应用 TFM/RID；直接为 Toolchain 传入应用 TargetFrameworks 或 runtime identifier 会被拒绝。

5. ColorPicker 确认功能按需启用

ColorPicker 和 GradientColorPicker 默认仍为 IsNeedConfirm=False。需要确定/取消时显式开启：

<atom:ColorPicker IsNeedConfirm="True" Value="{Binding Color}" />
<atom:GradientColorPicker IsNeedConfirm="True" Value="{Binding Gradient}" />

开启后编辑与清除保持草稿，确认后才提交，取消或普通关闭丢弃草稿。纯色选择器的显式确认优先于 ValueSyncStrategy。使用自定义语言 Catalog 时补齐 Confirm/Cancel 文案。既有 ColorPickerLangResourceKind.EmptyColorText=0 保留，新成员追加在其后；Semantic Part 和 Token 身份保留。

8.7 KiB Raw Permalink Blame History Unescape Escape