Compartilhar via

Xamarin.Forms Item da barra de ferramentas

  • Artigo

A Xamarin.FormsToolbarItem classe é um tipo especial de botão que pode ser adicionado à coleção de um PageToolbarItems objeto. Cada ToolbarItem objeto aparecerá como um botão na barra de navegação do aplicativo. Uma ToolbarItem instância pode ter um ícone e aparecer como um item de menu primário ou secundário. A classe ToolbarItem herda de MenuItem.

As capturas de tela a seguir mostram ToolbarItem objetos na barra de navegação no iOS e Android:

A classe ToolbarItem define as seguintes propriedades:

  • Order é um ToolbarItemOrder valor de enum que determina se a ToolbarItem instância é exibida no menu primário ou secundário.
  • Priorityé um integer valor que determina a ordem de exibição dos itens na coleção de ToolbarItems um Page objeto.

A ToolbarItem classe herda as seguintes propriedades normalmente usadas da MenuItem classe:

  • Command é um ICommand que permite vincular ações do usuário, como toques ou cliques com o dedo, a comandos definidos em um ViewModel.
  • CommandParameter é um object que especifica o parâmetro que deve ser passado para o Command.
  • IconImageSource é um ImageSource valor que determina o ícone de exibição em um ToolbarItem objeto.
  • Text é um string que determina o texto de exibição em um ToolbarItem objeto.

Essas propriedades são apoiadas por objetos para BindableProperty que uma ToolbarItem instância possa ser o destino de associações de dados.

Observação

Uma alternativa para criar uma barra de ferramentas a partir de objetos é definir a propriedade anexada NavigationPage.TitleView para uma classe de layout que contém vários modos de ToolbarItem exibição. Para obter mais informações, consulte Exibindo modos de exibição na barra de navegação.

Criar um ToolbarItem

Um ToolbarItem objeto pode ser instanciado em XAML. As Text propriedades e IconImageSource podem ser definidas para determinar como o botão é exibido na barra de navegação. O exemplo a seguir mostra como instanciar um ToolbarItem com algumas propriedades comuns definidas e adicioná-lo a uma ContentPagecoleção 's ToolbarItems :

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

Este exemplo resultará em um ToolbarItem objeto que tem texto, um ícone e aparece primeiro na área da barra de navegação principal. A ToolbarItem também pode ser criado em código e adicionado à ToolbarItems coleção:

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

O arquivo representado pelo string, fornecido como a IconImageSource propriedade, deve existir em cada projeto de plataforma.

Observação

Os ativos de imagem são tratados de forma diferente em cada plataforma. Um ImageSource pode vir de fontes, incluindo um arquivo local ou recurso incorporado, um URI ou um fluxo. Para obter mais informações sobre como definir a propriedade e Imagens no , consulte Imagens no .Xamarin.FormsXamarin.FormsIconImageSource

Definir o comportamento do botão

A ToolbarItem classe herda o Clicked evento da MenuItem classe. Um manipulador de eventos pode ser anexado ao Clicked evento para reagir a toques ou cliques em ToolbarItem instâncias em XAML:

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

Um manipulador de eventos também pode ser anexado no código:

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

Exemplos anteriores faziam referência a um manipulador de OnItemClicked eventos. O código a seguir mostra um exemplo de implementação:

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

ToolbarItem Os objetos também podem usar as Command propriedades e CommandParameter para reagir à entrada do usuário sem manipuladores de eventos. Para obter mais informações sobre a interface e a ICommand associação de dados MVVM, consulte Xamarin.Forms Comportamento MVVM MenuItem.

Habilitar ou desabilitar um ToolbarItem em tempo de execução

Para habilitar a desabilitação de um ToolbarItem em tempo de execução, vincule sua Command propriedade a uma ICommand implementação e certifique-se de que um canExecute delegado habilite e desabilite o ICommand conforme apropriado.

Para obter mais informações, consulte Habilitar ou desabilitar um MenuItem em tempo de execução.

Menus primário e secundário

O ToolbarItemOrder enum tem Default, Primarye Secondary valores.

Quando a Order propriedade é definida como Primary, o ToolbarItem objeto aparecerá na barra de navegação principal em todas as plataformas. ToolbarItem Os objetos são priorizados sobre o título da página, que será truncado para abrir espaço para os itens. As capturas de tela a seguir mostram ToolbarItem objetos no menu principal no iOS e Android:

Quando a propriedade é definida como Secondary, o Order comportamento varia entre plataformas. Na UWP e no Android, o Secondary menu de itens aparece como três pontos que podem ser tocados ou clicados para revelar itens em uma lista vertical. No iOS, o menu de Secondary itens aparece abaixo da barra de navegação como uma lista horizontal. As capturas de tela a seguir mostram um menu secundário no iOS e Android:

Aviso

O comportamento do ícone em ToolbarItem objetos que têm sua Order propriedade definida como Secondary é inconsistente entre plataformas. Evite definir a IconImageSource propriedade em itens que aparecem no menu secundário.