UWP CommandBar 命令栏控件新特性实战：基于 Windows-universal-samples 的 XamlCommanding 示例深度解析

示例工程【免费下载链接】Windows-universal-samplesAPI samples for the Universal Windows Platform.项目地址https://gitcode.com/gh_mirrors/wi/Windows-universal-samples点击查看免费下载XamlCommanding 是 Windows-universal-samples 仓库中专门用于演示 Windows 10 下 XAMLCommandBar以及AppBar命令栏控件新特性与行为变化的官方示例。本文以该示例的 README 为骨架结合仓库内 C# 与 C 双语言实现共 8 个场景完整讲解命令栏按钮、默认图标体系、开合事件、样式定制、自定义内容托管与自适应重排等实战要点读完后你将能够在自己的 UWP 应用中熟练驾驭 CommandBar 的完整命令面。示例概览XamlCommanding 展示了什么在 Windows 10 上AppBar与CommandBar默认都是可见的且可以处于closed关闭或opened打开两种状态。处于关闭状态时应用栏可以提供minimal最小或compact紧凑两种提示形态也可以完全不提供任何提示当用户点击以省略号…形式出现的More按钮或通过代码将控件置为打开状态时应用栏/命令栏会过渡到打开状态。示例围绕以下六大主题组织每个主题对应一个独立场景页面CommandBar 专用按钮AppBarButton、AppBarToggleButton、AppBarSeparator可以像普通按钮一样使用但针对 CommandBar 进行了视觉优化标签中可以使用软连字符soft-hyphen提示换行位置。默认图标体系Windows 10 的默认图标集来自Segoe MDL2 Assets字体其字形度量使得字形可以像可缩放矢量图一样填充指定尺寸。Opening/Closing 事件演示新增的Opening、Closing事件以及动画完成后才触发的既有Opened、Closed事件。样式定制CommandBar 的溢出菜单overflow menu可以与显示PrimaryCommands的主栏分开独立设置样式。托管自定义内容CommandBar 现在支持通过Content属性显示自定义 UI在保留结构化命令面的同时支持更灵活的命令场景还可附加 Flyout。自适应屏幕尺寸默认控件不会随可用空间变化在溢出区与主栏之间重排命令示例通过子类化 CommandBar 并在MeasureOverride中加入额外逻辑实现重排。注意Windows universal samples 需要 Visual Studio 进行构建并需要 Windows 10 环境才能运行。运行环境与系统要求Client客户端Windows 10Server服务器Windows Server 2016 Technical PreviewPhone手机Windows 10示例同时提供 C#cs与 Ccpp两种语言的工程C 侧使用 C/CXcppcx编写两个工程的场景结构一一对应。构建与运行示例构建步骤如果下载的是整个 samples ZIP 包务必解压整个压缩包而不仅仅是包含目标示例的文件夹——示例依赖SharedContent目录中的共享代码。启动 Microsoft Visual Studio选择FileOpenProject/Solution。在解压目录中进入 Samples 子文件夹再进入本示例文件夹然后进入所需语言子文件夹C 或 C#双击 Visual Studio 解决方案文件.sln。按CtrlShiftB或选择BuildBuild Solution进行构建。部署与运行后续步骤取决于你是只想部署示例还是既部署又运行仅部署选择BuildDeploy Solution。部署并调试运行按F5或选择DebugStart Debugging。部署但不调试运行按CtrlF5或选择DebugStart Without Debugging。场景一CommandBar 专用按钮与软连字符换行Scenario1.xaml 演示了AppBarButton、AppBarToggleButton、AppBarSeparator三种按钮既可作为独立控件使用也可托管自定义内容还能出现在 CommandBar 中。AppBarButton与AppBarToggleButton均派生自ButtonBase因此可以像使用Button一样设置自定义Content或通过继承自ButtonBase.Flyout属性附加 Flyout但这些类型是为在 CommandBar 中使用而优化的——作为PrimaryCommand与SecondaryCommand出现时视觉外观会自动变化。XAML 中一个值得注意的细节是标签换行提示软连字符soft-hyphen字符0xADXAML 中写作#x00AD;可用于提示文本换行应发生的位置AppBarButton IconAccept LabelLongString#x00AD;UsingSoft#x00AD;Hyphens/ AppBarSeparator/ AppBarToggleButton IconContact LabelLongStringWithoutUsingSoftHyphens IsCheckedTrue/对比即可发现带软连字符的标签会按提示位置折行而 LongStringWithoutUsingSoftHyphens 这类长字符串在狭窄空间里则无法优雅换行。该场景同时演示了在独立面板与 CommandBar 内使用同一组按钮并在CommandBar.SecondaryCommands中重复放置它们。源码注释特别指出作为 SecondaryCommands 时custom content 与 Icon 是多余的因为它们在默认视觉中不会出现——溢出菜单中的次级命令只展示标签文本。场景二默认图标体系——Segoe MDL2 Assets 字体Scenario2.xaml 展示了 Windows 10 应用中图标体系的重大变化SymbolIcon与FontIcon默认使用新版Segoe MDL2 Assets字体中的字形而非旧版 Segoe UI Symbol。MDL2 字体与Symbol枚举中的字形存在 1:1 映射但除此之外与 Segoe UI Symbol 并不等价。新默认字体中的字形被设计为正好落在Em squareEm 方格上因此可以像可缩放资源一样直接调整尺寸使用。示例明确对比了两类图标的缩放行为SymbolIcon固定为 20x20不可缩放示例中用Border Height20 Width20验证。FontIcon通过FontSize自由缩放示例分别渲染了 12x12、20x20、32x32、48x48 四种尺寸的同一字形#xE106;。Border Height48 Width48 FontIcon Glyph#xE106; FontSize48/ /Border这一区别对设计自适应界面至关重要需要随设备分辨率缩放的图标应使用FontIcon MDL2 字形而固定尺寸的小图标可直接使用SymbolIcon。场景三Opening/Closing 事件与触发时机Scenario3.xaml 与其代码后置文件 Scenario3.xaml.cs 演示了 AppBar/CommandBar 上新增的Opening/Closing事件其效果是用户打开或关闭控件时动态改变背景透明度。事件触发时机的核心规则README 明示Opening/Closing在过渡动画开始之前触发Opened/Closed在过渡动画完成之后触发。代码后置实现如下初始时背景笔刷透明度为 50%Opening时置为 100%100% 不透明Closed时恢复 50%private void CommandBar_Opening(object sender, object e) { this.translucentBackgroundBrush.Opacity 1.0; MainPage.Current.NotifyUser(CommandBar: OPENING. Setting Background Opacity to 100%, NotifyType.ErrorMessage); } private void CommandBar_Closed(object sender, object e) { this.translucentBackgroundBrush.Opacity 0.5; MainPage.Current.NotifyUser(CommandBar: CLOSED. Setting Background Opacity to 50%, NotifyType.StatusMessage); }XAML 侧将四个事件全部挂到半透明背景的 CommandBar 上并附带多个主命令与次级命令CommandBar OpeningCommandBar_Opening ClosingCommandBar_Closing OpenedCommandBar_Opened ClosedCommandBar_Closed Background{StaticResource translucentBackgroundBrush} VerticalAlignmentBottom行为变化注意点README 与场景描述均强调控件不再响应边缘手势edgy gesture例如右键点击或WINKEY Z键盘快捷键都不会再打开命令栏。打开命令栏的唯一方式是点击 […] 省略号按钮或以编程方式设置IsOpen。场景四CommandBar 状态、布局与 ClosedDisplayModeScenario4.xaml 演示 CommandBar 的状态及其对布局的影响。控件在关闭状态下的大小由ClosedDisplayMode决定——改变它会影响布局而控件打开时不影响布局命令栏以浮层方式展开。页面提供三个交互控件IsOpenToggleButton双向绑定CommandBar.IsOpen以编程方式控制开合。IsStickyToggleButton默认情况下控件启用light-dismiss轻触关闭交互通过IsSticky属性可禁用该行为设为 true 后点击外部区域不再自动关闭。ClosedDisplayModeComboBox提供Compact紧凑、Minimal最小、Hidden隐藏三种关闭形态。CommandBar x:Namecmdbar IsOpen{Binding IsChecked, ElementNameisopentoggle, ModeTwoWay} IsSticky{Binding IsChecked, ElementNameisstickytoggle, ModeTwoWay} ClosedDisplayMode{Binding SelectedItem.Content, ElementNamecombobox}布局演示方式在 StackPanel 中于 CommandBar 上方与下方各放置一张图片可以直观看到切换ClosedDisplayMode时控件占据的高度如何变化而打开状态下命令栏浮在内容之上不挤压布局。场景五多个 CommandBar 内联放置Scenario5.xaml 说明 CommandBar 可以像普通控件一样与其他 UI 元素内联放置并不局限于屏幕顶部/底部的边缘位置。示例在同一个 Grid 中放置了四个 CommandBar左上、右上不同背景色、水平垂直居中的交叉位置以及底部各自使用不同的VerticalAlignment、HorizontalAlignment与背景画刷SystemControlBackgroundAccentBrush、SystemControlBackgroundListMediumBrush。CommandBar VerticalAlignmentTop Background{ThemeResource SystemControlBackgroundAccentBrush}/ CommandBar VerticalAlignmentTop Grid.Column1 Background{ThemeResource SystemControlBackgroundListMediumBrush}/ CommandBar VerticalAlignmentCenter HorizontalAlignmentCenter Grid.ColumnSpan2 Background{ThemeResource SystemControlBackgroundListMediumBrush}/ CommandBar VerticalAlignmentBottom Grid.ColumnSpan2/与场景三相同这里也再次注明CommandBar 不再响应右键或 WINKEY Z 等边缘手势打开。场景六样式化 CommandBar 与溢出菜单Scenario6.xaml 演示 CommandBar 的样式定制。CommandBar 有两个主要的视觉部分主栏bar呈现PrimaryCommandsCommandBar上的Background等属性只影响这一部分。溢出菜单overflow menu呈现SecondaryCommands其样式由CommandBarOverflowPresenterStyle属性决定。示例在Page.Resources中定义了一个针对CommandBarOverflowPresenter的完整自定义样式customOverflowStyle包含滚动行为、背景、边框与模板Style x:KeycustomOverflowStyle TargetTypeCommandBarOverflowPresenter Setter PropertyScrollViewer.HorizontalScrollMode ValueDisabled / Setter PropertyScrollViewer.VerticalScrollBarVisibility ValueAuto / Setter PropertyBackground Value{ThemeResource SystemControlBackgroundAccentBrush}/ Setter PropertyBorderThickness Value8/ Setter PropertyBorderBrush ValueWhite/ Setter PropertyMaxHeight Value154/ Setter PropertyWidth Value320/ Setter PropertyTemplate Setter.Value ControlTemplate TargetTypeCommandBarOverflowPresenter Border Background{TemplateBinding Background} BorderBrush{TemplateBinding BorderBrush} BorderThickness{TemplateBinding BorderThickness} ScrollViewer ... ItemsPresenter x:NameItemsPresenter Margin0,0,0,24 / /ScrollViewer /Border /ControlTemplate /Setter.Value /Setter /Style随后通过CommandBarOverflowPresenterStyle{StaticResource customOverflowStyle}挂到主栏上。值得注意的是溢出菜单项Menu item 1..7只设置了Label因为在默认视觉中次级命令只显示文本。场景七托管自定义内容ContentScenario7.xaml 演示作为ContentControl的 CommandBar 对Content属性的支持。README 与场景描述给出了三条关键约束Content属性必须在 XAML 中显式引用即显式声明CommandBar.Content否则不会显示。当同时存在PrimaryCommands与Content时PrimaryCommands 优先级更高可能导致 Content 被裁剪。当ClosedDisplayMode Compact时若 Content 大于命令栏紧凑尺寸则可能被裁剪可以利用Opening/Closed事件来显示/隐藏 Content 区域的部分 UI。当ClosedDisplayMode Minimal时Content 会被自动隐藏因为整条栏变成了一个大的点击目标供用户打开控件。示例 XAML 中Content 区域放置了一个包含 AppBarButton、TextBox 与 OK/Cancel 按钮的自定义 GridCommandBar.Content Grid StackPanel OrientationHorizontal HorizontalAlignmentLeft AppBarButton IconAccept LabelClipped when Compact/ TextBox PlaceholderTextThis is a TextBox MinWidth196 Height48 Margin12,0 VerticalAlignmentTop/ AppBarButton x:Nameappbarbutton IconAdd LabelOnly visible when opened IsCompactTrue/ /StackPanel ... /Grid /CommandBar.Content其中IsCompactTrue的 AppBarButton 被刻意命名为 Only visible when opened配合Opening事件即可实现仅在打开时显示的联动效果。场景八自适应屏幕尺寸——DynamicCommandBar 重排机制默认的 CommandBar不会自动将命令从PrimaryCommands重排到SecondaryCommands溢出菜单。这是本示例最具技术深度的一个场景Scenario8.xaml 与 DynamicCommandBar.csC 对应实现见 DynamicCommandBar.h / DynamicCommandBar.cpp通过子类化 CommandBar并在MeasureOverride中加入额外逻辑实现了这一目标。核心设计DynamicCommandBar公开了一个ContentMinWidth依赖属性默认值 0.0用于为 Content 区域设置最小宽度以覆盖内容被 PrimaryCommands 裁剪的默认行为public static readonly DependencyProperty ContentMinWidthProperty DependencyProperty.Register(ContentMinWidth, typeof(double), typeof(DynamicCommandBar), new PropertyMetadata(0.0d));在OnApplyTemplate中通过模板子元素名获取MoreButton省略号展开按钮以便在测量时计入其宽度protected override void OnApplyTemplate() { base.OnApplyTemplate(); moreButton this.GetTemplateChild(MoreButton) as Button; }重排算法MeasureOverride重排逻辑分两个阶段对应源码注释 First, move items to the overflow... 与 Next move items out of the overflow...溢出收缩阶段从PrimaryCommands末尾向前遍历累加每个命令的DesiredSize.Width、MoreButton 宽度与 ContentMinWidth得到requestedWidth当requestedWidth availableSize.Width时将末尾命令移入SecondaryCommands顶部同时把AppBarSeparator移入一个独立的separatorQueue队列——这样被移动的命令与原本就在溢出区的命令之间会插入分隔符加以区分且不会出现孤立分隔符。回流恢复阶段当空间重新充足requestedWidth separatorQueueWidth 溢出栈顶元素宽度 availableSize.Width时把命令从溢出区移回PrimaryCommands并将积压的分隔符一并回移若移回后溢出区顶部剩下孤立分隔符则将其摘除并回收。每个移入溢出的条目都会以TupleICommandBarElement, double元素 测量宽度压入overflow栈保证移回时使用一致的宽度度量。场景中的使用方式local:DynamicCommandBar VerticalAlignmentBottom ContentMinWidth196 Grid.Row1 local:DynamicCommandBar.Content TextBlock ... TextContent Area/ /local:DynamicCommandBar.Content AppBarButton IconAccept LabelAccept/ AppBarButton IconAccount LabelAccount/ AppBarSeparator/ AppBarButton IconAlignCenter LabelAlign Center MinWidth96/ ... /local:DynamicCommandBar同时示例为对齐类按钮设置了MinWidth96/120使按钮在溢出区与主栏之间来回重排时能保持一致的宽度行为正确。需要实现命令随窗口宽度自适应收拢/展开的 UWP 应用可以直接参考这一子类化方案。相关主题与参考相关示例Context Menus上下文菜单与命令栏配合的右键/长按菜单场景。UI BasicsUI 基础XAML 控件与布局基础。Navigation导航页面导航与框架管理。参考 APIAppBarWindows.UI.Xaml.Controls.AppBarAppBarButtonWindows.UI.Xaml.Controls.AppBarButtonAppBarToggleButtonWindows.UI.Xaml.Controls.AppBarToggleButtonAppBarSeparatorWindows.UI.Xaml.Controls.AppBarSeparatorCommandBarWindows.UI.Xaml.Controls.CommandBarFlyoutWindows.UI.Xaml.Controls.FlyoutMenuFlyoutWindows.UI.Xaml.Controls.MenuFlyout小结XamlCommanding 示例完整覆盖了 Windows 10 时代 CommandBar 的全部关键新特性专用命令按钮与软连字符换行、基于 Segoe MDL2 Assets 的可缩放图标、Opening/Closing 事件时序、ClosedDisplayMode 状态与布局影响、溢出菜单独立样式、Content 自定义内容托管以及通过子类化 MeasureOverride实现的命令自适应重排。文中所有行为说明均可直接对照仓库中 cs 与 cpp 两个实现进行验证是构建高质量 UWP 命令面的可靠参考起点。赞分享示例工程【免费下载链接】Windows-universal-samplesAPI samples for the Universal Windows Platform.项目地址https://gitcode.com/gh_mirrors/wi/Windows-universal-samples点击查看免费下载相关推荐SleeperXmacOS系统级电源管理框架的技术实现与应用SleeperXmacOS系统级电源管理框架的技术实现与应用 在macOS生态系统中电源管理一直是一个复杂而关键的技术领域。对于需要在特定场景下保持系统活跃示例工程终极指南如何轻松自定义和扩展Octokit.net的GitHub客户端功能终极指南如何轻松自定义和扩展Octokit.net的GitHub客户端功能 Octokit.net是一个强大的GitHub API客户端库专为.NET开发者示例工程UWP 应用数据存储实战Windows-universal-samples 之 ApplicationData 示例深度解析UWP 应用数据存储实战Windows universal samples 之 ApplicationData 示例深度解析 导读 本文以 Windows u示例工程上一篇react-native-router-flux 离线应用未来时间晶体存储下一篇Quivr解决企业知识孤岛问题的下一代RAG系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考