Xamarin.Forms ToolbarItem

下载示例

Xamarin.FormsToolbarItem 类是一种特殊类型的按钮，可添加到 Page 对象的 ToolbarItems 集合中。 每个 ToolbarItem 对象都将显示为应用程序导航栏中的一个按钮。 ToolbarItem 实例可以有一个图标，并显示为主要菜单项或辅助菜单项。 ToolbarItem 类继承自 MenuItem。

以下屏幕截图显示了 iOS 和 Android 上的导航栏中的 ToolbarItem 对象：

ToolbarItem 类定义以下属性：

• Order 是一个 ToolbarItemOrder 枚举值，用于确定 ToolbarItem 实例显示在主菜单还是辅助菜单中。
• Priority 是一个 integer 值，用于确定项在 Page 对象的 ToolbarItems 集合中的显示顺序。

ToolbarItem 类从 MenuItem 类继承了以下常用的属性：

• Command 是一个 ICommand，允许将用户操作（如手指点击或单击）绑定到 viewmodel 上定义的命令。
• CommandParameter 是一个 object，用于指定应传递给 Command 的参数。
• IconImageSource 是一个 ImageSource 值，用于确定 ToolbarItem 对象上的显示图标。
• Text 是一个 string，用于确定 ToolbarItem 对象上的显示文本。

这些属性由 BindableProperty 对象提供支持，因此 ToolbarItem 实例可以是数据绑定的目标。

注意

从 ToolbarItem 对象创建工具栏的替代方法是将 NavigationPage.TitleView 附加属性设置为包含多个视图的布局类。 有关详细信息，请参阅导航栏中的显示视图。

创建 ToolbarItem

可以在 XAML 中实例化 ToolbarItem 对象。 可以设置 Text 和 IconImageSource 属性来确定按钮在导航栏中的显示方式。 以下示例演示如何实例化设置了一些通用属性的 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 属性和图像，请参阅 Xamarin.Forms 中的图像。

定义按钮行为

ToolbarItem 类从 MenuItem 类继承 Clicked 事件。 事件处理程序可以附加到 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 属性来响应用户输入，而无需事件处理程序。 有关 ICommand 接口和 MVVM 数据绑定的详细信息，请参阅 Xamarin.Forms MenuItem MVVM 行为。

在运行时启用或禁用 ToolbarItem

若要在运行时启用或禁用 ToolbarItem，请将其 Command 属性绑定到 ICommand 实现，并确保 canExecute 委托根据需要启用或禁用 ICommand。

有关详细信息，请参阅在运行时启用或禁用 MenuItem。

主菜单和辅助菜单

ToolbarItemOrder 枚举具有 Default、Primary 和 Secondary 值。

当 Order 属性设置为 Primary 时，ToolbarItem 对象将显示在所有平台上的主导航栏中。 ToolbarItem 对象优先于页面标题，该标题将被截断，以便为项腾出空间。 以下屏幕截图显示了 iOS 和 Android 上的主菜单中的 ToolbarItem 对象：

当 Order 属性设置为 Secondary 时，行为因平台而异。 在 UWP 和 Android 上，Secondary 项菜单显示为三个点，点击或单击它可显示垂直列表中的项。 在 iOS 上，Secondary 项菜单在导航栏下方显示为水平列表。 以下屏幕截图显示 iOS 和 Android 上的辅助菜单：

警告

将 Order 属性设置为 Secondary 的 ToolbarItem 对象中的图标行为因平台而异。 避免在辅助菜单中出现的项目上设置 IconImageSource 属性。

相关链接

• ToolbarItem 演示
• Xamarin.Forms 中的图像
• Xamarin.Forms MenuItem