WinUI ProgressRing 控件 API 规范深度解析确定模式、范围语义与状态可视化【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xamlProgressRing 是 WinUI 中用于向用户提示某个操作正在进行的环形进度控件传统上仅支持不确定模式indeterminate的无限旋转动画。本文基于仓库中的规格文档 specs/Progress/ProgressRing.md 展开结合 controls/dev/ProgressRing 下的真实 IDL、C 实现、默认样式与测试代码系统梳理 ProgressRing 新增的确定模式determinate、Minimum/Maximum范围语义、暂停/错误状态设计以及底层 Lottie 动画驱动的实现原理。读完本文你将掌握 ProgressRing 全部核心属性的取值与默认值、XAML 用法、状态组合行为并能从源码层面理解状态切换与值强制转换coercion的机制。背景进度控件家族与 ProgressRing 的定位进度控件Progress controls的作用是向用户传达某个操作正在发生WinUI 中由两个控件组成ProgressBar横向条状同时具备确定模式与不确定模式ProgressRing环形spinner在引入确定模式之前仅支持不确定模式。ProgressRing 的典型视觉表现是一个环形随着进度推进环上有一块填充区域在动画移动。在旧版指导建议中ProgressRing 仅用于用户无法继续与界面交互的场景随着确定模式与暂停/错误能力的引入这一限制已被放宽——ProgressRing 可以在用户继续交互的同时持续旋转用于表示后台任务的进行状态。该规格源于多个演进提案为 ProgressRing 增加确定模式issue #688、ProgressRing 样式更新issue #837以及 Progress 控件使用指导issue #880。与之配套的状态对比表见 specs/Progress/progress-styles-tables.md。设计目标模式对齐与状态对齐本次规格设计的核心目标是为 ProgressRing 增加确定模式通过IsIndeterminate属性在两种模式间切换使其能够基于Value属性反映具体进度比例状态对齐 ProgressBar将 ProgressBar 已有的ShowPaused与ShowError能力引入 ProgressRing使其能够表达进度暂停与处理出错两种状态明确继承关系ProgressRing 继续继承自Control不继承RangeBase。原因是 RangeBase 中存在 ProgressRing/ProgressBar 都用不到的额外功能Value、Minimum、Maximum等范围属性直接在 ProgressRing 上以依赖属性DependencyProperty形式实现。核心 API 一览规格文档给出了新增到 ProgressRing 的属性清单其中IsIndeterminate默认值为True以保证向后兼容原有行为仍为默认行为名称类型描述IsIndeterminateboolean默认 True。获取或设置一个值指示进度环是以重复图案报告通用进度不确定进度还是基于 Value 属性报告进度确定进度Valuedouble获取或设置范围控件的当前值该值可能被强制转换coerceShowPausedboolean默认 False。获取或设置一个值指示进度控件是否应使用向用户传达 Paused 状态的视觉状态ShowErrorboolean默认 False。获取或设置一个值指示进度控件是否应使用向用户传达 Error 状态的视觉状态Maximumdouble默认 100。获取或设置范围元素可能的最高 ValueMinimumdouble默认 0。获取或设置范围元素可能的最低 ValueValueChangedevent范围值发生变化时触发的事件对照当前仓库的真实接口定义 controls/dev/ProgressRing/ProgressRing.idl可以确认以下属性已在实现中落地且默认值与规格一致IsActive默认true控制环是否激活显示IsIndeterminate默认true确定/不确定模式切换Value默认0.0、Minimum默认0.0、Maximum默认100.0预览MUX_PREVIEW属性DeterminateSource与IndeterminateSource允许替换默认的 Lottie 动画源只读的TemplateSettings含EllipseDiameter、EllipseOffset、MaxSideLength用于向后兼容自动化对等类ProgressRingAutomationPeer实现了IRangeValueProvider使辅助技术能够读取当前进度值。需要说明的是规格文档中规划的ShowPaused、ShowError与公开的ValueChanged事件在本文所对应的仓库版本 IDL 中尚未出现属于规格规划中的能力文章后续的状态组合表展示的即是这套规划中的完整状态语义。使用示例规格文档以IsActive切换激活、IsIndeterminate切换模式、Value表示进度比例给出了两组最基础的 XAML 用法。不确定模式IndeterminateProgressRing IsActiveTrue Height100 Width100/确定模式DeterminateProgressRing IsActiveTrue Height100 Width100 Value75 IsIndeterminateFalse/属性组合状态语义规格文档用三张状态表完整刻画了IsActive、IsIndeterminate、ShowPaused、ShowError、Value五种属性的组合行为。这些表格是理解控件行为的关键下面完整继承并展开说明。未激活的 ProgressRingInactive说明图像当 IsActive 为 False 时无论其他属性如何设置ProgressRing 永远显示为空白这一行为与源码实现吻合在 ProgressRing.cpp 的UpdateStates()中IsActive为 false 时切换到Inactive视觉状态并调用player.Stop()停止动画默认样式ProgressRing.xaml中Inactive状态会把LayoutRoot的 Opacity 设为 0因此整环不可见。不确定模式IsIndeterminate True不确定模式下动画会无限循环旋转此时即使设置了 Value也按没有 Value处理即 Value 不参与渲染ShowPausedShowErrorValue图像FalseFalse空FalseFalse75FalseTrue空FalseTrue75TrueFalse空TrueFalse75TrueTrue空TrueTrue75不确定模式设置 Value 应显示为没有 Value这一规则在实现中得到印证ProgressRing.cpp 的OnValuePropertyChanged()中if (!IsIndeterminate())才会调用UpdateLottieProgress()更新 Lottie 进度即不确定模式下 Value 变化不会驱动动画进度。确定模式IsIndeterminate False确定模式下环的填充比例由Value决定无 Value 或 Value 为 0 时显示空环ShowPausedShowErrorValue图像FalseFalse空FalseFalse0FalseFalse75FalseTrue空FalseTrue75TrueFalse空TrueFalse75TrueTrue空TrueTrue75从表中可以提炼出两条关键规则ShowError 优先于其他视觉只要ShowErrorTrue无论ShowPaused与Value如何都渲染为空白规格设计阶段以空环表达错误/暂停状态最终视觉样式以后续定稿为准规格文档明确标注了设计尚未最终确定暂停状态ShowPausedTrue, ShowErrorFalse, Value75会渲染为专门的暂停环其余组合则落入空环。Minimum 与 Maximum确定模式下ProgressRing 依据Value相对于Minimum和Maximum的比值来指示进度属性组合图像Minimum10, Maximum18, Value16当Value16、Minimum10、Maximum18时实际进度比例应为(16-10)/(18-10)75%与图示中 75% 的填充效果一致。源码级实现原理Lottie 动画驱动的渲染架构当前实现中 ProgressRing 的动画不再依赖传统 Storyboard而是基于Lottie 动画AnimatedVisualPlayer。默认控件模板controls/dev/ProgressRing/ProgressRing.xaml结构如下Grid x:NameLayoutRoot BackgroundTransparent VisualStateManager.VisualStateGroups VisualStateGroup x:NameCommonStates VisualState x:NameInactive VisualState.Setters Setter TargetLayoutRoot.Opacity Value0 / Setter TargetLottiePlayer.(AutomationProperties.AccessibilityView) ValueRaw / /VisualState.Setters /VisualState VisualState x:NameDeterminateActive / VisualState x:NameActive / /VisualStateGroup /VisualStateManager.VisualStateGroups controls:AnimatedVisualPlayer x:NameLottiePlayer AutoPlayfalse Stretchfill Opacity1 / /Grid内置的两套动画源位于 controls/dev/ProgressRing/AnimatedVisuals/ProgressRingIndeterminate.cpp 与 controls/dev/ProgressRing/AnimatedVisuals/ProgressRingDeterminate.cpp由 Lottie JSON 编译生成的IAnimatedVisualSource。以确定模式动画源 ProgressRingDeterminate.cs 为例其用CompositionEllipseGeometry画两个椭圆底层灰色轨道LightGray上层通过TrimEnd标量动画控制弧长进度通过表达式动画_.Progress驱动——这正是确定模式下弧线随Value增长的根本机制。状态切换与动画源选择ProgressRing.cpp 的UpdateStates()是状态机核心IsActiveTrue且IsIndeterminateTrue切换到Active视觉状态播放不确定动画源并调用PlayAsync(0, 1, true)无限循环IsActiveTrue且IsIndeterminateFalse切换到DeterminateActive视觉状态播放确定动画源并调用UpdateLottieProgress()定位到当前进度IsActiveFalse切换到Inactiveplayer.Stop()停止动画。IsActive、IsIndeterminate任一属性变化都会触发UpdateStates()见OnIsActivePropertyChanged与OnIsIndeterminatePropertyChanged。动画源的切换由SetAnimatedVisualPlayerSource()ProgressRing.cpp完成若用户未设置自定义DeterminateSource/IndeterminateSource则使用内置 Lottie 源并同步将Foreground/Background颜色注入动画的Foreground/Background主题属性SetLottieForegroundColor/SetLottieBackgroundColor默认色来自主题资源。进度更新与值强制转换UpdateLottieProgress()ProgressRing.cpp负责把Value映射到动画进度const double value Value(); const double min Minimum(); const double range Maximum() - min; const double fromProgress (m_oldValue - min) / range; const double toProgress (value - min) / range;当新值大于旧值时用PlayAsync(fromProgress, toProgress, false)做平滑动画否则直接SetProgress(toProgress)定位。这从实现层面印证了Value 相对 Minimum/Maximum 计算进度比例的规格语义。为保证范围一致性实现中还包含一整套强制转换逻辑ProgressRing.cppCoerceMinimumMinimum Maximum时把Minimum压回等于MaximumCoerceMaximumMaximum Minimum时把Maximum压回等于MinimumCoerceValueValue超出[Minimum, Maximum]时高于上限则取Maximum否则取MinimumNaN值直接忽略。OnValuePropertyChanged/OnMinimumPropertyChanged/OnMaximumPropertyChanged通过m_rangeBasePropertyUpdating标志防止递归更新。交互测试 InteractionTests/ProgressRingTests.cs 中的UpdateMinMaxTest专门验证了这些边界情形Maximum 设为 5 时 Minimum 自动修正为相等、Minimum 设为 15 时 Value 同步修正为 15、以及小数范围0.1~1.1下的步进精度。无障碍与自动化AutomationPeerProgressRing.idl 中ProgressRingAutomationPeer继承FrameworkElementAutomationPeer并实现IRangeValueProvider使屏幕阅读器可以读取/调节进度值AccessibilityViewUpdateStates()中激活时设为Content、未激活时设为Raw对辅助技术隐藏命中与聚焦默认样式设置IsHitTestVisibleFalse、IsTabStopFalseProgressRing 是纯展示控件不参与键盘导航与命中测试。API 测试 APITests/ProgressRingTests.cs 的VerifyAccessibilityView即断言了IsActive切换时 AccessibilityView 的联动。样式与主题资源ProgressRing 的视觉外观由默认样式与主题资源共同决定默认样式controls/dev/ProgressRing/ProgressRing.xaml默认 32×32最小 16×16Foreground/Background均取自主题资源Maximum默认为 100水平/垂直居中主题资源controls/dev/ProgressRing/ProgressRing_themeresources.xamlLight 与 Default 主题下前景使用AccentFillColorDefaultBrush、背景使用ControlFillColorTransparentBrush高对比度HighContrast主题下切换为SystemControlHighlightAccentBrush与SystemControlBackgroundBaseLowBrush并定义描边粗细资源ProgressRingStrokeThickness4向后兼容模板设置ProgressRingTemplateSettings提供EllipseDiameter、EllipseOffset、MaxSideLength三个只读值在ApplyTemplateSettings()ProgressRing.cpp中依据实际宽度计算直径约为宽度的 10%宽度 ≤40 时补偿 1px供旧模板和自定义模板使用。测试验证仓库为 ProgressRing 提供了三层测试API 测试APITests/ProgressRingTests.cs验证 AccessibilityView 与IsActive的联动交互测试InteractionTests/ProgressRingTests.csChangeStateTest依次断言 ActiveOpacity1、动画播放→ DeterminateActive动画停止→ InactiveOpacity0三态LottieCustomSourceTest验证自定义 Lottie 源可替换默认动画ChangeValueTest与UpdateMinMaxTest覆盖 Value/Min/Max 变更VerifyIndeterminateProgressRingDoesNotImplementRangeValuePattern验证不确定模式下不暴露 RangeValue 自动化模式测试页面TestUI/ProgressRingPage.xaml提供 IsActive/IsIndeterminate 开关、Minimum/Maximum/Value/Width 输入框与状态文本是复现上述行为的最直观实验场。设计说明与开放问题规格文档还明确了两点设计约束继承关系ProgressRing 保持继承自Control不引入RangeBase的继承体系未来方向正在调研在环中心添加内容文本或图标的能力以对齐 Xbox 及其他微软产品团队的视觉语言。最后规格文档保留了一个开放问题0%、1%、98%、99% 这些边缘进度值如何可视化——由于 ProgressRing 采用圆角内边缘设计极低/极高的进度在视觉上如何呈现仍在与相关团队讨论中。这也意味着ProgressRing 的最终视觉样式尤其是暂停/错误态的呈现可能会随版本演进调整在实际开发中以你所使用版本的行为为准。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WinUI ProgressRing 控件 API 规范深度解析：确定模式、范围语义与状态可视化
WinUI ProgressRing 控件 API 规范深度解析确定模式、范围语义与状态可视化【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xamlProgressRing 是 WinUI 中用于向用户提示某个操作正在进行的环形进度控件传统上仅支持不确定模式indeterminate的无限旋转动画。本文基于仓库中的规格文档 specs/Progress/ProgressRing.md 展开结合 controls/dev/ProgressRing 下的真实 IDL、C 实现、默认样式与测试代码系统梳理 ProgressRing 新增的确定模式determinate、Minimum/Maximum范围语义、暂停/错误状态设计以及底层 Lottie 动画驱动的实现原理。读完本文你将掌握 ProgressRing 全部核心属性的取值与默认值、XAML 用法、状态组合行为并能从源码层面理解状态切换与值强制转换coercion的机制。背景进度控件家族与 ProgressRing 的定位进度控件Progress controls的作用是向用户传达某个操作正在发生WinUI 中由两个控件组成ProgressBar横向条状同时具备确定模式与不确定模式ProgressRing环形spinner在引入确定模式之前仅支持不确定模式。ProgressRing 的典型视觉表现是一个环形随着进度推进环上有一块填充区域在动画移动。在旧版指导建议中ProgressRing 仅用于用户无法继续与界面交互的场景随着确定模式与暂停/错误能力的引入这一限制已被放宽——ProgressRing 可以在用户继续交互的同时持续旋转用于表示后台任务的进行状态。该规格源于多个演进提案为 ProgressRing 增加确定模式issue #688、ProgressRing 样式更新issue #837以及 Progress 控件使用指导issue #880。与之配套的状态对比表见 specs/Progress/progress-styles-tables.md。设计目标模式对齐与状态对齐本次规格设计的核心目标是为 ProgressRing 增加确定模式通过IsIndeterminate属性在两种模式间切换使其能够基于Value属性反映具体进度比例状态对齐 ProgressBar将 ProgressBar 已有的ShowPaused与ShowError能力引入 ProgressRing使其能够表达进度暂停与处理出错两种状态明确继承关系ProgressRing 继续继承自Control不继承RangeBase。原因是 RangeBase 中存在 ProgressRing/ProgressBar 都用不到的额外功能Value、Minimum、Maximum等范围属性直接在 ProgressRing 上以依赖属性DependencyProperty形式实现。核心 API 一览规格文档给出了新增到 ProgressRing 的属性清单其中IsIndeterminate默认值为True以保证向后兼容原有行为仍为默认行为名称类型描述IsIndeterminateboolean默认 True。获取或设置一个值指示进度环是以重复图案报告通用进度不确定进度还是基于 Value 属性报告进度确定进度Valuedouble获取或设置范围控件的当前值该值可能被强制转换coerceShowPausedboolean默认 False。获取或设置一个值指示进度控件是否应使用向用户传达 Paused 状态的视觉状态ShowErrorboolean默认 False。获取或设置一个值指示进度控件是否应使用向用户传达 Error 状态的视觉状态Maximumdouble默认 100。获取或设置范围元素可能的最高 ValueMinimumdouble默认 0。获取或设置范围元素可能的最低 ValueValueChangedevent范围值发生变化时触发的事件对照当前仓库的真实接口定义 controls/dev/ProgressRing/ProgressRing.idl可以确认以下属性已在实现中落地且默认值与规格一致IsActive默认true控制环是否激活显示IsIndeterminate默认true确定/不确定模式切换Value默认0.0、Minimum默认0.0、Maximum默认100.0预览MUX_PREVIEW属性DeterminateSource与IndeterminateSource允许替换默认的 Lottie 动画源只读的TemplateSettings含EllipseDiameter、EllipseOffset、MaxSideLength用于向后兼容自动化对等类ProgressRingAutomationPeer实现了IRangeValueProvider使辅助技术能够读取当前进度值。需要说明的是规格文档中规划的ShowPaused、ShowError与公开的ValueChanged事件在本文所对应的仓库版本 IDL 中尚未出现属于规格规划中的能力文章后续的状态组合表展示的即是这套规划中的完整状态语义。使用示例规格文档以IsActive切换激活、IsIndeterminate切换模式、Value表示进度比例给出了两组最基础的 XAML 用法。不确定模式IndeterminateProgressRing IsActiveTrue Height100 Width100/确定模式DeterminateProgressRing IsActiveTrue Height100 Width100 Value75 IsIndeterminateFalse/属性组合状态语义规格文档用三张状态表完整刻画了IsActive、IsIndeterminate、ShowPaused、ShowError、Value五种属性的组合行为。这些表格是理解控件行为的关键下面完整继承并展开说明。未激活的 ProgressRingInactive说明图像当 IsActive 为 False 时无论其他属性如何设置ProgressRing 永远显示为空白这一行为与源码实现吻合在 ProgressRing.cpp 的UpdateStates()中IsActive为 false 时切换到Inactive视觉状态并调用player.Stop()停止动画默认样式ProgressRing.xaml中Inactive状态会把LayoutRoot的 Opacity 设为 0因此整环不可见。不确定模式IsIndeterminate True不确定模式下动画会无限循环旋转此时即使设置了 Value也按没有 Value处理即 Value 不参与渲染ShowPausedShowErrorValue图像FalseFalse空FalseFalse75FalseTrue空FalseTrue75TrueFalse空TrueFalse75TrueTrue空TrueTrue75不确定模式设置 Value 应显示为没有 Value这一规则在实现中得到印证ProgressRing.cpp 的OnValuePropertyChanged()中if (!IsIndeterminate())才会调用UpdateLottieProgress()更新 Lottie 进度即不确定模式下 Value 变化不会驱动动画进度。确定模式IsIndeterminate False确定模式下环的填充比例由Value决定无 Value 或 Value 为 0 时显示空环ShowPausedShowErrorValue图像FalseFalse空FalseFalse0FalseFalse75FalseTrue空FalseTrue75TrueFalse空TrueFalse75TrueTrue空TrueTrue75从表中可以提炼出两条关键规则ShowError 优先于其他视觉只要ShowErrorTrue无论ShowPaused与Value如何都渲染为空白规格设计阶段以空环表达错误/暂停状态最终视觉样式以后续定稿为准规格文档明确标注了设计尚未最终确定暂停状态ShowPausedTrue, ShowErrorFalse, Value75会渲染为专门的暂停环其余组合则落入空环。Minimum 与 Maximum确定模式下ProgressRing 依据Value相对于Minimum和Maximum的比值来指示进度属性组合图像Minimum10, Maximum18, Value16当Value16、Minimum10、Maximum18时实际进度比例应为(16-10)/(18-10)75%与图示中 75% 的填充效果一致。源码级实现原理Lottie 动画驱动的渲染架构当前实现中 ProgressRing 的动画不再依赖传统 Storyboard而是基于Lottie 动画AnimatedVisualPlayer。默认控件模板controls/dev/ProgressRing/ProgressRing.xaml结构如下Grid x:NameLayoutRoot BackgroundTransparent VisualStateManager.VisualStateGroups VisualStateGroup x:NameCommonStates VisualState x:NameInactive VisualState.Setters Setter TargetLayoutRoot.Opacity Value0 / Setter TargetLottiePlayer.(AutomationProperties.AccessibilityView) ValueRaw / /VisualState.Setters /VisualState VisualState x:NameDeterminateActive / VisualState x:NameActive / /VisualStateGroup /VisualStateManager.VisualStateGroups controls:AnimatedVisualPlayer x:NameLottiePlayer AutoPlayfalse Stretchfill Opacity1 / /Grid内置的两套动画源位于 controls/dev/ProgressRing/AnimatedVisuals/ProgressRingIndeterminate.cpp 与 controls/dev/ProgressRing/AnimatedVisuals/ProgressRingDeterminate.cpp由 Lottie JSON 编译生成的IAnimatedVisualSource。以确定模式动画源 ProgressRingDeterminate.cs 为例其用CompositionEllipseGeometry画两个椭圆底层灰色轨道LightGray上层通过TrimEnd标量动画控制弧长进度通过表达式动画_.Progress驱动——这正是确定模式下弧线随Value增长的根本机制。状态切换与动画源选择ProgressRing.cpp 的UpdateStates()是状态机核心IsActiveTrue且IsIndeterminateTrue切换到Active视觉状态播放不确定动画源并调用PlayAsync(0, 1, true)无限循环IsActiveTrue且IsIndeterminateFalse切换到DeterminateActive视觉状态播放确定动画源并调用UpdateLottieProgress()定位到当前进度IsActiveFalse切换到Inactiveplayer.Stop()停止动画。IsActive、IsIndeterminate任一属性变化都会触发UpdateStates()见OnIsActivePropertyChanged与OnIsIndeterminatePropertyChanged。动画源的切换由SetAnimatedVisualPlayerSource()ProgressRing.cpp完成若用户未设置自定义DeterminateSource/IndeterminateSource则使用内置 Lottie 源并同步将Foreground/Background颜色注入动画的Foreground/Background主题属性SetLottieForegroundColor/SetLottieBackgroundColor默认色来自主题资源。进度更新与值强制转换UpdateLottieProgress()ProgressRing.cpp负责把Value映射到动画进度const double value Value(); const double min Minimum(); const double range Maximum() - min; const double fromProgress (m_oldValue - min) / range; const double toProgress (value - min) / range;当新值大于旧值时用PlayAsync(fromProgress, toProgress, false)做平滑动画否则直接SetProgress(toProgress)定位。这从实现层面印证了Value 相对 Minimum/Maximum 计算进度比例的规格语义。为保证范围一致性实现中还包含一整套强制转换逻辑ProgressRing.cppCoerceMinimumMinimum Maximum时把Minimum压回等于MaximumCoerceMaximumMaximum Minimum时把Maximum压回等于MinimumCoerceValueValue超出[Minimum, Maximum]时高于上限则取Maximum否则取MinimumNaN值直接忽略。OnValuePropertyChanged/OnMinimumPropertyChanged/OnMaximumPropertyChanged通过m_rangeBasePropertyUpdating标志防止递归更新。交互测试 InteractionTests/ProgressRingTests.cs 中的UpdateMinMaxTest专门验证了这些边界情形Maximum 设为 5 时 Minimum 自动修正为相等、Minimum 设为 15 时 Value 同步修正为 15、以及小数范围0.1~1.1下的步进精度。无障碍与自动化AutomationPeerProgressRing.idl 中ProgressRingAutomationPeer继承FrameworkElementAutomationPeer并实现IRangeValueProvider使屏幕阅读器可以读取/调节进度值AccessibilityViewUpdateStates()中激活时设为Content、未激活时设为Raw对辅助技术隐藏命中与聚焦默认样式设置IsHitTestVisibleFalse、IsTabStopFalseProgressRing 是纯展示控件不参与键盘导航与命中测试。API 测试 APITests/ProgressRingTests.cs 的VerifyAccessibilityView即断言了IsActive切换时 AccessibilityView 的联动。样式与主题资源ProgressRing 的视觉外观由默认样式与主题资源共同决定默认样式controls/dev/ProgressRing/ProgressRing.xaml默认 32×32最小 16×16Foreground/Background均取自主题资源Maximum默认为 100水平/垂直居中主题资源controls/dev/ProgressRing/ProgressRing_themeresources.xamlLight 与 Default 主题下前景使用AccentFillColorDefaultBrush、背景使用ControlFillColorTransparentBrush高对比度HighContrast主题下切换为SystemControlHighlightAccentBrush与SystemControlBackgroundBaseLowBrush并定义描边粗细资源ProgressRingStrokeThickness4向后兼容模板设置ProgressRingTemplateSettings提供EllipseDiameter、EllipseOffset、MaxSideLength三个只读值在ApplyTemplateSettings()ProgressRing.cpp中依据实际宽度计算直径约为宽度的 10%宽度 ≤40 时补偿 1px供旧模板和自定义模板使用。测试验证仓库为 ProgressRing 提供了三层测试API 测试APITests/ProgressRingTests.cs验证 AccessibilityView 与IsActive的联动交互测试InteractionTests/ProgressRingTests.csChangeStateTest依次断言 ActiveOpacity1、动画播放→ DeterminateActive动画停止→ InactiveOpacity0三态LottieCustomSourceTest验证自定义 Lottie 源可替换默认动画ChangeValueTest与UpdateMinMaxTest覆盖 Value/Min/Max 变更VerifyIndeterminateProgressRingDoesNotImplementRangeValuePattern验证不确定模式下不暴露 RangeValue 自动化模式测试页面TestUI/ProgressRingPage.xaml提供 IsActive/IsIndeterminate 开关、Minimum/Maximum/Value/Width 输入框与状态文本是复现上述行为的最直观实验场。设计说明与开放问题规格文档还明确了两点设计约束继承关系ProgressRing 保持继承自Control不引入RangeBase的继承体系未来方向正在调研在环中心添加内容文本或图标的能力以对齐 Xbox 及其他微软产品团队的视觉语言。最后规格文档保留了一个开放问题0%、1%、98%、99% 这些边缘进度值如何可视化——由于 ProgressRing 采用圆角内边缘设计极低/极高的进度在视觉上如何呈现仍在与相关团队讨论中。这也意味着ProgressRing 的最终视觉样式尤其是暂停/错误态的呈现可能会随版本演进调整在实际开发中以你所使用版本的行为为准。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考