Xamarin.FormsToolBarItem ToolbarItem

Beispiel herunterladen Das Beispiel herunterladenDownload Sample Download the sample

Die Xamarin.Forms ToolbarItem -Klasse ist ein spezieller Typ von Schaltfläche, der der Auflistung eines-Objekts hinzugefügt werden kann Page ToolbarItems .The Xamarin.Forms ToolbarItem class is a special type of button that can be added to a Page object's ToolbarItems collection. Jedes ToolbarItem Objekt wird in der Navigationsleiste der Anwendung als Schaltfläche angezeigt.Each ToolbarItem object will appear as a button in the application's navigation bar. Eine ToolbarItem -Instanz kann ein Symbol aufweisen und als primäres oder sekundäres Menü Element angezeigt werden.A ToolbarItem instance can have an icon and appear as a primary or secondary menu item. Die ToolbarItem Klasse erbt von MenuItem .The ToolbarItem class inherits from MenuItem.

Die folgenden Screenshots zeigen ToolbarItem Objekte in der Navigationsleiste unter IOS und Android:The following screenshots show ToolbarItem objects in the navigation bar on iOS and Android:

"Bildschirm Abbildung der ToolBarItem-Demo unter Android und IOS""ToolbarItem demo screenshot on Android and iOS"

Die- ToolbarItem Klasse definiert die folgenden Eigenschaften:The ToolbarItem class defines the following properties:

  • Orderein ToolbarItemOrder Enumerationswert, der bestimmt, ob die- ToolbarItem Instanz im primären oder sekundären Menü angezeigt wird.Order is a ToolbarItemOrder enum value that determines whether the ToolbarItem instance displays in the primary or secondary menu.
  • Priorityein- integer Wert, der die Anzeigereihenfolge von Elementen in der Auflistung eines Page -Objekts bestimmt ToolbarItems .Priority is an integer value that determines the display order of items in a Page object's ToolbarItems collection.

Die ToolbarItem -Klasse erbt die folgenden normalerweise verwendeten Eigenschaften von der- MenuItem Klasse:The ToolbarItem class inherits the following typically-used properties from the MenuItem class:

  • Commandist eine ICommand , die das Binden von Benutzeraktionen (z. b. Finger Tippen oder Klicks) auf Befehle ermöglicht, die für ein ViewModel definiert sind.Command is an ICommand that allows binding user actions, such as finger taps or clicks, to commands defined on a viewmodel.
  • CommandParameterist eine object , die den Parameter angibt, der an den übergeben werden soll Command .CommandParameter is an object that specifies the parameter that should be passed to the Command.
  • IconImageSourceein- ImageSource Wert, der das Anzeige Symbol für ein- ToolbarItem Objekt bestimmt.IconImageSource is an ImageSource value that determines the display icon on a ToolbarItem object.
  • Textist ein string , der den Anzeige Text für ein- ToolbarItem Objekt bestimmt.Text is a string that determines the display text on a ToolbarItem object.

Diese Eigenschaften werden durch- BindableProperty Objekte gestützt, sodass eine- ToolbarItem Instanz das Ziel von Daten Bindungen sein kann.These properties are backed by BindableProperty objects so a ToolbarItem instance can be the target of data bindings.

Hinweis

Eine Alternative zum Erstellen einer Symbolleiste aus ToolbarItem Objekten besteht darin, die NavigationPage.TitleView angefügte-Eigenschaft auf eine Layoutklasse festzulegen, die mehrere Ansichten enthält.An alternative to creating a toolbar from ToolbarItem objects is to set the NavigationPage.TitleView attached property to a layout class that contains multiple views. Weitere Informationen finden Sie unter Anzeigen von Ansichten in der Navigationsleiste.For more information, see Displaying Views in the Navigation Bar.

Erstellen eines ToolBarItemCreate a ToolbarItem

Ein- ToolbarItem Objekt kann in XAML instanziiert werden.A ToolbarItem object can be instantiated in XAML. Die Text IconImageSource Eigenschaften und können festgelegt werden, um zu bestimmen, wie die Schaltfläche auf der Navigationsleiste angezeigt wird.The Text and IconImageSource properties can be set to determine how the button is displayed in the navigation bar. Im folgenden Beispiel wird gezeigt, wie ein ToolbarItem mit einigen allgemeinen Eigenschaften instanziiert und der Auflistung hinzugefügt wird ContentPage ToolbarItems :The following example shows how to instantiate a ToolbarItem with some common properties set, and add it to a ContentPage's ToolbarItems collection:

<ContentPage.ToolbarItems>
    <ToolbarItem Text="Example Item"
                 IconImageSource="example_icon.png"
                 Order="Primary"
                 Priority="0" />
</ContentPage.ToolbarItems>

In diesem Beispiel wird ein ToolbarItem -Objekt mit Text angezeigt, ein Symbol, das im Bereich der primären Navigationsleiste zuerst angezeigt wird.This example will result in a ToolbarItem object that has text, an icon and appears first in the primary navigation bar area. Ein ToolbarItem kann auch im Code erstellt und der Auflistung hinzugefügt werden ToolbarItems :A ToolbarItem can also be created in code and added to the ToolbarItems collection:

ToolbarItem item = new ToolbarItem
{
    Text = "Example Item",
    IconImageSource = ImageSource.FromFile("example_icon.png"),
    Order = ToolbarItemOrder.Primary,
    Priority = 0
};

// "this" refers to a Page object
this.ToolbarItems.Add(item);

Die durch das dargestellte Datei string , die als-Eigenschaft bereitgestellt IconImageSource wird, muss in jedem Platt Form Projekt vorhanden sein.The file represented by the string, provided as the IconImageSource property, must exist in each platform project.

Hinweis

Bild Ressourcen werden auf jeder Plattform unterschiedlich behandelt.Image assets are handled differently on each platform. Ein ImageSource kann aus Quellen stammen, einschließlich einer lokalen Datei oder eingebetteten Ressource, eines URIs oder eines Streams.An ImageSource can come from sources including a local file or embedded resource, a URI, or a stream. Weitere Informationen zum Festlegen der IconImageSource -Eigenschaft und der Bilder in finden Sie unter Xamarin.Forms Bilder in Xamarin.Forms .For more information about setting the IconImageSource property and Images in Xamarin.Forms, see Images in Xamarin.Forms.

Definieren des Schaltflächen VerhaltensDefine button behavior

Die- ToolbarItem Klasse erbt das- Clicked Ereignis von der- MenuItem Klasse.The ToolbarItem class inherits the Clicked event from the MenuItem class. Ein Ereignishandler kann an das-Ereignis angefügt werden, um auf- Clicked ToolbarItem Instanzen in XAML auf tippen oder Klicks zu reagieren:An event handler can be attached to the Clicked event to react to taps or clicks on ToolbarItem instances in XAML:

<ToolbarItem ...
             Clicked="OnItemClicked" />

Ein Ereignishandler kann auch im Code angefügt werden:An event handler can also be attached in code:

ToolbarItem item = new ToolbarItem { ... }
item.Clicked += OnItemClicked;

In den vorherigen Beispielen wurde auf einen OnItemClicked Ereignishandler verwiesen.Previous examples referenced an OnItemClicked event handler. Der folgende Code zeigt eine Beispiel Implementierung:The following code shows an example implementation:

void OnItemClicked(object sender, EventArgs e)
{
    ToolbarItem item = (ToolbarItem)sender;
    messageLabel.Text = $"You clicked the \"{item.Text}\" toolbar item.";
}

ToolbarItem-Objekte können auch die Command -Eigenschaft und die-Eigenschaft verwenden CommandParameter , um auf Benutzereingaben ohne Ereignishandler zu reagieren.ToolbarItem objects can also use the Command and CommandParameter properties to react to user input without event handlers. Weitere Informationen zur ICommand -Schnittstelle und zur MVVM-Datenbindung finden Sie unter Xamarin.Forms MenuItem MVVM-Verhalten.For more information about the ICommand interface and MVVM data-binding, see Xamarin.Forms MenuItem MVVM Behavior.

Aktivieren oder Deaktivieren eines ToolBarItem zur LaufzeitEnable or disable a ToolbarItem at runtime

Um das Deaktivieren von zur ToolbarItem Laufzeit zu aktivieren, binden Sie seine- Command Eigenschaft an eine ICommand -Implementierung, und stellen Sie sicher, dass ein Delegat den ggf canExecute . aktiviert und deaktiviert ICommand .To enable of disable a ToolbarItem at runtime, bind its Command property to an ICommand implementation, and ensure that a canExecute delegate enables and disables the ICommand as appropriate.

Weitere Informationen finden Sie unter Aktivieren oder Deaktivieren eines MenuItem zur Laufzeit.For more information, see Enable or disable a MenuItem at runtime.

Primäre und sekundäre MenüsPrimary and secondary menus

Die Enumeration ToolbarItemOrder hat Default die Primary Werte, und Secondary .The ToolbarItemOrder enum has Default, Primary, and Secondary values.

Wenn die- Order Eigenschaft auf festgelegt ist Primary , wird das- ToolbarItem Objekt auf der Hauptnavigationsleiste auf allen Plattformen angezeigt.When the Order property is set to Primary, the ToolbarItem object will appear in the main navigation bar on all platforms. ToolbarItemObjekte werden über den Seitentitel priorisiert, der abgeschnitten wird, um Platz für die Elemente zu schaffen.ToolbarItem objects are prioritized over the page title, which will be truncated to make room for the items. Die folgenden Screenshots zeigen ToolbarItem Objekte im primären Menü unter IOS und Android:The following screenshots show ToolbarItem objects in the primary menu on iOS and Android:

"ToolBarItem-Hauptmenü: Screenshot Android und IOS""ToolbarItem primary menu screenshot Android and iOS"

Wenn die- Order Eigenschaft auf festgelegt ist Secondary , variiert das Verhalten plattformübergreifend.When the Order property is set to Secondary, behavior varies across platforms. Bei UWP und Android wird das Secondary Menü Elemente als drei Punkte angezeigt, auf die Sie tippen oder klicken können, um Elemente in einer vertikalen Liste anzuzeigen.On UWP and Android, the Secondary items menu appears as three dots that can be tapped or clicked to reveal items in a vertical list. Unter IOS wird das Secondary Menü Elemente unterhalb der Navigationsleiste als horizontale Liste angezeigt.On iOS, the Secondary items menu appears below the navigation bar as a horizontal list. Die folgenden Screenshots zeigen ein sekundäres Menü unter IOS und Android:The following screenshots show a secondary menu on iOS and Android:

"ToolBarItem-Menü auf dem sekundären Menü" Android und IOS ""ToolbarItem secondary menu screenshot Android and iOS"

Warnung

Das Symbol Verhalten in ToolbarItem Objekten, deren- Order Eigenschaft auf festgelegt Secondary ist, ist plattformübergreifend nicht konsistent.Icon behavior in ToolbarItem objects that have their Order property set to Secondary is inconsistent across platforms. Legen Sie die- IconImageSource Eigenschaft für Elemente, die im sekundären Menü angezeigt werden, nicht fest.Avoid setting the IconImageSource property on items that appear in the secondary menu.