Barra seletora

Uma barra seletora permite que um usuário alterne entre um pequeno número de diferentes conjuntos ou exibições de dados. É possível selecionar um item de cada vez.

Quando um usuário seleciona um item na barra de seleção, você normalmente altera a exibição ao:

• navegar entre páginas diferentes na sua aplicação.
• alterando os dados mostrados em um controle de coleção.

A barra seletora é um controle leve que suporta um ícone e texto. Destina-se a apresentar um número limitado de opções para não reorganizar os itens para se adaptar a diferentes tamanhos de janela.

Será este o controlo correto?

Use uma SelectorBar quando quiser permitir que um usuário navegue entre um número limitado de visualizações ou páginas e apenas uma opção pode ser selecionada ao mesmo tempo.

Eis alguns exemplos:

• Alternar entre páginas "Recentes", "Compartilhadas" e "Favoritas", onde cada página exibe uma lista exclusiva de conteúdo.
• Alternar entre as visualizações "Todos", "Não lidos", "Sinalizados" e "Urgentes", em que cada exibição exibe uma lista filtrada exclusivamente de itens de e-mail.

Quando deve ser utilizado um controlo diferente?

Existem alguns cenários em que outro controle pode ser mais apropriado para usar.

• Use o NavigationView quando precisar de uma navegação consistente de aplicativo de nível superior que se adapte a diferentes tamanhos de janela.
• Use TabView quando o usuário puder abrir, fechar, reorganizar ou remover novas visualizações do conteúdo.
• Use o PipsPager quando precisar de paginação regular de uma única visualização de dados.
• Use RadioButtons quando uma opção não estiver selecionada por padrão e o contexto não estiver relacionado à navegação da página.

Criar um controle SelectorBar

• APIs importantes: classe SelectorBar, propriedade Items, evento SelectionChanged, classe SelectorBarItem

Abra o aplicativo WinUI 3 Gallery e veja a SelectorBar em ação

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Este XAML cria um controle SelectorBar básico com 3 seções de conteúdo.

<SelectorBar x:Name="SelectorBar">
    <SelectorBarItem x:Name="SelectorBarItemRecent" 
                     Text="Recent" Icon="Clock"/>
    <SelectorBarItem x:Name="SelectorBarItemShared" 
                     Text="Shared" Icon="Share"/>
    <SelectorBarItem x:Name="SelectorBarItemFavorites" 
                     Text="Favorites" Icon="Favorite"/>
</SelectorBar>

Isso mostra como adicionar um SelectorBarItem no código.

SelectorBarItem newItem = new SelectorBarItem()
{
    Text = "New Item",
    Icon = new SymbolIcon(Symbol.Add)
};
selectorBar.Items.Add(newItem);

Itens da SelectorBar

Você preenche a coleção SelectorBar Items com objetos SelectorBarItem . Você pode fazer isso diretamente em XAML ou em código. Como se destina a exibir um número limitado de opções, SelectorBar não tem uma ItemsSource propriedade para vincular a uma coleção externa de itens.

Conteúdo do item

A classe SelectorBarItem fornece propriedades Text e Icon que você usa para definir o conteúdo da barra de seletores. Você pode definir uma ou ambas as propriedades; no entanto, recomendamos que você defina a Text propriedade para tornar o item mais significativo.

A Icon propriedade usa um IconElement, para que você possa usar qualquer um destes tipos de ícones derivados:

• AnimatedIcon
• BitmapIcon
• FontIcon
• IconSourceElement
• ImageIcon
• PathIcon
• SymbolIcon

Observação

SelectorBarItem herda a propriedade Child de ItemContainer. Você pode usar essa propriedade para definir o conteúdo, mas não recomendamos isso. O conteúdo definido dessa maneira não obterá o estilo e os estados visuais fornecidos pelo modelo de controle SelectorBarItem.

Seleção de itens

Você pode usar a propriedade SelectedItem para obter ou definir o item ativo da SelectorBar. Isso é sincronizado com a propriedade IsSelected do SelectorBarItem. Se você definir uma das propriedades, a outra será atualizada automaticamente.

Sempre que a SelectorBar recebe foco e SelectedItem é null, SelectedItem é automaticamente definida como a primeira instância focalizável na coleção Items , se houver alguma.

Sempre que o item selecionado é removido da Items coleção, a SelectedItem propriedade é definida como null. Se SelectedItem estiver definido como null enquanto a SelectorBar tiver foco, SelectorBar não terá nenhum item selecionado, mas manterá o foco.

A configuração SelectedItem de um elemento que não está atualmente na Items coleção gera uma exceção.

Não há propriedade SelectedIndex , mas você pode obter o SelectedItem índice do tipo:

int currentSelectedIndex = 
    selectorBar.Items.IndexOf(selectorBar.SelectedItem);

Seleção alterada

Manipule o evento SelectionChanged para responder à seleção de usuários e alterar o que é mostrado ao usuário. O SelectionChanged evento é gerado quando um item é selecionado de qualquer uma destas maneiras:

• Automação da interface do usuário
• Foco na tabulação (e um novo item é selecionado)
• Navegação à esquerda e à direita na SelectorBar
• Evento tocado através do rato ou toque
• Seleção programática (por meio da propriedade SelectorBar.SelectedItem ou da propriedade IsSelected de SelectorBarItem).

Quando um usuário seleciona um item, você normalmente altera a exibição navegando entre páginas diferentes em seu aplicativo ou alterando os dados mostrados em um controle de coleção. Exemplos de ambos são mostrados aqui.

Navegar com animações de transição

Sugestão

Você pode encontrar esses exemplos na página SelectorBar do aplicativo WinUI Gallery. Use o aplicativo WinUI Gallery para executar e exibir o código completo.

Este exemplo demonstra a manipulação do evento SelectionChanged para navegar entre páginas diferentes. A navegação usa o SlideNavigationTransitionEffect para deslizar as páginas da esquerda ou da direita, conforme apropriado.

<SelectorBar x:Name="SelectorBar2" 
             SelectionChanged="SelectorBar2_SelectionChanged">
    <SelectorBarItem x:Name="SelectorBarItemPage1" Text="Page1" 
                     IsSelected="True" />
    <SelectorBarItem x:Name="SelectorBarItemPage2" Text="Page2" />
    <SelectorBarItem x:Name="SelectorBarItemPage3" Text="Page3" />
    <SelectorBarItem x:Name="SelectorBarItemPage4" Text="Page4" />
    <SelectorBarItem x:Name="SelectorBarItemPage5" Text="Page5" />
</SelectorBar>

<Frame x:Name="ContentFrame" IsNavigationStackEnabled="False" />

int previousSelectedIndex = 0;

private void SelectorBar2_SelectionChanged
             (SelectorBar sender, SelectorBarSelectionChangedEventArgs args)
{
    SelectorBarItem selectedItem = sender.SelectedItem;
    int currentSelectedIndex = sender.Items.IndexOf(selectedItem);
    System.Type pageType;

    switch (currentSelectedIndex)
    {
        case 0:
            pageType = typeof(SamplePage1);
            break;
        case 1:
            pageType = typeof(SamplePage2);
            break;
        case 2:
            pageType = typeof(SamplePage3);
            break;
        case 3:
            pageType = typeof(SamplePage4);
            break;
        default:
            pageType = typeof(SamplePage5);
            break;
    }

    var slideNavigationTransitionEffect = 
            currentSelectedIndex - previousSelectedIndex > 0 ? 
                SlideNavigationTransitionEffect.FromRight : 
                SlideNavigationTransitionEffect.FromLeft;

    ContentFrame.Navigate(pageType, null, new SlideNavigationTransitionInfo() 
                            { Effect = slideNavigationTransitionEffect });

    previousSelectedIndex = currentSelectedIndex;
}

Exibir coleções diferentes em um ItemsView

Este exemplo mostra como alterar a fonte de dados de um ItemsView quando o usuário seleciona uma opção na SelectorBar.

<SelectorBar x:Name="SelectorBar3" 
             SelectionChanged="SelectorBar3_SelectionChanged">
    <SelectorBarItem x:Name="SelectorBarItemPink" Text="Pink"
                     IsSelected="True"/>
    <SelectorBarItem x:Name="SelectorBarItemPlum" Text="Plum"/>
    <SelectorBarItem x:Name="SelectorBarItemPowderBlue" Text="PowderBlue"/>
</SelectorBar>

<ItemsView x:Name="ItemsView3" 
           ItemTemplate="{StaticResource ColorsTemplate}"/>
    <ItemsView.Layout>
        <UniformGridLayout/>
    </ItemsView.Layout>
</ItemsView/>

private void SelectorBar3_SelectionChanged
             (SelectorBar sender, SelectorBarSelectionChangedEventArgs args)
{
    if (sender.SelectedItem == SelectorBarItemPink)
    {
        ItemsView3.ItemsSource = PinkColorCollection;
    }
    else if (sender.SelectedItem == SelectorBarItemPlum)
    {
        ItemsView3.ItemsSource = PlumColorCollection;
    }
    else
    {
        ItemsView3.ItemsSource = PowderBlueColorCollection;
    }
}

UWP e WinUI 2

Importante

O controle SelectorBar não está disponível para UWP e WinUI 2. Para obter alternativas, consulte NavigationView ou TabView.

Tópicos relacionados

• Classe SelectorBar
• Noções básicas de design de navegação