From 13c82aa0ac13663c16ee07cba264f4167b530ef7 Mon Sep 17 00:00:00 2001 From: Qiutong Shen Date: Tue, 19 May 2026 14:35:27 +0800 Subject: [PATCH] fix(develop): UI control samples and visual element corrections --- hub/apps/develop/ui/controls/animated-icon.md | 4 ++-- hub/apps/develop/ui/controls/breadcrumbbar.md | 2 +- hub/apps/develop/ui/controls/buttons.md | 2 +- hub/apps/develop/ui/controls/combo-box.md | 10 +++++----- hub/apps/develop/ui/controls/commanding.md | 10 +--------- .../develop/ui/controls/controls-and-events-intro.md | 2 +- .../develop/ui/controls/custom-transport-controls.md | 2 +- .../develop/ui/controls/dialogs-and-flyouts/flyouts.md | 2 +- .../ui/controls/dialogs-and-flyouts/teaching-tip.md | 2 +- .../develop/ui/controls/item-templates-listview.md | 2 +- hub/apps/develop/ui/controls/listview-filtering.md | 6 +++--- hub/apps/develop/ui/controls/radio-button.md | 2 +- hub/apps/develop/ui/controls/text-block.md | 2 +- hub/apps/develop/ui/controls/title-bar.md | 2 +- hub/apps/develop/ui/controls/tree-view.md | 2 +- hub/apps/develop/ui/in-app-acrylic.md | 2 +- .../ui/navigation/navigate-between-two-pages.md | 4 ++-- hub/apps/develop/ui/sound.md | 4 ++-- 18 files changed, 27 insertions(+), 35 deletions(-) diff --git a/hub/apps/develop/ui/controls/animated-icon.md b/hub/apps/develop/ui/controls/animated-icon.md index 3e6675ae31..7e4896b55c 100644 --- a/hub/apps/develop/ui/controls/animated-icon.md +++ b/hub/apps/develop/ui/controls/animated-icon.md @@ -49,7 +49,7 @@ Defining a color property in your Lottie animation named "Foreground" lets you t ## Recommendations -- Please view the UX guidance for [Icons for Windows Apps](/windows/uwp/design/style/icons) to ensure your icons match the design principles. +- Please view the UX guidance for [Icons for Windows Apps](/windows/apps/design/style/icons) to ensure your icons match the design principles. - Limit the number of animated icons on a single screen or view. Only animate icons to draw the user's attention to where they need to take action or when they are performing an action. ## Create an animated icon @@ -211,7 +211,7 @@ private void Button_PointerEntered(object sender, PointerRoutedEventArgs e) private void Button_PointerExited(object sender, PointerRoutedEventArgs e) { - AnimatedIcon.SetState(this.StackPaAnimatedIcon1nel1, "Normal"); + AnimatedIcon.SetState(this.AnimatedIcon1, "Normal"); } ``` diff --git a/hub/apps/develop/ui/controls/breadcrumbbar.md b/hub/apps/develop/ui/controls/breadcrumbbar.md index 4f0cc48329..92f462abe1 100644 --- a/hub/apps/develop/ui/controls/breadcrumbbar.md +++ b/hub/apps/develop/ui/controls/breadcrumbbar.md @@ -46,7 +46,7 @@ The image below shows the parts of the `BreadcrumbBar` control. You can modify t > [!div class="checklist"] > -> - **Important APIs:** [BreadcrumbBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.button) +> - **Important APIs:** [BreadcrumbBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.breadcrumbbar) > [!div class="nextstepaction"] > [Open the WinUI 3 Gallery app and see the BreadcrumbBar in action](winui3gallery://item/BreadcrumbBar) diff --git a/hub/apps/develop/ui/controls/buttons.md b/hub/apps/develop/ui/controls/buttons.md index e5b6496924..194eebbcc0 100644 --- a/hub/apps/develop/ui/controls/buttons.md +++ b/hub/apps/develop/ui/controls/buttons.md @@ -238,7 +238,7 @@ private void Decrease_Click(object sender, RoutedEventArgs e) > [!div class="checklist"] > -> - **Important APIs**: [DropDownButton class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.button), [Flyout property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.button.flyout) +> - **Important APIs**: [DropDownButton class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.dropdownbutton), [Flyout property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.button.flyout) > [!div class="nextstepaction"] > [Open the WinUI 3 Gallery app and see the DropdownButton in action](winui3gallery://item/DropdownButton) diff --git a/hub/apps/develop/ui/controls/combo-box.md b/hub/apps/develop/ui/controls/combo-box.md index d928231062..30b8d3ac7f 100644 --- a/hub/apps/develop/ui/controls/combo-box.md +++ b/hub/apps/develop/ui/controls/combo-box.md @@ -102,9 +102,9 @@ The following example demonstrates binding a combo box to a collection of FontFa ```csharp ObservableCollection fonts = new ObservableCollection() { - fonts.Add(new FontFamily("Arial")); - fonts.Add(new FontFamily("Courier New")); - fonts.Add(new FontFamily("Times New Roman")); + new FontFamily("Arial"), + new FontFamily("Courier New"), + new FontFamily("Times New Roman") }; ``` @@ -228,7 +228,7 @@ If the newly entered value is not valid, you use the SelectedValue to revert the ```csharp private void FontSizeComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e) { - if (byte.TryParse(e.Text, out double newValue)) + if (double.TryParse(e.Text, out double newValue)) { // Update the app's font size. _fontSize = newValue; @@ -263,7 +263,7 @@ private void FavoriteColorComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSu { ColorName = e.Text, Color = ColorFromStringConverter(e.Text) - } + }; ListOfColors.Add(newColor); } else diff --git a/hub/apps/develop/ui/controls/commanding.md b/hub/apps/develop/ui/controls/commanding.md index cbcb222447..0ee020f6dd 100644 --- a/hub/apps/develop/ui/controls/commanding.md +++ b/hub/apps/develop/ui/controls/commanding.md @@ -369,9 +369,6 @@ If you need to create a command that isn't defined by the [StandardUICommand](/w *XamlUICommandSample* -| Download the code for this example | -| -------------------- | -| [WinUI commanding sample (XamlUICommand)](https://github.com/MicrosoftDocs/windows-topic-specific-samples/archive/uwp-commanding-xamluicommand.zip) | | Download the code for this example | | -------------------- | | [Commanding sample (XamlUICommand)](https://github.com/MicrosoftDocs/windows-topic-specific-samples/archive/uwp-commanding-xamluicommand.zip) | @@ -609,7 +606,7 @@ The most basic way to support a structured commanding experience is to define an > [!NOTE] > In some cases, it might be just as efficient to bind a method to the Click event and a property to the IsEnabled property. -Standard WinUI controls (button, list, selection, calendar, predictive text) provide the basis for many common command experiences. For a complete list of control types, see [Controls and patterns for Windows apps](../../../design/controls/index.md). + #### Example ![Command interface example](images/commanding/icommand.gif) @@ -622,10 +619,6 @@ Standard WinUI controls (button, list, selection, calendar, predictive text) pro In this basic example, we demonstrate how a single command can be invoked with a button click, a keyboard accelerator, and rotating a mouse wheel. -| Download the code for this example | -| -------------------- | -| [Commanding sample (ICommand)](https://github.com/MicrosoftDocs/windows-topic-specific-samples/archive/uwp-commanding-icommand.zip) | - ```xaml **Important APIs**: [MediaPlayerElement](/uwp/api/windows.ui.xaml.controls.mediaplayerelement), [MediaPlayerElement.AreTransportControlsEnabled](/uwp/api/windows.ui.xaml.controls.mediaplayerelement.aretransportcontrolsenabled), [MediaTransportControls](/uwp/api/Windows.Media.SystemMediaTransportControls) +> **Important APIs**: [MediaPlayerElement](/uwp/api/windows.ui.xaml.controls.mediaplayerelement), [MediaPlayerElement.AreTransportControlsEnabled](/uwp/api/windows.ui.xaml.controls.mediaplayerelement.aretransportcontrolsenabled), [MediaTransportControls](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediatransportcontrols) Before starting, you should be familiar with the MediaPlayerElement and the MediaTransportControls classes. For more info, see the MediaPlayerElement control guide. diff --git a/hub/apps/develop/ui/controls/dialogs-and-flyouts/flyouts.md b/hub/apps/develop/ui/controls/dialogs-and-flyouts/flyouts.md index ffe0ccfc9e..3fb60ad6e4 100644 --- a/hub/apps/develop/ui/controls/dialogs-and-flyouts/flyouts.md +++ b/hub/apps/develop/ui/controls/dialogs-and-flyouts/flyouts.md @@ -189,7 +189,7 @@ private void Folder2_Click(object sender, RoutedEventArgs e) flyout.OverlayInputPassThroughElement = FavoritesBar; ... flyout.ShowAt(sender as FrameworkElement); -{ +} ``` ## Related articles diff --git a/hub/apps/develop/ui/controls/dialogs-and-flyouts/teaching-tip.md b/hub/apps/develop/ui/controls/dialogs-and-flyouts/teaching-tip.md index da45551b31..dc2cc7add4 100644 --- a/hub/apps/develop/ui/controls/dialogs-and-flyouts/teaching-tip.md +++ b/hub/apps/develop/ui/controls/dialogs-and-flyouts/teaching-tip.md @@ -255,7 +255,7 @@ An icon can be added beside the title and subtitle using the [IconSource](/windo diff --git a/hub/apps/develop/ui/controls/item-templates-listview.md b/hub/apps/develop/ui/controls/item-templates-listview.md index 88e1fb15d5..25d2d035cc 100644 --- a/hub/apps/develop/ui/controls/item-templates-listview.md +++ b/hub/apps/develop/ui/controls/item-templates-listview.md @@ -13,7 +13,7 @@ This section contains item templates that you can use with a [**ListView**](/win To demonstrate data binding, these templates bind **ListViewItems** to the example Recording class from the [data binding overview](/windows/uwp/data-binding/data-binding-quickstart). > [!NOTE] -> Currently, when a **DataTemplate** contains multiple controls (for example, more than a single **TextBlock**), the default accessible name for screenreaders comes from .ToString() on the item. As a convenience you can instead set the [**AutomationProperties.Name**](/uwp/api/windows.ui.xaml.automation.automationproperties) on the root element of the **DataTemplate**. For more on accessibility, see [Accessibility overview](../../../design/accessibility/accessibility-overview.md). +> Currently, when a **DataTemplate** contains multiple controls (for example, more than a single **TextBlock**), the default accessible name for screenreaders comes from .ToString() on the item. As a convenience you can instead set the [**AutomationProperties.Name**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.automation.automationproperties.name) on the root element of the **DataTemplate**. For more on accessibility, see [Accessibility overview](../../../design/accessibility/accessibility-overview.md). ## Single line list item Use this template to display a list of items with an image and a single line of text. diff --git a/hub/apps/develop/ui/controls/listview-filtering.md b/hub/apps/develop/ui/controls/listview-filtering.md index 7d4ba29390..f534aa4c39 100644 --- a/hub/apps/develop/ui/controls/listview-filtering.md +++ b/hub/apps/develop/ui/controls/listview-filtering.md @@ -22,7 +22,7 @@ To implement text filtering, your app will need a [ListView](/windows/windows-ap The following XAML shows a UI with a simple ListView along with an accompanying TextBox. In this example, the ListView displays a collection of `Contact` objects. `Contact` is a class defined in the code-behind, and each `Contact` object has the following properties: `FirstName`, `LastName`, and `Company`. -The user can type a filtering term into the TextBox to filter the list of `Contact` objects by last name. The TextBox has it's `x:Name` attribute set (`FilterByLastName`) so you can access the TextBox's [Text](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox.text) property in the code-behind. You also handle it's [TextChanged](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox.textchanged) event (`OnFilterChanged`). The TextChanged event occurs whenever the user types in the TextBox, letting you perform a filtering operation upon receiving user input. +The user can type a filtering term into the TextBox to filter the list of `Contact` objects by last name. The TextBox has its `x:Name` attribute set (`FilterByLastName`) so you can access the TextBox's [Text](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox.text) property in the code-behind. You also handle its [TextChanged](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox.textchanged) event (`OnFilterChanged`). The TextChanged event occurs whenever the user types in the TextBox, letting you perform a filtering operation upon receiving user input. For filtering to work, the ListView must have a data source that can be manipulated in the code-behind, such as an [ObservableCollection\](/dotnet/api/system.collections.objectmodel.observablecollection-1). In this case, the ListView's [ItemsSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemscontrol.itemssource) property is assigned to an `ObservableCollection` in the code-behind. @@ -51,7 +51,7 @@ For filtering to work, the ListView must have a data source that can be manipula To start, you'll need to initialize your original data source in a separate collection, such as a [List\](/dotnet/api/system.collections.generic.list-1). In this example, you have a `List` called `allContacts` that holds all of the `Contact` objects that can potentially be shown in the ListView. -You'll also need a collection to hold the filtered data, which will constantly change every time a filter is applied. For this, you'll use an [ObservableCollection\](/dotnet/api/system.collections.objectmodel.observablecollection-1) so that the ListView is notified to update whenever the collection changes. In this example, it's an `ObservableCollection` called `contactsFiltered`, and is the [ItemsSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemscontrol.itemssource) for the ListView. At initialization, it will have the same contents as `allContacts`. +You'll also need a collection to hold the filtered data, which will constantly change every time a filter is applied. For this, you'll use an [ObservableCollection\](/dotnet/api/system.collections.objectmodel.observablecollection-1) so that the ListView is notified to update whenever the collection changes. In this example, it's an `ObservableCollection` called `contactsFiltered`, and is the [ItemsSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.itemscontrol.itemssource) for the ListView. At initialization, it will have the same contents as `allContacts`. The filtering operation is performed through these steps, shown in the following code: @@ -87,7 +87,7 @@ public sealed partial class MainPage : Page // contactsFiltered). Set this newly populated collection as the // ItemsSource for the ListView. contactsFiltered = new ObservableCollection(allContacts); - Filtereditemscontrol.itemssource = contactsFiltered; + FilteredListView.ItemsSource = contactsFiltered; } // Whenever text changes in the filtering text box, this function is called: diff --git a/hub/apps/develop/ui/controls/radio-button.md b/hub/apps/develop/ui/controls/radio-button.md index 9bc470d61e..8a1a2fcc32 100644 --- a/hub/apps/develop/ui/controls/radio-button.md +++ b/hub/apps/develop/ui/controls/radio-button.md @@ -354,7 +354,7 @@ public sealed partial class MainPage : Page List colorOptionItems; - public MainPage1() + public MainPage() { this.InitializeComponent(); diff --git a/hub/apps/develop/ui/controls/text-block.md b/hub/apps/develop/ui/controls/text-block.md index 3a4138b3d6..70a685506e 100644 --- a/hub/apps/develop/ui/controls/text-block.md +++ b/hub/apps/develop/ui/controls/text-block.md @@ -95,7 +95,7 @@ In this example, the first TextBlock is rendered using the fast path, while the This text is NOT on the fast path. - + ``` When you run this XAML in debug mode with [IsTextPerformanceVisualizationEnabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.debugsettings.istextperformancevisualizationenabled) set to `true`, the result looks like this. diff --git a/hub/apps/develop/ui/controls/title-bar.md b/hub/apps/develop/ui/controls/title-bar.md index 39e4a83707..d969de6912 100644 --- a/hub/apps/develop/ui/controls/title-bar.md +++ b/hub/apps/develop/ui/controls/title-bar.md @@ -30,7 +30,7 @@ The title bar is divided into these areas: ![Screenshot showing the parts of a title bar control.](images/titlebar/title-bar-parts.png) - **Back button:** [IsBackButtonEnabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonenabled), [IsBackButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonvisible), [BackRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.backrequested) - A built-in back button for navigation. -- **Pane toggle button:** [IsPaneToggleButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonenabled), [PaneToggleRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.panetogglerequested) - This button is intended to be used in conjunction with the NavigationView control. +- **Pane toggle button:** [IsPaneToggleButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.ispanetogglebuttonvisible), [PaneToggleRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.panetogglerequested) - This button is intended to be used in conjunction with the NavigationView control. - **Left header:** [LeftHeader](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.leftheader) - **Icon:** [IconSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.iconsource) - **Title:** [Title](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.title) diff --git a/hub/apps/develop/ui/controls/tree-view.md b/hub/apps/develop/ui/controls/tree-view.md index a970fc5446..00c7274474 100644 --- a/hub/apps/develop/ui/controls/tree-view.md +++ b/hub/apps/develop/ui/controls/tree-view.md @@ -327,7 +327,7 @@ There are 2 ways you can expand or collapse a tree view node in your code. You might need to show a large number of nodes in your tree view, or you might not know ahead of time how many nodes it will have. The **TreeView** control is not virtualized, so you can manage resources by filling each node as it's expanded, and removing the child nodes when it's collapsed. -Handle the [Expanding](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.treeview.expand) event and use the [HasUnrealizedChildren](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.treeviewnode.hasunrealizedchildren) property to add children to a node when it's being expanded. The **HasUnrealizedChildren** property indicates whether the node needs to be filled, or if its **Children** collection has already been populated. It's important to remember that the **TreeViewNode** doesn't set this value, you need to manage it in your app code. +Handle the [Expanding](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.treeview.expanding) event and use the [HasUnrealizedChildren](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.treeviewnode.hasunrealizedchildren) property to add children to a node when it's being expanded. The **HasUnrealizedChildren** property indicates whether the node needs to be filled, or if its **Children** collection has already been populated. It's important to remember that the **TreeViewNode** doesn't set this value, you need to manage it in your app code. Here's an example of these APIs in use. See the complete example code at the end of this article for context, including the implementation of **FillTreeNode**. diff --git a/hub/apps/develop/ui/in-app-acrylic.md b/hub/apps/develop/ui/in-app-acrylic.md index 4cc3446f59..49cec2776a 100644 --- a/hub/apps/develop/ui/in-app-acrylic.md +++ b/hub/apps/develop/ui/in-app-acrylic.md @@ -76,7 +76,7 @@ myBrush.TintColor = Color.FromArgb(255, 202, 24, 37); myBrush.FallbackColor = Color.FromArgb(255, 202, 24, 37); myBrush.TintOpacity = 0.6; -grid.Fill = myBrush; +grid.Background = myBrush; ``` ## Related articles diff --git a/hub/apps/develop/ui/navigation/navigate-between-two-pages.md b/hub/apps/develop/ui/navigation/navigate-between-two-pages.md index a88087fa85..0c48c21622 100644 --- a/hub/apps/develop/ui/navigation/navigate-between-two-pages.md +++ b/hub/apps/develop/ui/navigation/navigate-between-two-pages.md @@ -441,13 +441,13 @@ using namespace winrt::Microsoft::UI::Xaml::Media::Animation; // ... -void winrt::BasicNavigation::implementation::MainPage::HyperlinkButton_Click(winrt::Windows::Foundation::IInspectable const& sender, winrt::Microsoft::UI::Xaml::RoutedEventArgs const& e) +void winrt::BasicNavigation::implementation::Page2::HyperlinkButton_Click(winrt::Windows::Foundation::IInspectable const& sender, winrt::Microsoft::UI::Xaml::RoutedEventArgs const& e) { // Create the slide transition and set the transition effect to FromLeft. SlideNavigationTransitionInfo slideEffect = SlideNavigationTransitionInfo(); slideEffect.Effect(SlideNavigationTransitionEffect(SlideNavigationTransitionEffect::FromLeft)); Frame().Navigate(winrt::xaml_typename(), - nullptr, + nullptr, slideEffect); } ``` diff --git a/hub/apps/develop/ui/sound.md b/hub/apps/develop/ui/sound.md index bc40baf8a6..89d7cefab3 100644 --- a/hub/apps/develop/ui/sound.md +++ b/hub/apps/develop/ui/sound.md @@ -63,14 +63,14 @@ Where maximum volume (relative to system volume) is 1.0, and minimum is 0.0 (ess If a control's default sound is not desired, it can be disabled. This is done through the **ElementSoundMode** on the control. -The **ElementSoundMode** has two states: **Off** and **Default**. When not set, it is **Default**. If set to **Off**, every sound that control plays will be muted *except for focus*. +The **ElementSoundMode** has three states: **Default**, **FocusOnly**, and **Off**. When not set, it is **Default**. If set to **FocusOnly**, only focus sounds play. If set to **Off**, no sounds play for that control. ```XAML