Toolbaritem and MenuItem (#1626)
* Toolbaritems * Fix broken xref. * Edits. * Edits. * Initial menuitem content. * Content complete. * Fix image links. * Edits.
This commit is contained in:
David Britch
GitHub
Родитель
0ab6c98d2c
Коммит
f3a9523051
|
|
@ -413,6 +413,8 @@
|
|||
href: user-interface/controls/twopaneview.md
|
||||
- name: Display pop-ups
|
||||
href: user-interface/pop-ups.md
|
||||
- name: Display toolbar items
|
||||
href: user-interface/toolbaritem.md
|
||||
- name: Display tooltips
|
||||
href: user-interface/tooltips.md
|
||||
- name: Fonts
|
||||
|
|
@ -449,6 +451,8 @@
|
|||
href: user-interface/context-menu.md
|
||||
- name: Display a menu bar
|
||||
href: user-interface/menu-bar.md
|
||||
- name: Display menu items
|
||||
href: user-interface/menuitem.md
|
||||
- name: Shadows
|
||||
href: user-interface/shadow.md
|
||||
- name: Styles
|
||||
|
|
|
|||
|
|
@ -246,7 +246,7 @@ This template can be used for as a basis for making alterations to the existing
|
|||
In addition, the <xref:Microsoft.Maui.Controls.Grid>, <xref:Microsoft.Maui.Controls.Image>, and <xref:Microsoft.Maui.Controls.Label> elements all have `x:Name` values and so can be targeted with the Visual State Manager. For more information, see [Set state on multiple elements](~/user-interface/visual-states.md#set-state-on-multiple-elements).
|
||||
|
||||
> [!NOTE]
|
||||
> The same template can also be used for `MenuItem` objects.
|
||||
> The same template can also be used for <xref:Microsoft.Maui.Controls.MenuItem> objects.
|
||||
|
||||
### Replace flyout content
|
||||
|
||||
|
|
@ -306,11 +306,11 @@ Alternatively, flyout content can be defined by setting the `Shell.FlyoutContent
|
|||
|
||||
## Menu items
|
||||
|
||||
Menu items can be optionally added to the flyout, and each menu item is represented by a `MenuItem` object. The position of `MenuItem` objects on the flyout is dependent upon their declaration order in the Shell visual hierarchy. Therefore, any `MenuItem` objects declared before <xref:Microsoft.Maui.Controls.FlyoutItem> objects will appear before the <xref:Microsoft.Maui.Controls.FlyoutItem> objects in the flyout, and any `MenuItem` objects declared after <xref:Microsoft.Maui.Controls.FlyoutItem> objects will appear after the <xref:Microsoft.Maui.Controls.FlyoutItem> objects in the flyout.
|
||||
Menu items can be optionally added to the flyout, and each menu item is represented by a <xref:Microsoft.Maui.Controls.MenuItem> object. The position of <xref:Microsoft.Maui.Controls.MenuItem> objects on the flyout is dependent upon their declaration order in the Shell visual hierarchy. Therefore, any <xref:Microsoft.Maui.Controls.MenuItem> objects declared before <xref:Microsoft.Maui.Controls.FlyoutItem> objects will appear before the <xref:Microsoft.Maui.Controls.FlyoutItem> objects in the flyout, and any <xref:Microsoft.Maui.Controls.MenuItem> objects declared after <xref:Microsoft.Maui.Controls.FlyoutItem> objects will appear after the <xref:Microsoft.Maui.Controls.FlyoutItem> objects in the flyout.
|
||||
|
||||
The `MenuItem` class has a `Clicked` event, and a `Command` property. Therefore, `MenuItem` objects enable scenarios that execute an action in response to the `MenuItem` being tapped.
|
||||
The <xref:Microsoft.Maui.Controls.MenuItem> class has a `Clicked` event, and a `Command` property. Therefore, <xref:Microsoft.Maui.Controls.MenuItem> objects enable scenarios that execute an action in response to the <xref:Microsoft.Maui.Controls.MenuItem> being tapped.
|
||||
|
||||
`MenuItem` objects can be added to the flyout as shown in the following example:
|
||||
<xref:Microsoft.Maui.Controls.MenuItem> objects can be added to the flyout as shown in the following example:
|
||||
|
||||
```xaml
|
||||
<Shell ...>
|
||||
|
|
@ -322,18 +322,18 @@ The `MenuItem` class has a `Clicked` event, and a `Command` property. Therefore,
|
|||
</Shell>
|
||||
```
|
||||
|
||||
This example adds a `MenuItem` object to the flyout, beneath all the flyout items:
|
||||
This example adds a <xref:Microsoft.Maui.Controls.MenuItem> object to the flyout, beneath all the flyout items:
|
||||
|
||||
:::image type="content" source="media/flyout/flyout.png" alt-text="Screenshot of flyout containing a MenuItem object.":::
|
||||
|
||||
The `MenuItem` object executes an `ICommand` named `HelpCommand`, which opens the URL specified by the `CommandParameter` property in the system web browser.
|
||||
The <xref:Microsoft.Maui.Controls.MenuItem> object executes an `ICommand` named `HelpCommand`, which opens the URL specified by the `CommandParameter` property in the system web browser.
|
||||
|
||||
> [!NOTE]
|
||||
> The `BindingContext` of each `MenuItem` is inherited from the subclassed <xref:Microsoft.Maui.Controls.Shell> object.
|
||||
> The `BindingContext` of each <xref:Microsoft.Maui.Controls.MenuItem> is inherited from the subclassed <xref:Microsoft.Maui.Controls.Shell> object.
|
||||
|
||||
### Define MenuItem appearance
|
||||
|
||||
The appearance of each `MenuItem` can be customized by setting the `Shell.MenuItemTemplate` attached property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
The appearance of each <xref:Microsoft.Maui.Controls.MenuItem> can be customized by setting the `Shell.MenuItemTemplate` attached property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<Shell ...>
|
||||
|
|
@ -358,20 +358,20 @@ The appearance of each `MenuItem` can be customized by setting the `Shell.MenuIt
|
|||
</Shell>
|
||||
```
|
||||
|
||||
This example attaches the <xref:Microsoft.Maui.Controls.DataTemplate> to each `MenuItem` object, displaying the title of the `MenuItem` object in italics:
|
||||
This example attaches the <xref:Microsoft.Maui.Controls.DataTemplate> to each <xref:Microsoft.Maui.Controls.MenuItem> object, displaying the title of the <xref:Microsoft.Maui.Controls.MenuItem> object in italics:
|
||||
|
||||
:::image type="content" source="media/flyout/menuitem-templated.png" alt-text="Screenshot of templated MenuItem objects.":::
|
||||
|
||||
Because `Shell.MenuItemTemplate` is an attached property, different templates can be attached to specific `MenuItem` objects.
|
||||
Because `Shell.MenuItemTemplate` is an attached property, different templates can be attached to specific <xref:Microsoft.Maui.Controls.MenuItem> objects.
|
||||
|
||||
> [!NOTE]
|
||||
> Shell provides the `Text` and `IconImageSource` properties to the `BindingContext` of the `MenuItemTemplate`. You can also use `Title` in place of `Text` and `Icon` in place of `IconImageSource` which will let you reuse the same template for menu items and flyout items.
|
||||
|
||||
The default template for <xref:Microsoft.Maui.Controls.FlyoutItem> objects can also be used for `MenuItem` objects. For more information, see [Default template for FlyoutItems](#default-template-for-flyoutitems).
|
||||
The default template for <xref:Microsoft.Maui.Controls.FlyoutItem> objects can also be used for <xref:Microsoft.Maui.Controls.MenuItem> objects. For more information, see [Default template for FlyoutItems](#default-template-for-flyoutitems).
|
||||
|
||||
## Style FlyoutItem and MenuItem objects
|
||||
|
||||
Shell includes three style classes, which are automatically applied to <xref:Microsoft.Maui.Controls.FlyoutItem> and `MenuItem` objects. The style class names are `FlyoutItemLabelStyle`, `FlyoutItemImageStyle`, and `FlyoutItemLayoutStyle`.
|
||||
Shell includes three style classes, which are automatically applied to <xref:Microsoft.Maui.Controls.FlyoutItem> and <xref:Microsoft.Maui.Controls.MenuItem> objects. The style class names are `FlyoutItemLabelStyle`, `FlyoutItemImageStyle`, and `FlyoutItemLayoutStyle`.
|
||||
|
||||
The following XAML shows an example of defining styles for these style classes:
|
||||
|
||||
|
|
@ -398,9 +398,9 @@ The following XAML shows an example of defining styles for these style classes:
|
|||
</Style>
|
||||
```
|
||||
|
||||
These styles will automatically be applied to <xref:Microsoft.Maui.Controls.FlyoutItem> and `MenuItem` objects, without having to set their `StyleClass` properties to the style class names.
|
||||
These styles will automatically be applied to <xref:Microsoft.Maui.Controls.FlyoutItem> and <xref:Microsoft.Maui.Controls.MenuItem> objects, without having to set their `StyleClass` properties to the style class names.
|
||||
|
||||
In addition, custom style classes can be defined and applied to <xref:Microsoft.Maui.Controls.FlyoutItem> and `MenuItem` objects. For more information about style classes, see [Style classes](~/user-interface/styles/xaml.md#style-classes).
|
||||
In addition, custom style classes can be defined and applied to <xref:Microsoft.Maui.Controls.FlyoutItem> and <xref:Microsoft.Maui.Controls.MenuItem> objects. For more information about style classes, see [Style classes](~/user-interface/styles/xaml.md#style-classes).
|
||||
|
||||
## Flyout header
|
||||
|
||||
|
|
@ -758,7 +758,7 @@ The following example shows hiding an item in the flyout:
|
|||
```
|
||||
|
||||
> [!NOTE]
|
||||
> There's also a `Shell.FlyoutItemIsVisible` attached property, which can be set on <xref:Microsoft.Maui.Controls.FlyoutItem>, `MenuItem`, <xref:Microsoft.Maui.Controls.Tab>, and <xref:Microsoft.Maui.Controls.ShellContent> objects.
|
||||
> There's also a `Shell.FlyoutItemIsVisible` attached property, which can be set on <xref:Microsoft.Maui.Controls.FlyoutItem>, <xref:Microsoft.Maui.Controls.MenuItem>, <xref:Microsoft.Maui.Controls.Tab>, and <xref:Microsoft.Maui.Controls.ShellContent> objects.
|
||||
|
||||
## Open and close the flyout programmatically
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ A context menu is defined with a `MenuFlyout`, which can consist of the followin
|
|||
- `MenuFlyoutSubItem`, which represents a sub-menu item that can be clicked.
|
||||
- `MenuFlyoutSeparator`, which is a horizontal line that separates items in the menu.
|
||||
|
||||
`MenuFlyoutSubItem` derives from `MenuFlyoutItem`, which in turn derives from `MenuItem`. `MenuItem` defines multiple properties that enable the appearance and behavior of a menu item to be specified. The appearance of a menu item, or sub-item, can be defined by setting the `Text`, and `IconImageSource` properties. The response to a menu item, or sub-item, click can be defined by setting the `Clicked`, `Command`, and `CommandParameter` properties. <!-- For more information about menu items, see [Menu items](). -->
|
||||
`MenuFlyoutSubItem` derives from `MenuFlyoutItem`, which in turn derives from <xref:Microsoft.Maui.Controls.MenuItem>. <xref:Microsoft.Maui.Controls.MenuItem> defines multiple properties that enable the appearance and behavior of a menu item to be specified. The appearance of a menu item, or sub-item, can be defined by setting the `Text`, and `IconImageSource` properties. The response to a menu item, or sub-item, click can be defined by setting the `Clicked`, `Command`, and `CommandParameter` properties. For more information about menu items, see [Display menu items](menuitem.md).
|
||||
|
||||
> [!WARNING]
|
||||
> A context menu on an <xref:Microsoft.Maui.Controls.Entry> is currently unsupported on Mac Catalyst.
|
||||
|
|
@ -119,7 +119,7 @@ void OnLabelClicked(object sender, EventArgs e)
|
|||
|
||||
## Display icons on menu items
|
||||
|
||||
`MenuFlyoutItem` and `MenuFlyoutSubItem` inherit the `IconImageSource` property from `MenuItem`, which enables a small icon to be displayed next to the text for a context menu item. This icon can either be an image, or a font icon.
|
||||
`MenuFlyoutItem` and `MenuFlyoutSubItem` inherit the `IconImageSource` property from <xref:Microsoft.Maui.Controls.MenuItem>, which enables a small icon to be displayed next to the text for a context menu item. This icon can either be an image, or a font icon.
|
||||
|
||||
> [!WARNING]
|
||||
> Mac Catalyst does not support displaying icons on context menu items.
|
||||
|
|
|
|||
|
|
@ -947,7 +947,7 @@ listView.ScrollTo(monkey, position: ScrollToPosition.End, animate: true);
|
|||
|
||||
## Add context menus
|
||||
|
||||
<xref:Microsoft.Maui.Controls.ListView> supports context menus items, which are defined as `MenuItem` objects that are added to the `ViewCell.ContextActions` collection in the <xref:Microsoft.Maui.Controls.DataTemplate> for each item:
|
||||
<xref:Microsoft.Maui.Controls.ListView> supports context menus items, which are defined as <xref:Microsoft.Maui.Controls.MenuItem> objects that are added to the `ViewCell.ContextActions` collection in the <xref:Microsoft.Maui.Controls.DataTemplate> for each item:
|
||||
|
||||
```xaml
|
||||
<ListView x:Name="listView"
|
||||
|
|
@ -971,7 +971,7 @@ listView.ScrollTo(monkey, position: ScrollToPosition.End, animate: true);
|
|||
</ListView>
|
||||
```
|
||||
|
||||
The `MenuItem` objects are revealed when an item in the <xref:Microsoft.Maui.Controls.ListView> is right-clicked:
|
||||
The <xref:Microsoft.Maui.Controls.MenuItem> objects are revealed when an item in the <xref:Microsoft.Maui.Controls.ListView> is right-clicked:
|
||||
|
||||
:::image type="content" source="media/listview/contextmenuitems.png" alt-text="Screenshot of CollectionView context menu items.":::
|
||||
|
||||
|
|
|
|||
|
|
@ -136,13 +136,13 @@ The `LeftItems`, `RightItems`, `TopItems`, and `BottomItems` collections are all
|
|||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
||||
Each swipe item is defined as a `SwipeItem` object that's placed into one of the four `SwipeItems` directional collections. The `SwipeItem` class derives from the `MenuItem` class, and adds the following members:
|
||||
Each swipe item is defined as a `SwipeItem` object that's placed into one of the four `SwipeItems` directional collections. The `SwipeItem` class derives from the <xref:Microsoft.Maui.Controls.MenuItem> class, and adds the following members:
|
||||
|
||||
- A `BackgroundColor` property, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the background color of the swipe item. This property is backed by a bindable property.
|
||||
- An `Invoked` event, which is raised when the swipe item is executed.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `MenuItem` class defines several properties, including `Command`, `CommandParameter`, `IconImageSource`, and `Text`. These properties can be set on a `SwipeItem` object to define its appearance, and to define an `ICommand` that executes when the swipe item is invoked. <!--For more information, see [MenuItem](~/user-interface/menuitem.md).-->
|
||||
> The <xref:Microsoft.Maui.Controls.MenuItem> class defines several properties, including `Command`, `CommandParameter`, `IconImageSource`, and `Text`. These properties can be set on a `SwipeItem` object to define its appearance, and to define an `ICommand` that executes when the swipe item is invoked. For more information, see [Display menu items](~/user-interface/menuitem.md).
|
||||
|
||||
The following example shows two `SwipeItem` objects in the `LeftItems` collection of a <xref:Microsoft.Maui.Controls.SwipeView>:
|
||||
|
||||
|
|
|
|||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 9.9 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 9.9 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 7.1 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 12 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 12 KiB |
|
|
@ -21,7 +21,7 @@ A `MenuBarItem` can consist of the following children:
|
|||
- `MenuFlyoutSubItem`, which represents a sub-menu item that can be clicked.
|
||||
- `MenuFlyoutSeparator`, which is a horizontal line that separates items in the menu.
|
||||
|
||||
`MenuFlyoutSubItem` derives from `MenuFlyoutItem`, which in turn derives from `MenuItem`. `MenuItem` defines multiple properties that enable the appearance and behavior of a menu item to be specified. The appearance of a menu item, or sub-item, can be defined by setting the `Text`, and `IconImageSource` properties. The response to a menu item, or sub-item, click can be defined by setting the `Clicked`, `Command`, and `CommandParameter` properties. <!-- For more information about menu items, see [Menu items](). -->
|
||||
`MenuFlyoutSubItem` derives from `MenuFlyoutItem`, which in turn derives from <xref:Microsoft.Maui.Controls.MenuItem>. <xref:Microsoft.Maui.Controls.MenuItem> defines multiple properties that enable the appearance and behavior of a menu item to be specified. The appearance of a menu item, or sub-item, can be defined by setting the `Text`, and `IconImageSource` properties. The response to a menu item, or sub-item, click can be defined by setting the `Clicked`, `Command`, and `CommandParameter` properties. For more information about menu items, see [Display menu items](menuitem.md).
|
||||
|
||||
## Create menu bar items
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ In this example, each `MenuFlyoutItem` defines a menu item that executes an `ICo
|
|||
|
||||
## Display icons on menu items
|
||||
|
||||
`MenuFlyoutItem` and `MenuFlyoutSubItem` inherit the `IconImageSource` property from `MenuItem`, which enables a small icon to be displayed next to the text for a menu item. This icon can either be an image, or a font icon.
|
||||
`MenuFlyoutItem` and `MenuFlyoutSubItem` inherit the `IconImageSource` property from <xref:Microsoft.Maui.Controls.MenuItem>, which enables a small icon to be displayed next to the text for a menu item. This icon can either be an image, or a font icon.
|
||||
|
||||
> [!WARNING]
|
||||
> Mac Catalyst does not support displaying icons on menu items.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,133 @@
|
|||
---
|
||||
title: "Display menu items"
|
||||
description: "Learn how to create menu items for menus such as ListView item context menus and Shell app flyout menus."
|
||||
ms.date: 08/02/2023
|
||||
---
|
||||
|
||||
# Display menu items
|
||||
|
||||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.MenuItem> class can be used to define menu items for menus such as <xref:Microsoft.Maui.Controls.ListView> item context menus and Shell app flyout menus.
|
||||
|
||||
The following screenshots show <xref:Microsoft.Maui.Controls.MenuItem> objects in a <xref:Microsoft.Maui.Controls.ListView> context menu on Android:
|
||||
|
||||
:::image type="content" source="media/menuitem/text-context-menu-android.png" alt-text="Screenshot of menu items in a ListView context menu on Android.":::
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.MenuItem> class defines the following properties:
|
||||
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.Command>, of type `ICommand`, allows binding user actions, such as finger taps or clicks, to commands defined on a viewmodel.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.CommandParameter>, of type `object`, specifies the parameter that should be passed to the `Command`.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.IconImageSource>, of type <xref:Microsoft.Maui.Controls.ImageSource>, defines the menu item icon.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.IsDestructive>, of type `bool`, indicates whether the <xref:Microsoft.Maui.Controls.MenuItem> removes its associated UI element from the list.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.IsEnabled>, of type `bool`, indicates whether the menu item responds to user input.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.Text>, of type `string`, specifies the menu item text.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings.
|
||||
|
||||
## Create a MenuItem
|
||||
|
||||
To create a menu item, for example as a context menu on a <xref:Microsoft.Maui.Controls.ListView> object's items, create a <xref:Microsoft.Maui.Controls.MenuItem> object within a <xref:Microsoft.Maui.Controls.ViewCell> object that's used as the <xref:Microsoft.Maui.Controls.DataTemplate> object for the <xref:Microsoft.Maui.Controls.ListView>s `ItemTemplate`. When the <xref:Microsoft.Maui.Controls.ListView> object is populated it will create each item using the <xref:Microsoft.Maui.Controls.DataTemplate>, exposing the <xref:Microsoft.Maui.Controls.MenuItem> choices when the context menu is activated for an item.
|
||||
|
||||
The following example shows how to create a <xref:Microsoft.Maui.Controls.MenuItem> within the context of a <xref:Microsoft.Maui.Controls.ListView> object:
|
||||
|
||||
```xaml
|
||||
<ListView>
|
||||
<ListView.ItemTemplate>
|
||||
<DataTemplate>
|
||||
<ViewCell>
|
||||
<ViewCell.ContextActions>
|
||||
<MenuItem Text="Context menu option" />
|
||||
</ViewCell.ContextActions>
|
||||
<Label Text="{Binding .}" />
|
||||
</ViewCell>
|
||||
</DataTemplate>
|
||||
</ListView.ItemTemplate>
|
||||
</ListView>
|
||||
```
|
||||
|
||||
This example will result in a <xref:Microsoft.Maui.Controls.MenuItem> object that has text. However, the appearance of a <xref:Microsoft.Maui.Controls.MenuItem> varies across platforms.
|
||||
|
||||
A <xref:Microsoft.Maui.Controls.MenuItem> can also be created in code:
|
||||
|
||||
```csharp
|
||||
// Return a ViewCell instance that is used as the template for each list item
|
||||
DataTemplate dataTemplate = new DataTemplate(() =>
|
||||
{
|
||||
// A Label displays the list item text
|
||||
Label label = new Label();
|
||||
label.SetBinding(Label.TextProperty, ".");
|
||||
|
||||
// A ViewCell serves as the DataTemplate
|
||||
ViewCell viewCell = new ViewCell
|
||||
{
|
||||
View = label
|
||||
};
|
||||
|
||||
// Add a MenuItem to the ContextActions
|
||||
MenuItem menuItem = new MenuItem
|
||||
{
|
||||
Text = "Context Menu Option"
|
||||
};
|
||||
viewCell.ContextActions.Add(menuItem);
|
||||
|
||||
// Return the custom ViewCell to the DataTemplate constructor
|
||||
return viewCell;
|
||||
});
|
||||
|
||||
ListView listView = new ListView
|
||||
{
|
||||
...
|
||||
ItemTemplate = dataTemplate
|
||||
};
|
||||
```
|
||||
|
||||
A context menu in a <xref:Microsoft.Maui.Controls.ListView> is activated and displayed differently on each platform. On Android, the context menu is activated by long-press on a list item. The context menu replaces the title and navigation bar area and <xref:Microsoft.Maui.Controls.MenuItem> options are displayed as horizontal buttons. On iOS, the context menu is activated by swiping on a list item. The context menu is displayed on the list item and `MenuItems` are displayed as horizontal buttons. On Windows, the context menu is activated by right-clicking on a list item. The context menu is displayed near the cursor as a vertical list.
|
||||
|
||||
<!-- No MenuItems in this scenario on Mac Catalyst -->
|
||||
|
||||
## Define MenuItem behavior
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.MenuItem> class defines a <xref:Microsoft.Maui.Controls.MenuItem.Clicked> event. An event handler can be attached to this event to react to taps or clicks on <xref:Microsoft.Maui.Controls.MenuItem> objects:
|
||||
|
||||
```xaml
|
||||
<MenuItem ...
|
||||
Clicked="OnItemClicked" />
|
||||
```
|
||||
|
||||
An event handler can also be attached in code:
|
||||
|
||||
```csharp
|
||||
MenuItem item = new MenuItem { ... };
|
||||
item.Clicked += OnItemClicked;
|
||||
```
|
||||
|
||||
These examples reference an `OnItemClicked` event handler, which is shown in the following example:
|
||||
|
||||
```csharp
|
||||
void OnItemClicked(object sender, EventArgs e)
|
||||
{
|
||||
MenuItem menuItem = sender as MenuItem;
|
||||
|
||||
// Access the list item through the BindingContext
|
||||
var contextItem = menuItem.BindingContext;
|
||||
|
||||
// Do something with the contextItem here
|
||||
}
|
||||
```
|
||||
|
||||
## Define MenuItem appearance
|
||||
|
||||
Icons are specified using the <xref:Microsoft.Maui.Controls.MenuItem.IconImageSource> property. If an icon is specified, the text specified by the <xref:Microsoft.Maui.Controls.MenuItem.Text> property won't be displayed. The following screenshot shows a <xref:Microsoft.Maui.Controls.MenuItem> with an icon on Android:
|
||||
|
||||
:::image type="content" source="media/menuitem/icon-context-menu-android.png" alt-text="Screenshot of menu items, with an icon, in a ListView context menu on Android.":::
|
||||
|
||||
<xref:Microsoft.Maui.Controls.MenuItem> objects only display icons on Android. On other platforms, only the text specified by the <xref:Microsoft.Maui.Controls.MenuItem.Text> property will be displayed.
|
||||
|
||||
> [!NOTE]
|
||||
> Images can be stored in a single location in your app project. For more information, see [Add images to a .NET MAUI project](~/user-interface/images/images.md).
|
||||
|
||||
## Enable or disable a MenuItem at runtime
|
||||
|
||||
To enable or disable a <xref:Microsoft.Maui.Controls.MenuItem> at runtime, bind its `Command` property to an `ICommand` implementation, and ensure that a `canExecute` delegate enables and disables the `ICommand` as appropriate.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Don't bind the `IsEnabled` property to another property when using the `Command` property to enable or disable the <xref:Microsoft.Maui.Controls.MenuItem>.
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
title: "Display toolbar items"
|
||||
description: "Learn how to add toolbar items, which are a special type of button, to the app's navigation bar."
|
||||
ms.date: 08/01/2023
|
||||
---
|
||||
|
||||
# Display toolbar items
|
||||
|
||||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.ToolbarItem> class is a special type of button that can be added to a <xref:Microsoft.Maui.Controls.Page> object's <xref:Microsoft.Maui.Controls.Page.ToolbarItems> collection. Because the <xref:Microsoft.Maui.Controls.Shell> class derives from <xref:Microsoft.Maui.Controls.Page>, <xref:Microsoft.Maui.Controls.ToolbarItem> objects can also be added to the `ToolbarItems` collection of a <xref:Microsoft.Maui.Controls.Shell> object. Each <xref:Microsoft.Maui.Controls.ToolbarItem> object will appear as a button in the app's navigation bar. A <xref:Microsoft.Maui.Controls.ToolbarItem> object can have an icon and appear as a primary or secondary item. The <xref:Microsoft.Maui.Controls.ToolbarItem> class inherits from <xref:Microsoft.Maui.Controls.MenuItem>.
|
||||
|
||||
The following screenshot shows a <xref:Microsoft.Maui.Controls.ToolbarItem> object in the navigation bar on iOS:
|
||||
|
||||
:::image type="content" source="media/toolbaritem/ios.png" alt-text="Screenshot of a toolbar item in the navigation bar on iOS.":::
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.ToolbarItem> class defines the following properties:
|
||||
|
||||
- <xref:Microsoft.Maui.Controls.ToolbarItem.Order>, of type <xref:Microsoft.Maui.Controls.ToolbarItemOrder>, determines whether the <xref:Microsoft.Maui.Controls.ToolbarItem> object displays in the primary or secondary menu.
|
||||
- <xref:Microsoft.Maui.Controls.ToolbarItem.Priority>, of type `int`, determines the display order of items in a <xref:Microsoft.Maui.Controls.Page.ToolbarItems> collection.
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.ToolbarItem> class inherits the following typically-used properties from the <xref:Microsoft.Maui.Controls.MenuItem> class:
|
||||
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.Command>, of type `ICommand`, allows binding user actions, such as finger taps or clicks, to commands defined on a viewmodel.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.CommandParameter>, of type `object`, specifies the parameter that should be passed to the `Command`.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.IconImageSource>, of type <xref:Microsoft.Maui.Controls.ImageSource>, that determines the display icon on a <xref:Microsoft.Maui.Controls.ToolbarItem> object.
|
||||
- <xref:Microsoft.Maui.Controls.MenuItem.Text>, of type `string`, determines the display text on a <xref:Microsoft.Maui.Controls.ToolbarItem> object.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings.
|
||||
|
||||
> [!NOTE]
|
||||
> An alternative to creating a toolbar from <xref:Microsoft.Maui.Controls.ToolbarItem> objects is to set the <xref:Microsoft.Maui.Controls.NavigationPage.TitleViewProperty> attached property to a layout class that contains multiple views. For more information, see [Display views in the navigation bar](~/user-interface/pages/navigationpage.md#display-views-in-the-navigation-bar).
|
||||
|
||||
## Create a ToolbarItem
|
||||
|
||||
To create a toolbar item, create a <xref:Microsoft.Maui.Controls.ToolbarItem> object and set its properties to define its appearance and behavior. The following example shows how to create a <xref:Microsoft.Maui.Controls.ToolbarItem> with minimal properties set, and add it to a <xref:Microsoft.Maui.Controls.ContentPage>'s <xref:Microsoft.Maui.Controls.Page.ToolbarItems> collection:
|
||||
|
||||
```xaml
|
||||
<ContentPage.ToolbarItems>
|
||||
<ToolbarItem Text="Add item"
|
||||
IconImageSource="add.png" />
|
||||
</ContentPage.ToolbarItems>
|
||||
```
|
||||
|
||||
This example will result in a <xref:Microsoft.Maui.Controls.ToolbarItem> object that has text and an icon. However, the appearance of a <xref:Microsoft.Maui.Controls.ToolbarItem> varies across platforms.
|
||||
|
||||
A <xref:Microsoft.Maui.Controls.ToolbarItem> can also be created in code and added to the <xref:Microsoft.Maui.Controls.Page.ToolbarItems> collection:
|
||||
|
||||
```csharp
|
||||
ToolbarItem item = new ToolbarItem
|
||||
{
|
||||
Text = "Add item",
|
||||
IconImageSource = ImageSource.FromFile("add.png")
|
||||
};
|
||||
|
||||
// "this" refers to a Page object
|
||||
this.ToolbarItems.Add(item);
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Images can be stored in a single location in your app project. For more information, see [Add images to a .NET MAUI project](~/user-interface/images/images.md).
|
||||
|
||||
## Define button behavior
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.ToolbarItem> class inherits the <xref:Microsoft.Maui.Controls.MenuItem.Clicked> event from the <xref:Microsoft.Maui.Controls.MenuItem> class. An event handler can be attached to the <xref:Microsoft.Maui.Controls.MenuItem.Clicked> event to react to taps or clicks on <xref:Microsoft.Maui.Controls.ToolbarItem> objects:
|
||||
|
||||
```xaml
|
||||
<ToolbarItem ...
|
||||
Clicked="OnItemClicked" />
|
||||
```
|
||||
|
||||
An event handler can also be attached in code:
|
||||
|
||||
```csharp
|
||||
ToolbarItem item = new ToolbarItem { ... };
|
||||
item.Clicked += OnItemClicked;
|
||||
```
|
||||
|
||||
These examples reference an `OnItemClicked` event handler, which is shown in the following example:
|
||||
|
||||
```csharp
|
||||
void OnItemClicked(object sender, EventArgs e)
|
||||
{
|
||||
ToolbarItem item = (ToolbarItem)sender;
|
||||
messageLabel.Text = $"You clicked the \"{item.Text}\" toolbar item.";
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> <xref:Microsoft.Maui.Controls.ToolbarItem> objects can also use the <xref:Microsoft.Maui.Controls.MenuItem.Command> and <xref:Microsoft.Maui.Controls.MenuItem.CommandParameter> properties to react to user input without event handlers. <!--For more information about the `ICommand` interface and MVVM data-binding, see [Xamarin.Forms MenuItem MVVM Behavior](~/xamarin-forms/user-interface/menuitem.md#define-menuitem-behavior-with-mvvm).-->
|
||||
|
||||
## Enable or disable a ToolbarItem at runtime
|
||||
|
||||
To enable or disable a <xref:Microsoft.Maui.Controls.ToolbarItem> at runtime, bind its <xref:Microsoft.Maui.Controls.MenuItem.Command> property to an `ICommand` implementation, and ensure that its `canExecute` delegate enables and disables the `ICommand` as appropriate.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Don't bind the `IsEnabled` property to another property when using the `Command` property to enable or disable the <xref:Microsoft.Maui.Controls.ToolbarItem>.
|
||||
|
||||
## Primary and secondary toolbar items
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.ToolbarItemOrder> enum has `Default`, `Primary`, and `Secondary` values.
|
||||
|
||||
When the <xref:Microsoft.Maui.Controls.ToolbarItem.Order> property is set to `Primary`, the <xref:Microsoft.Maui.Controls.ToolbarItem> object will appear in the navigation bar on all platforms. <xref:Microsoft.Maui.Controls.ToolbarItem> objects are prioritized over the page title, which will be truncated to make room for the items.
|
||||
|
||||
When the <xref:Microsoft.Maui.Controls.ToolbarItem.Order> property is set to `Secondary`, behavior varies across platforms. On iOS and Mac Catalyst, `Secondary` toolbar items will appear as a horizontal list. On Android and Windows, the `Secondary` items menu appears as three dots that can be tapped:
|
||||
|
||||
:::image type="content" source="media/toolbaritem/android-dots.png" alt-text="Screenshot of secondary toolbar ellipsis on Android.":::
|
||||
|
||||
Tapping the three dots reveals items in a vertical list:
|
||||
|
||||
:::image type="content" source="media/toolbaritem/android-secondaries.png" alt-text="Screenshot of secondary toolbar items in vertical list on Android.":::
|
||||
|
||||
> [!WARNING]
|
||||
> Icon behavior in <xref:Microsoft.Maui.Controls.ToolbarItem> objects that have their <xref:Microsoft.Maui.Controls.ToolbarItem.Order> property set to `Secondary` is inconsistent across platforms. Avoid setting the <xref:Microsoft.Maui.Controls.MenuItem.IconImageSource> property on items that appear in the secondary menu.
|
||||
Загрузка…
Ссылка в новой задаче