Xamarin.Forms ToolbarItem

類別 Xamarin.FormsToolbarItem 是特殊類型的按鈕，可以新增至 Page 物件的 ToolbarItems 集合。 每個 ToolbarItem 物件會顯示為應用程式導覽列中的按鈕。 ToolbarItem實例可以有圖示，並顯示為主要或次要功能表項。 類別 ToolbarItem 繼承自 MenuItem。

下列螢幕快照顯示 ToolbarItem iOS 和 Android 上導覽欄位中的物件：

類別 ToolbarItem 會定義下列屬性：

• Order 是列舉 ToolbarItemOrder 值，決定實例是否 ToolbarItem 顯示在主要或次要功能表中。
• Priority是值integer，決定物件ToolbarItems集合中Page項目的顯示順序。

類別 ToolbarItem 會從 MenuItem 類別繼承下列常用的屬性：

• CommandICommand是，允許將用戶動作，例如手指點選或按下，系結至 ViewModel 上定義的命令。
• CommandParameterobject是 ，指定應該傳遞至 的參數Command。
• IconImageSource 是值 ImageSource ，可決定物件上的 ToolbarItem 顯示圖示。
• Textstring是決定 物件上顯示文字的 ToolbarItem 。

這些屬性是由 BindableProperty 物件所支援，因此 ToolbarItem 實例可以是數據系結的目標。

注意

從 ToolbarItem 物件建立工具列的替代方法是將 NavigationPage.TitleView 附加屬性設定為包含多個檢視的版面配置類別。 如需詳細資訊，請參閱 在導覽列中顯示檢視。

建立 ToolbarItem

ToolbarItem物件可以在 XAML 中具現化。 和 TextIconImageSource 屬性可以設定為決定按鈕在導覽列中的顯示方式。 下列範例示範如何具現化 ToolbarItem 具有一些通用屬性集的，並將它新增至 ContentPage的 ToolbarItems 集合：

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

此範例會產生 ToolbarItem 物件，該物件具有文字、圖示，並先出現在主要導覽列區域中。 ToolbarItem也可以在程式代碼中建立 ，並將 新增至ToolbarItems集合：

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);

以屬性提供之 所 string表示的 IconImageSource 檔案必須存在於每個平台專案中。

注意

映射資產在每個平臺上會以不同的方式處理。 ImageSource可以來自來源，包括本機檔案或內嵌資源、URI 或數據流。 如需 在 中Xamarin.Forms設定 IconImageSource 屬性和 Images 的詳細資訊，請參閱 中的Xamarin.Forms影像。

定義按鈕行為

類別 ToolbarItem 會 Clicked 從 MenuItem 類別繼承 事件。 事件處理程式可以附加至 Clicked 事件，以回應 XAML 中的點選或按一下 ToolbarItem 實例：

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

事件處理程式也可以在程式代碼中附加：

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

先前的範例參考 OnItemClicked 事件處理程式。 下列程式代碼顯示範例實作：

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

ToolbarItem 物件也可以使用 Command 和 CommandParameter 屬性來回應使用者輸入，而不需要事件處理程式。 如需介面和MVVM數據系結的詳細資訊 ICommand ，請參閱 Xamarin.Forms MenuItem MVVM 行為。

在運行時間啟用或停用 ToolbarItem

若要在執行時間開啟 停用 ToolbarItem ，請將其 Command 屬性系結至 ICommand 實作，並確定 canExecute 委派會適當地啟用和停用 ICommand 。

如需詳細資訊，請參閱 在運行時間啟用或停用 MenuItem。

主要和次要功能表

列舉 ToolbarItemOrder 具有 Default、 Primary和 Secondary 值。

Order當屬性設定為 Primary時，ToolbarItem物件會出現在所有平臺上的主要導覽列中。 ToolbarItem 物件會優先於頁面標題，這會截斷以騰出空間供專案使用。 下列螢幕快照顯示 ToolbarItem iOS 和 Android 上主要選單中的物件：

Order當 屬性設定為 Secondary時，行為會因平臺而異。 在UWP和Android上，專案 Secondary 功能表會顯示為三個點，可以點選或按兩下以顯示垂直清單中的專案。 在iOS上 Secondary ，專案功能表會顯示在導覽列下方作為水準清單。 下列螢幕快照顯示 iOS 和 Android 上的次要選單：

警告

物件中 ToolbarItem ，其 Order 屬性設定為 Secondary 的圖示行為在平台之間不一致。 避免在 IconImageSource 出現在次要功能表中的項目上設定 屬性。

相關連結

• 中的影像 Xamarin.Forms
• Xamarin.Forms MenuItem