AtomUI OSS 6.2.10 版本发布

AtomUI OSS 6.2.10 于 2026-10-30 发布，面向所有使用 AtomUI 桌面控件库的 .NET / Avalonia 应用。自上一篇发布文章（6.2.6）以来， 6.2.7 至 6.2.10 四个版本累积发布，本篇一并汇总这些更新。

本次更新的主线是 动效系统重构：基于 Actor 的动效库被帧驱动、直接作用于控件的动效取代，布局动效只失效动画中的视口，子菜单、Expander、Collapse、TreeView 展开不再逐帧重绘整窗。同时，Windows 默认优先 RedirectionSurface 以消除 live resize 错帧，窗口型 Popup 的阴影区域在四大桌面平台对指针输入穿透。动效公共 API 在本版发生破坏性变更，升级前请阅读 迁移指南 。

本版亮点

动效直接作用于控件：移除 Actor 包装，动效由帧驱动并写入合成层变换通道，反向请求从当前呈现值连续接续；新增 SequenceMotion 与 ParallelMotion 组合动效。布局动效不再整窗重绘：只失效动画中的视口、只重新排列尺寸变化的祖先，子菜单、Expander、Collapse、TreeView 展开的每帧开销大幅下降；模态遮罩与抽屉动画期间合成缓存窗口内容，实测 Wayland Gallery 每帧渲染线程耗时降低约 70%。Windows live resize 不再错帧：默认优先 RedirectionSurface ，消除拖拽改尺寸时对向边缘的错帧与白屏。窗口型 Popup 阴影穿透：Windows、X11、Wayland、macOS 上，Popup 阴影区域把指针输入交给下方内容，包括其他应用。首次显示更干净（ 6.2.7 ）：ToggleSwitch、Segmented、ComboBox 等控件的初始状态直接提交，首次显示与重新挂载不再补播过渡动画；FluentTheme 共存时保留 AtomUI 窗口装饰与语言资源。

破坏性变更与迁移

升级前先看这里

— 本版是 patch 版本，但包含破坏性变更（动效公共 API、Windows 合成模式、启动时序、主题资源优先级、Window Token），不能只改包版本。

— 动效类型从 AtomUI.MotionScene 迁移到 AtomUI.Animations ， MotionActor 、 LayoutAwareMotionActor 等包装控件已移除；AXAML 的 atom: 前缀不受影响，C# 需要改 using 。

— Windows 上需要 AcrylicBlur 或 Mica 材质的应用，须显式把 WinUIComposition 排在合成模式列表前面。

— 6.2.7 起 UseAtomUI 配置时序变化、主题资源优先级变化；6.2.8 起 Window Token 枚举数值变化，自定义主题需重新编译。

变更总览

迁移指南（请在升级前阅读）

6.2.10 API 迁移指南

6.2.7 迁移指南

6.2.8 迁移指南

最具代表性的 API 变化是动效播放方式：内容不再需要包在 MotionActor 中，动效直接作用于目标控件，并通过 PlayAsync 返回 MotionOutcome 。

csharp

// 6.2.9：内容必须包在 MotionActor 中

await new FadeInMotion ( TimeSpan .FromMilliseconds( 300 ))

. RunAsync (motionActor, aboutToStart: => motionActor.IsVisible = true );

// 6.2.10

target.IsVisible = true ;

var result = await new FadeInMotion ( TimeSpan .FromMilliseconds( 300 )). PlayAsync (target);

if (result.IsCompleted)

{

// ...

}

新增

动效（ 6.2.10 ）： Motion 附加属性族（ IsVisible / Enter / Leave / IsEnabled / DurationOverride / LayoutDirection ）与 ContentViewport 控件； SequenceMotion 与 ParallelMotion 组合动效。字体（ 6.2.9 ）：
AtomUI.Fonts.AlibabaPuHuiTi 纳入正式 NuGet 发布，包含普惠体 3.0 Regular。文档（ 6.2.9 ）：Headless 与 xUnit 测试接入指南。文档（ 6.2.10 ）：中英文设计语言与主题定制规范。文档（ 6.2.7 ）：AtomUI 与其他框架主题集成的开发者指南。

改进

动效（ 6.2.10 ）：布局动效只失效动画视口、只重排尺寸变化的祖先，消除子菜单、Expander、Collapse、TreeView 展开时的逐帧整窗重绘；反向请求从当前呈现值连续接续。Dialog 与 Drawer（ 6.2.10 ）：模态遮罩与抽屉动画期间合成缓存窗口内容，实测 Wayland Gallery 每帧渲染线程耗时降低约 70%；无放置目标的对话框从面板中心缩放。Popup（ 6.2.10 ）：窗口型 Popup 改用与 Overlay Popup 相同的 BoxShadowsSecondary 阴影，内容与锚点距离保持不变。Window（ 6.2.10 ）：Wayland 在首次布局前预测窗口缩放，消除启动约 250 ms 后的整窗重排；恢复 Windows 10 激活态左、右、下边框（6.2.8 已恢复顶边）。Wayland（ 6.2.10 ）：默认按预计上屏时间提交已准备好的 EGL 帧，动效按上屏时间采样；可用 AppContext 开关
AtomUI.Experimental.WaylandFramePacing 关闭。NavMenu（ 6.2.10 ）：Inline 折叠宽度动画改由原生时钟驱动，移除 16 ms 定时循环。初始状态（ 6.2.7 ）：ToggleSwitch、Segmented、TabControl、ComboBox、Carousel、Pagination、Breadcrumb 等控件的初始状态直接提交，首次显示、重新挂载与重新应用模板不再补播过渡。主题共存（ 6.2.7 ）：App.axaml 声明 FluentTheme 时保留 AtomUI 窗口装饰，替换 Application.Resources 时保留语言资源。构建（ 6.2.8 ）：TypeMap 发布默认支持 .NET 10 及后续稳定版本，取消 SDK 白名单。

修复

DashedBorder（ 6.2.8 ）：子元素裁剪更新移到绘制前，修复显示缩放变化时的崩溃，保留圆角裁剪与分数缩放边框对齐。ImagePreviewer（ 6.2.8 ）：修复快速连续点击旋转时角度倒转、来回摆动。Window（ 6.2.8 ）：恢复 Windows 10 CSD 窗口缺失的顶边，匹配激活/非激活颜色，高 DPI 下保持一个物理像素。Splash（ 6.2.9 ）：恢复完整卡片阴影，静态阴影与动画内容分开缓存，保留卡片裁剪与外观定制。动效（ 6.2.10 ）：修复展开前内容短暂暴露自然高度，以及准备期间重入导致旧请求覆盖新布局。DataGrid（ 6.2.10 ）：行未填满表格时，右键空白区域可打开上下文菜单。启动（ 6.2.7 ）：修复普通模块配置间接创建 AvaloniaObject 时过早创建 Dispatcher，导致的持续动画与定时器卡顿。ToggleSwitch（ 6.2.7 ）：默认文本按实际字形轮廓垂直居中，兼容字体回退与 shaping offset。

升级步骤

适用版本：6.2.6 → 6.2.10；环境要求：.NET 8.0 / .NET 10、Avalonia 12.1.4。

01 同步升级 AtomUI 包与 Generator： dotnet add package AtomUI.Desktop.Controls --version 6.2.10

02 动效代码改用 using AtomUI.Animations; ，自定义动效迁移到 Build / PlayAsync 契约，模板去掉 Actor 包装

03 检查 Windows 材质需求：需要 AcrylicBlur / Mica 的应用显式配置 WinUIComposition 优先

04 排查 Style.Resources 全局同键覆盖（6.2.7）与 Window Token 硬编码数字（6.2.8）

05 重新编译全部生成式消费方；裁剪或 NativeAOT 应用需要重新发布

回滚方式：把 AtomUI 包与 Generator 恢复到 6.2.6，并重新构建生成式消费方。

反馈与支持

提交 Issue

完整变更记录

6.2.10 API 迁移指南

6.2.7 API 迁移指南

6.2.8 API 迁移指南

如果升级过程中遇到问题，欢迎在 Issue 中附上 AtomUI 版本、Avalonia 版本、操作系统与合成模式，以及最小复现步骤 。

AtomUI OSS 6.2.10 · 2026-10-30