显示工具栏项

. NET Multi-platform App UI (.NET MAUI) ToolbarItem 类是一种特殊类型的按钮，可以添加到 Page 对象的 ToolbarItems 集合中。 因为 Shell 类派生自 Page，所以 ToolbarItem 对象也可以添加到 Shell 对象的 ToolbarItems 集合中。 每个 ToolbarItem 对象将作为按钮显示在应用的导航栏中。 ToolbarItem 对象可以具有图标，并显示为主要项或辅助项。 ToolbarItem 类继承自 MenuItem。

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

ToolbarItem 类定义以下属性：

• Order，类型为 ToolbarItemOrder，确定 ToolbarItem 对象在主要菜单还是辅助菜单中显示。
• Priority，类型为 int，确定 ToolbarItems 集合中项的显示顺序。

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

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

这些属性由 BindableProperty 对象提供支持；也就是说，它们可以作为数据绑定的目标。

注意

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

创建 ToolbarItem

若要创建工具栏项，请创建一个 ToolbarItem 对象并设置其属性以定义其外观和行为。 以下示例演示如何创建具有最小属性集的 ToolbarItem ，并将其添加到 ContentPage 的 ToolbarItems 集合中：

<ContentPage.ToolbarItems>
    <ToolbarItem Text="Add item"
                 IconImageSource="add.png" />
</ContentPage.ToolbarItems>

此示例生成一个包含文本和图标的 ToolbarItem 对象。 但是，不同平台的 ToolbarItem 外观各不相同。

还可以在代码中创建 ToolbarItem 并将其添加到 ToolbarItems 集合中：

ToolbarItem item = new ToolbarItem
{
    Text = "Add item",
    IconImageSource = ImageSource.FromFile("add.png")
};

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

注意

图像可以存储在应用项目中的单个位置。 有关详细信息，请参阅将图像添加到 .NET MAUI 项目。

定义按钮行为

ToolbarItem 类从 MenuItem 类继承 Clicked 事件。 事件处理程序可以附加到 Clicked 事件，以响应对 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 属性响应用户输入，而无需事件处理程序。

在运行时启用或禁用 ToolbarItem

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

重要

使用 Command 属性启用或禁用 ToolbarItem 时，请勿将 IsEnabled 属性绑定到另一个属性。

主工具栏和辅助工具栏项

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

当属性 Order 设置为 Primary 时，ToolbarItem 对象将显示在所有平台上的导航栏中。 ToolbarItem 对象优先于页面标题，这会导致页面标题被截断，以便为这些项腾出空间。

当属性 Order 设置为 Secondary 时，行为因平台而异。 在 iOS 和 Mac Catalyst 上，Secondary 工具栏项显示为水平列表。 在 Android 和 Windows 上，Secondary 项菜单显示为三个可以点击的点：

点击三个点可显示垂直列表中的项：

警告

将 Order 属性设置为 Secondary 的 ToolbarItem 对象中的图标行为在不同平台上是不一致的。 避免对出现在二级菜单中的项设置 IconImageSource 属性。