WinUI TitleBar 控件设计全解非客户区拖拽穿透、功能分区与 NavigationView 集成实战microsoft-ui-xaml【免费下载链接】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-xamlTitleBar 是 WinUI 中用于替代系统 Shell 标题栏的现代标题栏控件它允许开发者在标题栏内直接嵌入 AutoSuggestBox、PersonPicture、NavigationView 的 BackButton / PaneToggleButton 以及 Mica 亚克力背景等 WinUI 组件而无需从零手写一套自定义标题栏。本文以 docs/design-notes/TitleBar/titleBar-dev-spec.md 与 docs/design-notes/TitleBar/titlebar-functional-spec.md 两份设计文档为主体结合本仓库controls/dev/TitleBar/下的真实实现源码系统讲解 TitleBar 的架构、非客户区打孔交互原理、完整 API 与三类实战场景帮助读者掌握在 WinUI 3 应用中正确启用、配置与扩展 TitleBar 的完整方法。为什么需要 WinUI TitleBar标题栏是 Windows 应用用户界面的基础组成部分它承担四项基本职责展示信息显示当前应用或文档的名称并可附带文档标题、状态信息如编辑中查看中窗口控制提供最小化、最大化/还原、关闭三个系统按钮拖拽移动用户按住标题栏空白区域即可拖动窗口到屏幕任意位置主题与集成可通过 Mica 材质匹配应用视觉风格并与 NavigationView、AutoSuggestBox、PersonPicture 等 WinUI 控件协同工作。在过去实现自定义标题栏意味着开发者必须从零构建一个用户组件其中最痛苦的痛点在于当标题栏内存在交互元素例如 AutoSuggestBox时必须手动计算并维护拖拽区域参见 WinUI Gallery 示例。WinUI TitleBar 的设计目标正是封装最常见的设计场景把这套繁琐的流程自动化。从仓库实现看TitleBar 的动机可归纳为三点见功能规范 Background 一节与 Fluent Windows Visual Design Library 对齐、弥合 Shell/Win32 标题栏与完全自定义 XAML 标题栏之间的鸿沟、简化现代标题栏的开发者体验。AppWindow.TitleBar 与 WinUI TitleBar 的定位区别设计文档明确区分了两个易混淆的概念| 维度 | AppWindow.TitleBar | WinUI TitleBar | |--|--|--| | 定位 | 默认标题栏向下兼容 Win32 | 开发者显式opt-in的自定义标题栏 | | 能力 | SetIcon、Title、最大化/最小化/关闭按钮、跟随主题 | 在 AppWindow 基础之上提供功能区、内容区、Mica 透明等扩展 | | 是否处理 Caption 按钮 | 是负责绘制与定制 | 否仅根据 RTL/LTR 布局为 Caption 按钮预留空间 |功能规范中特别强调WinUI TitleBar 不处理 Caption 按钮——它只是依据 RTL 或 LTR 设置在布局中为系统 Caption 按钮的出现位置分配空间Caption 按钮及其定制依然由 AppWindow.TitleBar 负责。这意味着两者是协作关系而非替代关系。WinUI TitleBar 提供的能力开发规范列出了 WinUI TitleBar 的核心功能点HeaderArea例如 BackButton、PaneToggleButton 等导航头部元素Icon标题栏图标Title主标题文本Subtitle副标题文本常用于版本标识PreviewBeta等ContentArea内容区例如 AutoSuggestBox 搜索框FooterArea尾部区域例如 PersonPicture 头像Mica 透明支持背景可设为透明以透出 Mica 材质自定义高度默认 32px紧凑若内容区非空则自动切换为 48px展开。这些功能区最终落到一个 12 列的 Grid 模板布局上见 controls/dev/TitleBar/TitleBar.xaml左内边距列、BackButton 列、PaneToggleButton 列、LeftHeader 列、图标列、标题列、副标题列、内容区列占剩余宽度*、RightHeader 列、最小拖拽区列、右内边距列每一列都对应一个命名的模板部件。关键设计考量开发规范记录了标题栏设计中必须处理的若干边界问题这些考量直接决定了TitleBar.cpp的实现形态。拖拽区域的打孔Punch Hole一旦通过Window.SetTitleBar()将 TitleBar 设为窗口标题栏整个区域的输入都会被标记为 non-client非客户区从而变得不可交互。因此实现上必须针对每个可交互区域打一个孔punch hole被打孔穿透的区域变为不可拖拽可点击交互其余未打孔区域保持拖拽能力计算必须在SizeChanged事件触发时持续更新。自定义内容的可交互性判定开发规范提出了一个开放式问题TitleBar 将自定义内容一律视为可交互并打孔穿透拖拽区但如何允许更细粒度的定制若增加IsInteractive附加属性TitleBar 每次都需要遍历整棵可视化树来计算矩形成本过高若命名为InteractiveContent又限制了控件的可定制性参考案例Teams 的前进/后退按钮在禁用状态下依然是可拖拽的。在仓库的最终实现中这个问题被一种更完善的机制解决新增了IsDragRegion附加属性与AutoRefreshDragRegions开关见 controls/dev/TitleBar/TitleBar.idl 中[MUX_PUBLIC_V11]区块配合递归的可视化树遍历实现精确控制详见后文源码级深入一节。键盘导航与可访问性标题栏内的交互内容必须支持键盘导航应作为应用可视化树中的普通元素对待图标需符合 Windows 应用设计指南单击图标弹出系统窗口菜单双击关闭窗口存在最小拖拽区域的硬性要求例如 Store 应用中 PersonPicture 与 Caption 按钮之间的间隙该值在规范中记录为TitleBarMinDragRegionWidth规范文档标注 60px当前主题资源实现值为 48px见 controls/dev/TitleBar/TitleBar_themeresources.xaml。WinUI 3 缺失的 UWP 事件开发规范指出UWP 时代的CoreApplicationViewTitleBar.LayoutMetricsChanged与IsVisibleChanged事件在 WinUI 3 中缺失这带来两个直接后果LayoutMetricsChangedDPI 变化时需要更新左右 Inset右 Inset 在 WinUI TitleBar 中用于为 Caption 按钮预留占位空间IsVisibleChanged窗口进入全屏模式时TitleBar 需要感知并自动折叠自身。因此需要暴露相应事件或依赖属性以支持动态更新。在实现中UpdatePadding()通过读取AppWindow.TitleBar().LeftInset() / RightInset()并写入模板中LeftPaddingColumn / RightPaddingColumn两列的宽度来动态响应controls/dev/TitleBar/TitleBar.cpp同时监听FlowDirection变化以正确处理 RTL 布局下左右 Inset 的交换。其余待决问题ContentDialog 遮罩层内容对话框弹出时 TitleBar 是否仍应可拖拽若否需要暴露一个禁用拖拽的布尔 APIFlyout 感知Flyout 需要知道 TitleBar 的尺寸才能正确计算向上或向下展开最小窗口宽度应用本身有 MinSize 约束时如 Store 已设置 MinSize可以避免完全折叠 AutoSuggestBox但仍应针对最坏场景进行测试。真实产品场景与折叠策略开发规范以三个真实应用为例说明了不同产品对标题栏折叠行为的不同取舍StoreMicrosoft Store紧凑模式Minimal Mode下 AutoSuggestBox 折叠为图标形态同时折叠 Title 与 Subtitle由于 Store 设置了应用 MinSize无需完全折叠搜索框WinUI Gallery处理 NavigationView 的 BackButton 与 PaneToggleButton——紧凑模式下折叠并移动 PaneToggleButton 到标题栏Teams支持在内容区放置非标准元素如前进/后退的 箭头并在尾部区域放置其他按钮Visual Studio Code支持切换 Header 内容在图标之前或之后显示——该能力在文档标注为目前未实现。这些场景对应实现中的DisplayModeGroup视觉状态Compact/Expanded紧凑模式下折叠标题与副标题文本、将内容区左对齐并应用TitleBarCompactContentMargin边距见 TitleBar.xaml。实现细节非客户区打孔机制开发规范的 Implementation Details 一节描述了 TitleBar 最核心的底层机制仓库源码完整落地了这一设计。m_interactableElementsList一个贯穿 TitleBar 生命周期维护的可交互元素列表每当指定元素的可见性变化时更新包括BackButtonPaneToggleButtonHeaderLeftHeaderContentFooterRightHeader对应实现为 TitleBar.cpp 中的UpdateInteractableElementsList()依次把可见且启用的 BackButton、可见的 PaneToggleButton、LeftHeader 区域、Content 区域需递归查找子元素、RightHeader 区域加入列表。UpdateDragRegion()UpdateDragRegion()在SizeChanged与LayoutUpdated事件触发时调用检查m_interactableElementsList是否有子元素若有通过TransformToVisual获取每个元素相对窗口的矩形并按XamlRoot().RasterizationScale()换算为物理像素坐标GetBounds()TitleBar.cpp访问 IXP 层的InputNonClientPointerSource调用SetRegionRects(NonClientRegionKind::Passthrough, rects)将矩形设为穿透区域若无交互元素则调用ClearRegionRects清除全部穿透区域。实现中还有一个值得注意的优化m_previousPassthroughRects会缓存上次提交的矩形集合若本次计算出的矩形与上次完全相同则直接跳过SetRegionRects调用避免无谓的布局与输入系统开销。规范中特别提到需要编写自定义的 LayoutUpdated 事件因为默认的 LayoutUpdated 事件会为每个微小无关紧要的事件触发。仓库实现通过AutoRefreshDragRegions属性来管理这一成本为 Content 元素订阅LayoutUpdated若关闭自动刷新则在首次更新完成后自动取消订阅一次性行为并在布局变化时由RecomputeDragRegions()手动触发同步刷新。架构总览开发规范给出了 TitleBar 的架构定位关键公共组件TitleBar类关键内部组件TitleBarTemplateSettings负责计算拖拽区域相关值、TitleBarAutomationPeer手势识别TitleBar 必须同时处理鼠标、触摸与键盘三类输入场景。仓库中TitleBarTemplateSettings暴露IconElement属性将TitleBar.IconSource的值传递到模板内部供PART_Icon绑定使用模板中通过TemplatedParent路径绑定TemplateSettings.IconElementTitleBarAutomationPeer继承自FrameworkElementAutomationPeer负责将 TitleBar 类型暴露给 Microsoft UI Automation见 TitleBar.idl。完整 API 速查功能规范以 API Pages 形式详细给出了每个公共 API 的语义以下结合源码逐条整理命名空间Microsoft.UI.Xaml.Controls。TitleBar 类public class TitleBar : Control布局相关属性| 属性 | 类型 | 默认值 | 语义 | |--|--|--|--| |LeftHeader|UIElement|null| 位于标题文本左侧LTR 场景默认左对齐非空时控件自动切换为TitleBarExpandedHeight| |Title|String|null| 主标题紧凑模式或字符串为空时不显示 | |Subtitle|String|null| 副标题如 Preview紧凑模式或字符串为空时不显示 | |IconSource|IconSource|null| 标题栏图标 | |Content|UIElement|null| 内容区居中显示常用于 AutoSuggestBox非空时切换为展开高度 | |RightHeader|UIElement|null| 位于内容右侧LTR右对齐常用于 PersonPicture 与 More AppBarButton非空时切换为展开高度 |导航相关属性与事件| 成员 | 类型/签名 | 默认值 | 语义 | |--|--|--|--| |IsBackButtonVisible|Boolean|false| BackButton 可见性 | |IsBackButtonEnabled|Boolean|true| BackButton 的 IsEnabled通常绑定NavFrame.CanGoBack| |IsPaneToggleButtonVisible|Boolean|false| PaneToggleButton 可见性通常仅与 NavigationView 搭配 | |BackRequested|TypedEventHandlerTitleBar, Object| — | BackButton 被点击时触发 | |PaneToggleRequested|TypedEventHandlerTitleBar, Object| — | 内部 PaneToggleButton 引发 Click 时触发 |高度联动逻辑控件的高度由三个内容区LeftHeader、Content、RightHeader是否为空决定全部为空则使用TitleBarCompactHeight32px任一非空则使用TitleBarExpandedHeight48px。由于内容区默认全部为空TitleBar 默认高度为紧凑高度。对应实现见UpdateHeight()TitleBar.cpp它根据三个属性是否为 null 切换CompactHeight/ExpandedHeight视觉状态。MIDL3 定义节选IDL 中通过[contentproperty(Content)]声明内容属性使 XAML 中子元素可直接写入 Content属性默认值与规范一致[MUX_DEFAULT_VALUE(false)]等unsealed runtimeclass TitleBar : Microsoft.UI.Xaml.Controls.Control { TitleBar(); UIElement LeftHeader; String Title; String Subtitle; Microsoft.UI.Xaml.Controls.IconSource IconSource; UIElement Content; UIElement RightHeader; Boolean IsBackButtonVisible; Boolean IsBackButtonEnabled; Boolean IsPaneToggleButtonVisible; TitleBarTemplateSettings TemplateSettings{ get; }; event Windows.Foundation.TypedEventHandlerTitleBar, Object BackRequested; event Windows.Foundation.TypedEventHandlerTitleBar, Object PaneToggleRequested; // ... 对应依赖属性静态 Property }完整定义见 controls/dev/TitleBar/TitleBar.idl其中[MUX_PUBLIC_V8]与[MUX_PUBLIC_V11]标记了 API 分批公开的版本边界。主题资源功能规范仅列出需要特别说明的主题资源仓库中的实际定义TitleBar_themeresources.xaml如下| 资源 | 类型 | 值 | 说明 | |--|--|--|--| |TitleBarCompactHeight| Double | 32px | 紧凑/默认高度 | |TitleBarExpandedHeight| Double | 48px | 展开高度内容区非空时 | |TitleBarMinDragRegionWidth| Double | 60px规范值/ 48px当前实现值 | RightHeader 与 Caption 按钮之间的最小拖拽区域 |除上述关键资源外主题资源还定义了TitleBarDeactivatedOpacity0.5窗口失活时内容区透明度、TitleBarIconMaxWidth/MaxHeight16px、各区域边距、对齐方式以及 BackButton / PaneToggleButton 的完整样式。这些资源在Default、Light、HighContrast三个主题字典中均有对应定义确保深色、浅色与高对比度主题下标题栏前景色、背景色与按钮状态的正确呈现。实战场景一简单 TitleBar这是最基础的用法——只在标题栏中放置标题、副标题与图标。XAMLWindow x:ClassApp1.MainWindow xmlns:localusing:App1 mc:Ignorabled Grid Grid.RowDefinitions RowDefinition HeightAuto / !-- Title Bar -- RowDefinition Height* / !-- App Content -- /Grid.RowDefinitions TitleBar x:NameSimpleTitleBar TitleSimple TitleBar SubtitlePreview TitleBar.IconSource SymbolIconSource SymbolHome/ /TitleBar.IconSource /TitleBar !-- App content -- /Grid /WindowC# 代码后置public MainWindow() { this.InitializeComponent(); // C# code to set Window.TitleBar UIElement as Titlebar Window window this; window.ExtendsContentIntoTitleBar true; // Hides the default system titlebar. window.SetTitleBar(this.SimpleTitleBar); // Replace system titlebar with the WinUI Titlebar. // Note: If no title bar is specified, the default system titlebar will be rendered, // regardless of the ExtendsContentIntoTitleBar property. }两点使用前提需要特别注意TitleBar 目前必须显式放置在 Grid 行中并在代码后置中被Window引用如上所示规范提到正在考虑改进Window以省去额外的 Grid 布局与代码后置ExtendsContentIntoTitleBar并不自动启用 TitleBar——若未通过SetTitleBar指定标题栏即使该属性为 true系统仍会渲染默认标题栏。仓库测试应用中的用法与此完全一致TestUI/TitleBarPageWindow.xaml.csthis.ExtendsContentIntoTitleBar true;后紧跟this.SetTitleBar(this.WindowingTitleBar);。实战场景二集成 WinUI 控件在标题栏中同时放置AutoSuggestBox、PersonPicture、AppBarButton等常见 WinUI 控件充分利用 Content 与 RightHeader 两个区域TitleBar x:NameControlsTitleBar TitleControlsTitleBar SubtitlePreview BackgroundTransparent IsBackButtonVisibleTrue IsPaneToggleButtonVisibleTrue TitleBar.IconSource SymbolIconSource SymbolHome/ /TitleBar.IconSource TitleBar.Content AutoSuggestBox PlaceholderTextSearch QueryIconFind / /TitleBar.Content TitleBar.RightHeader StackPanel OrientationHorizontal AppBarButton IconMore LabelMoreSymbolIcon / PersonPicture DisplayNameJane Doe / /StackPanel /TitleBar.RightHeader /TitleBar这一场景的关键在于AutoSuggestBox 位于 Content 区、PersonPicture 位于 RightHeader 区两者都会被自动加入m_interactableElementsList并打孔穿透拖拽区因此搜索框可以正常接收输入、头像可以正常点击而标题栏其余区域仍可拖拽窗口。测试页 TestUI/TitleBarPage.xaml 中正是这样组合了 AutoSuggestBox 与 PersonPicture。实战场景三与 NavigationView 的 L-Pattern 集成标题栏与 NavigationView 组成经典的 L 形布局。TitleBar 会在其DesiredSize大于ActualSize时自动切换为紧凑显示模式并折叠 IconSource 与 Subtitle。XAMLGrid Grid.RowDefinitions RowDefinition HeightAuto / RowDefinition Height* / /Grid.RowDefinitions TitleBar x:NameNavViewTitleBar TitleNavView TitleBar SubtitlePreview IsBackButtonVisibleTrue IsBackButtonEnabled{x:Bind NavFrame.CanGoBack} BackRequestedNavViewTitleBar_BackRequested PaneToggleRequestedNavViewTitleBar_PaneToggleRequested TitleBar.IconSource SymbolIconSource SymbolHome/ /TitleBar.IconSource /TitleBar NavigationView x:NameNavView Grid.Column1 !-- TitleBar with NavigationView L-Pattern Overwriting resources -- NavigationView.Resources !-- This is the border between NavView and NavView Content -- Thickness x:KeyNavigationViewContentGridBorderThickness1,1,0,0/Thickness !-- This is the rounded corner on the Top left of the L Pattern -- CornerRadius x:KeyNavigationViewContentGridCornerRadius8,0,0,0/CornerRadius /NavigationView.Resources Frame x:NameNavFrame / NavigationView.MenuItems ... /NavigationView.MenuItems /NavigationView /GridC# 代码后置public MainWindow() { this.InitializeComponent(); Window window this; window.ExtendsContentIntoTitleBar true; window.SetTitleBar(this.NavViewTitleBar); } private void NavViewTitleBar_BackRequested(TitleBar sender, object args) { if (NavFrame.CanGoBack) { NavFrame.GoBack(); } } private void NavViewTitleBar_PaneToggleRequested(TitleBar sender, object args) { NavView.IsPaneOpen !NavView.IsPaneOpen; }要点说明IsBackButtonEnabled直接x:Bind到NavFrame.CanGoBackBackButton 不可用如无历史记录时自动禁用且禁用状态下该按钮按实现逻辑不会被加入可交互列表从而保留为可拖拽区域——这与设计文档中Teams 前进/后退按钮禁用时仍可拖拽的参考场景一致BackRequested与PaneToggleRequested事件对应实现中的OnBackButtonClick/OnPaneToggleButtonClick处理器TitleBar.cpp覆盖NavigationViewContentGridBorderThickness与NavigationViewContentGridCornerRadius两个资源是为了消除 NavView 与标题栏衔接处的边框与圆角形成连续的 L 形布局。源码级深入交互元素探测与失活态处理FindInteractableElements 的递归规则UpdateInteractableElementsList()对 Content 区域调用FindInteractableElements()TitleBar.cpp其决策规则值得开发者了解跳过不可见Visibility ! Visible或IsHitTestVisible false的元素——注意IsHitTestVisible是独立属性不会反映 Visibility必须单独检查若元素显式设置了IsDragRegionfalse整个元素视为可交互并加入列表停止向下递归元素边界已覆盖其内部元素若元素显式设置IsDragRegiontrue是 Control 类型整个控件视为可拖拽不进入其模板子树非 Control 容器如 Panel继续递归允许子元素用IsDragRegionfalse覆盖未显式设置时自动探测遇到已启用的 ControlButton、TextBox、ComboBox 等即加入列表并停止递归被禁用的 Control 继续向下递归保留祖先的拖拽意图未命中任何规则的元素递归遍历全部子节点。这套规则让整个面板拖拽、面板中个别按钮可点击这类混合布局成为可能给面板设置IsDragRegiontrue再给其中的按钮设置IsDragRegionfalse即可。窗口失活Deactivated状态实现通过InputActivationListener监听窗口激活状态TitleBar.cpp当窗口失活时BackButton、PaneToggleButton、图标、标题、副标题及各内容区统一切换为*Deactivated视觉状态——按钮前景切换为TitleBarDeactivatedForegroundBrush、内容区整体透明度降为TitleBarDeactivatedOpacity0.5与 Windows 原生标题栏的失活视觉一致。与 AppWindow 的双向联动标题同步UpdateTitle()在设置 Title 的同时会同步写入AppWindow.Title当 Title 清空或控件销毁时通过ResetTitle()安全恢复窗口的默认标题仅当当前标题与最后应用值一致时才恢复避免覆盖外部修改Inset 占位UpdatePadding()读取AppWindow.TitleBar()的LeftInset/RightInset动态设置模板左右内边距列的宽度为 Caption 按钮预留空间并在 RTL 场景下交换左右取值TitleBar.cpp图标点击区域UpdateIconRegion()通过SetRegionRects(NonClientRegionKind::Icon, ...)将图标区域标记为窗口图标区域使单击弹出系统窗口菜单、双击关闭窗口的系统行为得以保留。测试覆盖仓库在 controls/dev/TitleBar/InteractionTests/TitleBarTests.cs 中提供了基于 MUXControlsTestApp 的交互测试骨架并在 TestUI/TitleBarPage.xaml 中提供调试页面可切换 OutputDebugString 日志级别、通过MUXControlsTestHooks控制 TitleBar 的调试输出、用 Win32SetWindowLongPtr设置WS_EX_LAYOUTRTL验证 RTL 布局。开发者在集成 TitleBar 时可参考该测试页验证自定义场景下的拖拽区域行为。超出范围Out of Scope标签式标题栏Tabbed TitleBarTitleBar不面向 TabView 场景设计——该场景可能作为独立的TabbedTitleBar控件另行考虑。设计文档用 Terminal、Notepad、Edge 三个示例说明当 TabView 延伸进标题栏占满整个窗口时头部图标、按钮与拖拽区域均可交由 TabView 的 Header 与 FooterArea 处理但要求TabView 需要增加属性为图标或其他元素预留空间TabView 需要在右侧为拖拽区域预留空间FileExplorer 当前通过自行设置拖拽区域并在TabView.FooterArea放置 CaptionControl 占位符实现。Window.TitleBar 语法糖规范设想了对 Window 类的改进使 XAML 可以直接写成Window Window.TitleBar TitleBar / /Window.TitleBar /Window理想情况下这还应向 TitleBar 暴露Window.Title、AppWindow.Title与AppWindow.SetIcon()。但该设想超出 WinUI TitleBar 的范围未包含在规范内。附录Header / Content / Footer 的命名讨论开发规范记录了Header、Content、Footer命名的备选方案及其参考来源最终采纳的方案与 TabView 保持一致Header/Footer与TabView.TabStripHeader/TabView.TabStripFooter对齐Left*/Right*与 Pivot 和 ScrollViewer 对齐未采用Start/End参考Windows.UI.Xaml.TextAlignment未采用Before/After参考 CSS 与 Fluent Web UI未采用Leading/Trailing参考 Apple SwiftUI Toolbar未采用。实际公开 API 最终使用了LeftHeader、Content、RightHeader三个名称与功能规范及 TitleBar.idl 中的定义一致。延伸阅读开发规范原文docs/design-notes/TitleBar/titleBar-dev-spec.md功能规范原文docs/design-notes/TitleBar/titlebar-functional-spec.md接口定义controls/dev/TitleBar/TitleBar.idl核心实现controls/dev/TitleBar/TitleBar.cpp默认模板controls/dev/TitleBar/TitleBar.xaml主题资源controls/dev/TitleBar/TitleBar_themeresources.xaml测试页面controls/dev/TitleBar/TestUI/TitleBarPage.xaml 与 controls/dev/TitleBar/InteractionTests/TitleBarTests.cs【免费下载链接】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 TitleBar 控件设计全解：非客户区拖拽穿透、功能分区与 NavigationView 集成实战（microsoft-ui-xaml）
WinUI TitleBar 控件设计全解非客户区拖拽穿透、功能分区与 NavigationView 集成实战microsoft-ui-xaml【免费下载链接】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-xamlTitleBar 是 WinUI 中用于替代系统 Shell 标题栏的现代标题栏控件它允许开发者在标题栏内直接嵌入 AutoSuggestBox、PersonPicture、NavigationView 的 BackButton / PaneToggleButton 以及 Mica 亚克力背景等 WinUI 组件而无需从零手写一套自定义标题栏。本文以 docs/design-notes/TitleBar/titleBar-dev-spec.md 与 docs/design-notes/TitleBar/titlebar-functional-spec.md 两份设计文档为主体结合本仓库controls/dev/TitleBar/下的真实实现源码系统讲解 TitleBar 的架构、非客户区打孔交互原理、完整 API 与三类实战场景帮助读者掌握在 WinUI 3 应用中正确启用、配置与扩展 TitleBar 的完整方法。为什么需要 WinUI TitleBar标题栏是 Windows 应用用户界面的基础组成部分它承担四项基本职责展示信息显示当前应用或文档的名称并可附带文档标题、状态信息如编辑中查看中窗口控制提供最小化、最大化/还原、关闭三个系统按钮拖拽移动用户按住标题栏空白区域即可拖动窗口到屏幕任意位置主题与集成可通过 Mica 材质匹配应用视觉风格并与 NavigationView、AutoSuggestBox、PersonPicture 等 WinUI 控件协同工作。在过去实现自定义标题栏意味着开发者必须从零构建一个用户组件其中最痛苦的痛点在于当标题栏内存在交互元素例如 AutoSuggestBox时必须手动计算并维护拖拽区域参见 WinUI Gallery 示例。WinUI TitleBar 的设计目标正是封装最常见的设计场景把这套繁琐的流程自动化。从仓库实现看TitleBar 的动机可归纳为三点见功能规范 Background 一节与 Fluent Windows Visual Design Library 对齐、弥合 Shell/Win32 标题栏与完全自定义 XAML 标题栏之间的鸿沟、简化现代标题栏的开发者体验。AppWindow.TitleBar 与 WinUI TitleBar 的定位区别设计文档明确区分了两个易混淆的概念| 维度 | AppWindow.TitleBar | WinUI TitleBar | |--|--|--| | 定位 | 默认标题栏向下兼容 Win32 | 开发者显式opt-in的自定义标题栏 | | 能力 | SetIcon、Title、最大化/最小化/关闭按钮、跟随主题 | 在 AppWindow 基础之上提供功能区、内容区、Mica 透明等扩展 | | 是否处理 Caption 按钮 | 是负责绘制与定制 | 否仅根据 RTL/LTR 布局为 Caption 按钮预留空间 |功能规范中特别强调WinUI TitleBar 不处理 Caption 按钮——它只是依据 RTL 或 LTR 设置在布局中为系统 Caption 按钮的出现位置分配空间Caption 按钮及其定制依然由 AppWindow.TitleBar 负责。这意味着两者是协作关系而非替代关系。WinUI TitleBar 提供的能力开发规范列出了 WinUI TitleBar 的核心功能点HeaderArea例如 BackButton、PaneToggleButton 等导航头部元素Icon标题栏图标Title主标题文本Subtitle副标题文本常用于版本标识PreviewBeta等ContentArea内容区例如 AutoSuggestBox 搜索框FooterArea尾部区域例如 PersonPicture 头像Mica 透明支持背景可设为透明以透出 Mica 材质自定义高度默认 32px紧凑若内容区非空则自动切换为 48px展开。这些功能区最终落到一个 12 列的 Grid 模板布局上见 controls/dev/TitleBar/TitleBar.xaml左内边距列、BackButton 列、PaneToggleButton 列、LeftHeader 列、图标列、标题列、副标题列、内容区列占剩余宽度*、RightHeader 列、最小拖拽区列、右内边距列每一列都对应一个命名的模板部件。关键设计考量开发规范记录了标题栏设计中必须处理的若干边界问题这些考量直接决定了TitleBar.cpp的实现形态。拖拽区域的打孔Punch Hole一旦通过Window.SetTitleBar()将 TitleBar 设为窗口标题栏整个区域的输入都会被标记为 non-client非客户区从而变得不可交互。因此实现上必须针对每个可交互区域打一个孔punch hole被打孔穿透的区域变为不可拖拽可点击交互其余未打孔区域保持拖拽能力计算必须在SizeChanged事件触发时持续更新。自定义内容的可交互性判定开发规范提出了一个开放式问题TitleBar 将自定义内容一律视为可交互并打孔穿透拖拽区但如何允许更细粒度的定制若增加IsInteractive附加属性TitleBar 每次都需要遍历整棵可视化树来计算矩形成本过高若命名为InteractiveContent又限制了控件的可定制性参考案例Teams 的前进/后退按钮在禁用状态下依然是可拖拽的。在仓库的最终实现中这个问题被一种更完善的机制解决新增了IsDragRegion附加属性与AutoRefreshDragRegions开关见 controls/dev/TitleBar/TitleBar.idl 中[MUX_PUBLIC_V11]区块配合递归的可视化树遍历实现精确控制详见后文源码级深入一节。键盘导航与可访问性标题栏内的交互内容必须支持键盘导航应作为应用可视化树中的普通元素对待图标需符合 Windows 应用设计指南单击图标弹出系统窗口菜单双击关闭窗口存在最小拖拽区域的硬性要求例如 Store 应用中 PersonPicture 与 Caption 按钮之间的间隙该值在规范中记录为TitleBarMinDragRegionWidth规范文档标注 60px当前主题资源实现值为 48px见 controls/dev/TitleBar/TitleBar_themeresources.xaml。WinUI 3 缺失的 UWP 事件开发规范指出UWP 时代的CoreApplicationViewTitleBar.LayoutMetricsChanged与IsVisibleChanged事件在 WinUI 3 中缺失这带来两个直接后果LayoutMetricsChangedDPI 变化时需要更新左右 Inset右 Inset 在 WinUI TitleBar 中用于为 Caption 按钮预留占位空间IsVisibleChanged窗口进入全屏模式时TitleBar 需要感知并自动折叠自身。因此需要暴露相应事件或依赖属性以支持动态更新。在实现中UpdatePadding()通过读取AppWindow.TitleBar().LeftInset() / RightInset()并写入模板中LeftPaddingColumn / RightPaddingColumn两列的宽度来动态响应controls/dev/TitleBar/TitleBar.cpp同时监听FlowDirection变化以正确处理 RTL 布局下左右 Inset 的交换。其余待决问题ContentDialog 遮罩层内容对话框弹出时 TitleBar 是否仍应可拖拽若否需要暴露一个禁用拖拽的布尔 APIFlyout 感知Flyout 需要知道 TitleBar 的尺寸才能正确计算向上或向下展开最小窗口宽度应用本身有 MinSize 约束时如 Store 已设置 MinSize可以避免完全折叠 AutoSuggestBox但仍应针对最坏场景进行测试。真实产品场景与折叠策略开发规范以三个真实应用为例说明了不同产品对标题栏折叠行为的不同取舍StoreMicrosoft Store紧凑模式Minimal Mode下 AutoSuggestBox 折叠为图标形态同时折叠 Title 与 Subtitle由于 Store 设置了应用 MinSize无需完全折叠搜索框WinUI Gallery处理 NavigationView 的 BackButton 与 PaneToggleButton——紧凑模式下折叠并移动 PaneToggleButton 到标题栏Teams支持在内容区放置非标准元素如前进/后退的 箭头并在尾部区域放置其他按钮Visual Studio Code支持切换 Header 内容在图标之前或之后显示——该能力在文档标注为目前未实现。这些场景对应实现中的DisplayModeGroup视觉状态Compact/Expanded紧凑模式下折叠标题与副标题文本、将内容区左对齐并应用TitleBarCompactContentMargin边距见 TitleBar.xaml。实现细节非客户区打孔机制开发规范的 Implementation Details 一节描述了 TitleBar 最核心的底层机制仓库源码完整落地了这一设计。m_interactableElementsList一个贯穿 TitleBar 生命周期维护的可交互元素列表每当指定元素的可见性变化时更新包括BackButtonPaneToggleButtonHeaderLeftHeaderContentFooterRightHeader对应实现为 TitleBar.cpp 中的UpdateInteractableElementsList()依次把可见且启用的 BackButton、可见的 PaneToggleButton、LeftHeader 区域、Content 区域需递归查找子元素、RightHeader 区域加入列表。UpdateDragRegion()UpdateDragRegion()在SizeChanged与LayoutUpdated事件触发时调用检查m_interactableElementsList是否有子元素若有通过TransformToVisual获取每个元素相对窗口的矩形并按XamlRoot().RasterizationScale()换算为物理像素坐标GetBounds()TitleBar.cpp访问 IXP 层的InputNonClientPointerSource调用SetRegionRects(NonClientRegionKind::Passthrough, rects)将矩形设为穿透区域若无交互元素则调用ClearRegionRects清除全部穿透区域。实现中还有一个值得注意的优化m_previousPassthroughRects会缓存上次提交的矩形集合若本次计算出的矩形与上次完全相同则直接跳过SetRegionRects调用避免无谓的布局与输入系统开销。规范中特别提到需要编写自定义的 LayoutUpdated 事件因为默认的 LayoutUpdated 事件会为每个微小无关紧要的事件触发。仓库实现通过AutoRefreshDragRegions属性来管理这一成本为 Content 元素订阅LayoutUpdated若关闭自动刷新则在首次更新完成后自动取消订阅一次性行为并在布局变化时由RecomputeDragRegions()手动触发同步刷新。架构总览开发规范给出了 TitleBar 的架构定位关键公共组件TitleBar类关键内部组件TitleBarTemplateSettings负责计算拖拽区域相关值、TitleBarAutomationPeer手势识别TitleBar 必须同时处理鼠标、触摸与键盘三类输入场景。仓库中TitleBarTemplateSettings暴露IconElement属性将TitleBar.IconSource的值传递到模板内部供PART_Icon绑定使用模板中通过TemplatedParent路径绑定TemplateSettings.IconElementTitleBarAutomationPeer继承自FrameworkElementAutomationPeer负责将 TitleBar 类型暴露给 Microsoft UI Automation见 TitleBar.idl。完整 API 速查功能规范以 API Pages 形式详细给出了每个公共 API 的语义以下结合源码逐条整理命名空间Microsoft.UI.Xaml.Controls。TitleBar 类public class TitleBar : Control布局相关属性| 属性 | 类型 | 默认值 | 语义 | |--|--|--|--| |LeftHeader|UIElement|null| 位于标题文本左侧LTR 场景默认左对齐非空时控件自动切换为TitleBarExpandedHeight| |Title|String|null| 主标题紧凑模式或字符串为空时不显示 | |Subtitle|String|null| 副标题如 Preview紧凑模式或字符串为空时不显示 | |IconSource|IconSource|null| 标题栏图标 | |Content|UIElement|null| 内容区居中显示常用于 AutoSuggestBox非空时切换为展开高度 | |RightHeader|UIElement|null| 位于内容右侧LTR右对齐常用于 PersonPicture 与 More AppBarButton非空时切换为展开高度 |导航相关属性与事件| 成员 | 类型/签名 | 默认值 | 语义 | |--|--|--|--| |IsBackButtonVisible|Boolean|false| BackButton 可见性 | |IsBackButtonEnabled|Boolean|true| BackButton 的 IsEnabled通常绑定NavFrame.CanGoBack| |IsPaneToggleButtonVisible|Boolean|false| PaneToggleButton 可见性通常仅与 NavigationView 搭配 | |BackRequested|TypedEventHandlerTitleBar, Object| — | BackButton 被点击时触发 | |PaneToggleRequested|TypedEventHandlerTitleBar, Object| — | 内部 PaneToggleButton 引发 Click 时触发 |高度联动逻辑控件的高度由三个内容区LeftHeader、Content、RightHeader是否为空决定全部为空则使用TitleBarCompactHeight32px任一非空则使用TitleBarExpandedHeight48px。由于内容区默认全部为空TitleBar 默认高度为紧凑高度。对应实现见UpdateHeight()TitleBar.cpp它根据三个属性是否为 null 切换CompactHeight/ExpandedHeight视觉状态。MIDL3 定义节选IDL 中通过[contentproperty(Content)]声明内容属性使 XAML 中子元素可直接写入 Content属性默认值与规范一致[MUX_DEFAULT_VALUE(false)]等unsealed runtimeclass TitleBar : Microsoft.UI.Xaml.Controls.Control { TitleBar(); UIElement LeftHeader; String Title; String Subtitle; Microsoft.UI.Xaml.Controls.IconSource IconSource; UIElement Content; UIElement RightHeader; Boolean IsBackButtonVisible; Boolean IsBackButtonEnabled; Boolean IsPaneToggleButtonVisible; TitleBarTemplateSettings TemplateSettings{ get; }; event Windows.Foundation.TypedEventHandlerTitleBar, Object BackRequested; event Windows.Foundation.TypedEventHandlerTitleBar, Object PaneToggleRequested; // ... 对应依赖属性静态 Property }完整定义见 controls/dev/TitleBar/TitleBar.idl其中[MUX_PUBLIC_V8]与[MUX_PUBLIC_V11]标记了 API 分批公开的版本边界。主题资源功能规范仅列出需要特别说明的主题资源仓库中的实际定义TitleBar_themeresources.xaml如下| 资源 | 类型 | 值 | 说明 | |--|--|--|--| |TitleBarCompactHeight| Double | 32px | 紧凑/默认高度 | |TitleBarExpandedHeight| Double | 48px | 展开高度内容区非空时 | |TitleBarMinDragRegionWidth| Double | 60px规范值/ 48px当前实现值 | RightHeader 与 Caption 按钮之间的最小拖拽区域 |除上述关键资源外主题资源还定义了TitleBarDeactivatedOpacity0.5窗口失活时内容区透明度、TitleBarIconMaxWidth/MaxHeight16px、各区域边距、对齐方式以及 BackButton / PaneToggleButton 的完整样式。这些资源在Default、Light、HighContrast三个主题字典中均有对应定义确保深色、浅色与高对比度主题下标题栏前景色、背景色与按钮状态的正确呈现。实战场景一简单 TitleBar这是最基础的用法——只在标题栏中放置标题、副标题与图标。XAMLWindow x:ClassApp1.MainWindow xmlns:localusing:App1 mc:Ignorabled Grid Grid.RowDefinitions RowDefinition HeightAuto / !-- Title Bar -- RowDefinition Height* / !-- App Content -- /Grid.RowDefinitions TitleBar x:NameSimpleTitleBar TitleSimple TitleBar SubtitlePreview TitleBar.IconSource SymbolIconSource SymbolHome/ /TitleBar.IconSource /TitleBar !-- App content -- /Grid /WindowC# 代码后置public MainWindow() { this.InitializeComponent(); // C# code to set Window.TitleBar UIElement as Titlebar Window window this; window.ExtendsContentIntoTitleBar true; // Hides the default system titlebar. window.SetTitleBar(this.SimpleTitleBar); // Replace system titlebar with the WinUI Titlebar. // Note: If no title bar is specified, the default system titlebar will be rendered, // regardless of the ExtendsContentIntoTitleBar property. }两点使用前提需要特别注意TitleBar 目前必须显式放置在 Grid 行中并在代码后置中被Window引用如上所示规范提到正在考虑改进Window以省去额外的 Grid 布局与代码后置ExtendsContentIntoTitleBar并不自动启用 TitleBar——若未通过SetTitleBar指定标题栏即使该属性为 true系统仍会渲染默认标题栏。仓库测试应用中的用法与此完全一致TestUI/TitleBarPageWindow.xaml.csthis.ExtendsContentIntoTitleBar true;后紧跟this.SetTitleBar(this.WindowingTitleBar);。实战场景二集成 WinUI 控件在标题栏中同时放置AutoSuggestBox、PersonPicture、AppBarButton等常见 WinUI 控件充分利用 Content 与 RightHeader 两个区域TitleBar x:NameControlsTitleBar TitleControlsTitleBar SubtitlePreview BackgroundTransparent IsBackButtonVisibleTrue IsPaneToggleButtonVisibleTrue TitleBar.IconSource SymbolIconSource SymbolHome/ /TitleBar.IconSource TitleBar.Content AutoSuggestBox PlaceholderTextSearch QueryIconFind / /TitleBar.Content TitleBar.RightHeader StackPanel OrientationHorizontal AppBarButton IconMore LabelMoreSymbolIcon / PersonPicture DisplayNameJane Doe / /StackPanel /TitleBar.RightHeader /TitleBar这一场景的关键在于AutoSuggestBox 位于 Content 区、PersonPicture 位于 RightHeader 区两者都会被自动加入m_interactableElementsList并打孔穿透拖拽区因此搜索框可以正常接收输入、头像可以正常点击而标题栏其余区域仍可拖拽窗口。测试页 TestUI/TitleBarPage.xaml 中正是这样组合了 AutoSuggestBox 与 PersonPicture。实战场景三与 NavigationView 的 L-Pattern 集成标题栏与 NavigationView 组成经典的 L 形布局。TitleBar 会在其DesiredSize大于ActualSize时自动切换为紧凑显示模式并折叠 IconSource 与 Subtitle。XAMLGrid Grid.RowDefinitions RowDefinition HeightAuto / RowDefinition Height* / /Grid.RowDefinitions TitleBar x:NameNavViewTitleBar TitleNavView TitleBar SubtitlePreview IsBackButtonVisibleTrue IsBackButtonEnabled{x:Bind NavFrame.CanGoBack} BackRequestedNavViewTitleBar_BackRequested PaneToggleRequestedNavViewTitleBar_PaneToggleRequested TitleBar.IconSource SymbolIconSource SymbolHome/ /TitleBar.IconSource /TitleBar NavigationView x:NameNavView Grid.Column1 !-- TitleBar with NavigationView L-Pattern Overwriting resources -- NavigationView.Resources !-- This is the border between NavView and NavView Content -- Thickness x:KeyNavigationViewContentGridBorderThickness1,1,0,0/Thickness !-- This is the rounded corner on the Top left of the L Pattern -- CornerRadius x:KeyNavigationViewContentGridCornerRadius8,0,0,0/CornerRadius /NavigationView.Resources Frame x:NameNavFrame / NavigationView.MenuItems ... /NavigationView.MenuItems /NavigationView /GridC# 代码后置public MainWindow() { this.InitializeComponent(); Window window this; window.ExtendsContentIntoTitleBar true; window.SetTitleBar(this.NavViewTitleBar); } private void NavViewTitleBar_BackRequested(TitleBar sender, object args) { if (NavFrame.CanGoBack) { NavFrame.GoBack(); } } private void NavViewTitleBar_PaneToggleRequested(TitleBar sender, object args) { NavView.IsPaneOpen !NavView.IsPaneOpen; }要点说明IsBackButtonEnabled直接x:Bind到NavFrame.CanGoBackBackButton 不可用如无历史记录时自动禁用且禁用状态下该按钮按实现逻辑不会被加入可交互列表从而保留为可拖拽区域——这与设计文档中Teams 前进/后退按钮禁用时仍可拖拽的参考场景一致BackRequested与PaneToggleRequested事件对应实现中的OnBackButtonClick/OnPaneToggleButtonClick处理器TitleBar.cpp覆盖NavigationViewContentGridBorderThickness与NavigationViewContentGridCornerRadius两个资源是为了消除 NavView 与标题栏衔接处的边框与圆角形成连续的 L 形布局。源码级深入交互元素探测与失活态处理FindInteractableElements 的递归规则UpdateInteractableElementsList()对 Content 区域调用FindInteractableElements()TitleBar.cpp其决策规则值得开发者了解跳过不可见Visibility ! Visible或IsHitTestVisible false的元素——注意IsHitTestVisible是独立属性不会反映 Visibility必须单独检查若元素显式设置了IsDragRegionfalse整个元素视为可交互并加入列表停止向下递归元素边界已覆盖其内部元素若元素显式设置IsDragRegiontrue是 Control 类型整个控件视为可拖拽不进入其模板子树非 Control 容器如 Panel继续递归允许子元素用IsDragRegionfalse覆盖未显式设置时自动探测遇到已启用的 ControlButton、TextBox、ComboBox 等即加入列表并停止递归被禁用的 Control 继续向下递归保留祖先的拖拽意图未命中任何规则的元素递归遍历全部子节点。这套规则让整个面板拖拽、面板中个别按钮可点击这类混合布局成为可能给面板设置IsDragRegiontrue再给其中的按钮设置IsDragRegionfalse即可。窗口失活Deactivated状态实现通过InputActivationListener监听窗口激活状态TitleBar.cpp当窗口失活时BackButton、PaneToggleButton、图标、标题、副标题及各内容区统一切换为*Deactivated视觉状态——按钮前景切换为TitleBarDeactivatedForegroundBrush、内容区整体透明度降为TitleBarDeactivatedOpacity0.5与 Windows 原生标题栏的失活视觉一致。与 AppWindow 的双向联动标题同步UpdateTitle()在设置 Title 的同时会同步写入AppWindow.Title当 Title 清空或控件销毁时通过ResetTitle()安全恢复窗口的默认标题仅当当前标题与最后应用值一致时才恢复避免覆盖外部修改Inset 占位UpdatePadding()读取AppWindow.TitleBar()的LeftInset/RightInset动态设置模板左右内边距列的宽度为 Caption 按钮预留空间并在 RTL 场景下交换左右取值TitleBar.cpp图标点击区域UpdateIconRegion()通过SetRegionRects(NonClientRegionKind::Icon, ...)将图标区域标记为窗口图标区域使单击弹出系统窗口菜单、双击关闭窗口的系统行为得以保留。测试覆盖仓库在 controls/dev/TitleBar/InteractionTests/TitleBarTests.cs 中提供了基于 MUXControlsTestApp 的交互测试骨架并在 TestUI/TitleBarPage.xaml 中提供调试页面可切换 OutputDebugString 日志级别、通过MUXControlsTestHooks控制 TitleBar 的调试输出、用 Win32SetWindowLongPtr设置WS_EX_LAYOUTRTL验证 RTL 布局。开发者在集成 TitleBar 时可参考该测试页验证自定义场景下的拖拽区域行为。超出范围Out of Scope标签式标题栏Tabbed TitleBarTitleBar不面向 TabView 场景设计——该场景可能作为独立的TabbedTitleBar控件另行考虑。设计文档用 Terminal、Notepad、Edge 三个示例说明当 TabView 延伸进标题栏占满整个窗口时头部图标、按钮与拖拽区域均可交由 TabView 的 Header 与 FooterArea 处理但要求TabView 需要增加属性为图标或其他元素预留空间TabView 需要在右侧为拖拽区域预留空间FileExplorer 当前通过自行设置拖拽区域并在TabView.FooterArea放置 CaptionControl 占位符实现。Window.TitleBar 语法糖规范设想了对 Window 类的改进使 XAML 可以直接写成Window Window.TitleBar TitleBar / /Window.TitleBar /Window理想情况下这还应向 TitleBar 暴露Window.Title、AppWindow.Title与AppWindow.SetIcon()。但该设想超出 WinUI TitleBar 的范围未包含在规范内。附录Header / Content / Footer 的命名讨论开发规范记录了Header、Content、Footer命名的备选方案及其参考来源最终采纳的方案与 TabView 保持一致Header/Footer与TabView.TabStripHeader/TabView.TabStripFooter对齐Left*/Right*与 Pivot 和 ScrollViewer 对齐未采用Start/End参考Windows.UI.Xaml.TextAlignment未采用Before/After参考 CSS 与 Fluent Web UI未采用Leading/Trailing参考 Apple SwiftUI Toolbar未采用。实际公开 API 最终使用了LeftHeader、Content、RightHeader三个名称与功能规范及 TitleBar.idl 中的定义一致。延伸阅读开发规范原文docs/design-notes/TitleBar/titleBar-dev-spec.md功能规范原文docs/design-notes/TitleBar/titlebar-functional-spec.md接口定义controls/dev/TitleBar/TitleBar.idl核心实现controls/dev/TitleBar/TitleBar.cpp默认模板controls/dev/TitleBar/TitleBar.xaml主题资源controls/dev/TitleBar/TitleBar_themeresources.xaml测试页面controls/dev/TitleBar/TestUI/TitleBarPage.xaml 与 controls/dev/TitleBar/InteractionTests/TitleBarTests.cs【免费下载链接】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），仅供参考