Compartilhar via

Configurar a seleção de itens da CollectionView

  • Artigo

Procurar amostra. Procurar no exemplo

A .NET Multi-Platform App UI (.NET MAUI) CollectionView define as seguintes propriedades que controlam a seleção de itens:

  • SelectionMode, do tipo SelectionMode, o modo de seleção.
  • SelectedItem, do tipo object, o item selecionado na lista. Essa propriedade tem um modo de vinculação padrão TwoWay e um valor null quando nenhum item estiver selecionado.
  • SelectedItems, do tipo IList<object>, os itens selecionados na lista. Essa propriedade tem um modo de vinculação padrão OneWay e um valor null quando nenhum item estiver selecionado.
  • SelectionChangedCommand, do tipo ICommand, que é executado quando o item selecionado é alterado.
  • SelectionChangedCommandParameter, do tipo object, que é o parâmetro passado para SelectionChangedCommand.

Todas essas propriedades são apoiadas por objetos BindableProperty, o que significa que essas propriedades podem ser o destino de vinculações de dados.

Por padrão, a seleção da CollectionView está desabilitada. No entanto, esse comportamento pode ser alterado ao definir o valor da propriedade SelectionMode para um dos membros da enumeração SelectionMode:

  • None — indica que os itens não podem ser selecionados. Este é o valor padrão.
  • Single — indica que um único item pode ser selecionado, com o item selecionado sendo realçado.
  • Multiple — indica que vários itens podem ser selecionados, com os itens selecionados sendo realçados.

CollectionView define um evento SelectionChanged que é acionado quando a propriedade SelectedItem é alterada, ou devido ao fato de o usuário selecionar um item na lista ou quando um aplicativo define a propriedade. Além disso, esse evento também é acionado quando a propriedade SelectedItems é alterada. O objeto SelectionChangedEventArgs que acompanha o evento SelectionChanged tem duas propriedades, ambas do tipo IReadOnlyList<object>:

  • PreviousSelection — a lista de itens que foram selecionados, antes de a seleção ter sido alterada.
  • CurrentSelection — a lista de itens selecionados após a alteração da seleção.

Além disso, CollectionView tem um método UpdateSelectedItems que atualiza a propriedade SelectedItems com uma lista de itens selecionados, embora dispare apenas uma única notificação de alteração.

Seleção única

Quando a propriedade SelectionMode é definida como Single, um único item na CollectionView pode ser selecionado. Quando um item é selecionado, a propriedade SelectedItem é definida como o valor do item selecionado. Quando essa propriedade é alterada, o SelectionChangedCommand é executado (com o valor do SelectionChangedCommandParameter sendo repassado para o ICommand) e o evento SelectionChanged é acionado.

O exemplo XAML a seguir mostra uma CollectionView que pode responder à seleção de um único item:

<CollectionView ItemsSource="{Binding Monkeys}"
                SelectionMode="Single"
                SelectionChanged="OnCollectionViewSelectionChanged">
    ...
</CollectionView>

Este é o código C# equivalente:

CollectionView collectionView = new CollectionView
{
    SelectionMode = SelectionMode.Single
};
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
collectionView.SelectionChanged += OnCollectionViewSelectionChanged;

Nesse exemplo de código, o manipulador de eventos OnCollectionViewSelectionChanged é executado quando o evento SelectionChanged é acionado, com o manipulador de eventos recuperando o item selecionado anteriormente e o item selecionado atual:

void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    string previous = (e.PreviousSelection.FirstOrDefault() as Monkey)?.Name;
    string current = (e.CurrentSelection.FirstOrDefault() as Monkey)?.Name;
    ...
}

Importante

O evento SelectionChanged pode ser acionado por alterações que ocorrem como resultado da alteração da propriedade SelectionMode.

A captura de tela a seguir mostra a seleção de um único item em uma CollectionView:

Captura de tela de uma lista vertical da CollectionView com uma única seleção.

Seleção múltipla

Quando a propriedade SelectionMode é definida como Multiple, vários itens podem ser selecionados na CollectionView. Quando os itens são selecionados, a propriedade SelectedItems é definida para os itens selecionados. Quando essa propriedade é alterada, o SelectionChangedCommand é executado (com o valor do SelectionChangedCommandParameter sendo repassado para o ICommand) e o evento SelectionChanged é acionado.

O exemplo XAML a seguir mostra uma CollectionView que pode responder à seleção de vários itens:

<CollectionView ItemsSource="{Binding Monkeys}"
                SelectionMode="Multiple"
                SelectionChanged="OnCollectionViewSelectionChanged">
    ...
</CollectionView>

Este é o código C# equivalente:

CollectionView collectionView = new CollectionView
{
    SelectionMode = SelectionMode.Multiple
};
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
collectionView.SelectionChanged += OnCollectionViewSelectionChanged;

Nesse exemplo de código, o manipulador de eventos OnCollectionViewSelectionChanged é executado quando o evento SelectionChanged é acionado, com o manipulador de eventos recuperando os itens selecionados anteriormente e os itens selecionados atuais:

void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    var previous = e.PreviousSelection;
    var current = e.CurrentSelection;
    ...
}

Importante

O evento SelectionChanged pode ser acionado por alterações que ocorrem como resultado da alteração da propriedade SelectionMode.

A captura de tela a seguir mostra a seleção de vários itens em uma CollectionView:

Captura de tela de uma lista vertical da CollectionView com várias seleções.

Pré-seleção única

Quando a propriedade SelectionMode é definida como Single, um único item pode ser pré-selecionado na CollectionView ao definir a propriedade SelectedItem para o item. O exemplo XAML a seguir mostra uma CollectionView que pré-seleciona um único item:

<CollectionView ItemsSource="{Binding Monkeys}"
                SelectionMode="Single"
                SelectedItem="{Binding SelectedMonkey}">
    ...
</CollectionView>

Este é o código C# equivalente:

CollectionView collectionView = new CollectionView
{
    SelectionMode = SelectionMode.Single
};
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
collectionView.SetBinding(SelectableItemsView.SelectedItemProperty, "SelectedMonkey");

Observação

A propriedade SelectedItem tem um modo de vinculação padrão de TwoWay.

Os dados da propriedade SelectedItem se vinculam à propriedade SelectedMonkey do modelo de exibição conectado, que é do tipo Monkey. Por padrão, uma vinculação TwoWay é usada de modo que, se o usuário alterar o item selecionado, o valor da propriedade SelectedMonkey seja definido para o objeto Monkey selecionado. A propriedade SelectedMonkey é definida na classe MonkeysViewModel e configurada para o quarto item da coleção Monkeys:

public class MonkeysViewModel : INotifyPropertyChanged
{
    ...
    public ObservableCollection<Monkey> Monkeys { get; private set; }

    Monkey selectedMonkey;
    public Monkey SelectedMonkey
    {
        get
        {
            return selectedMonkey;
        }
        set
        {
            if (selectedMonkey != value)
            {
                selectedMonkey = value;
            }
        }
    }

    public MonkeysViewModel()
    {
        ...
        selectedMonkey = Monkeys.Skip(3).FirstOrDefault();
    }
    ...
}

Portanto, quando a CollectionView aparece, o quarto item da lista é pré-selecionado:

Captura de tela de uma lista vertical da CollectionView com uma única pré-seleção.

Pré-seleção múltipla

Quando a propriedade SelectionMode é definida como Multiple, vários itens podem ser pré-selecionados na CollectionView. O exemplo XAML a seguir mostra uma CollectionView que permite a pré-seleção de vários itens:

<CollectionView x:Name="collectionView"
                ItemsSource="{Binding Monkeys}"
                SelectionMode="Multiple"
                SelectedItems="{Binding SelectedMonkeys}">
    ...
</CollectionView>

Este é o código C# equivalente:

CollectionView collectionView = new CollectionView
{
    SelectionMode = SelectionMode.Multiple
};
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
collectionView.SetBinding(SelectableItemsView.SelectedItemsProperty, "SelectedMonkeys");

Observação

A propriedade SelectedItems tem um modo de vinculação padrão de OneWay.

Os dados da propriedade SelectedItems se vinculam à propriedade SelectedMonkeys do modelo de exibição conectado, que é do tipo ObservableCollection<object>. A propriedade SelectedMonkeys é definida na classe MonkeysViewModel e configurada para o segundo, quarto e quinto itens da coleção Monkeys:

namespace CollectionViewDemos.ViewModels
{
    public class MonkeysViewModel : INotifyPropertyChanged
    {
        ...
        ObservableCollection<object> selectedMonkeys;
        public ObservableCollection<object> SelectedMonkeys
        {
            get
            {
                return selectedMonkeys;
            }
            set
            {
                if (selectedMonkeys != value)
                {
                    selectedMonkeys = value;
                }
            }
        }

        public MonkeysViewModel()
        {
            ...
            SelectedMonkeys = new ObservableCollection<object>()
            {
                Monkeys[1], Monkeys[3], Monkeys[4]
            };
        }
        ...
    }
}

Portanto, quando a CollectionView aparece, o segundo, o quarto e o quinto itens da lista são pré-selecionados:

Captura de tela de uma lista vertical da CollectionView com várias pré-seleções.

Limpar seleções

As propriedades SelectedItem e SelectedItems podem ser removidas ao defini-las ou aos objetos aos quais se vinculam como null. Quando qualquer uma dessas propriedades é removida, o evento SelectionChanged é gerado com uma propriedade CurrentSelection vazia e o SelectionChangedCommand é executado.

Manipular a nova seleção

Um cenário comum é o que usuários selecionarão um item no CollectionView e navegarão para outra página. Ao voltarem, o item ainda estará selecionado, o que resultará na impossibilidade de selecionar novamente o item. Para habilitar a nova seleção, você deve limpar a seleção do item no CollectionView:

<CollectionView ...
                SelectionChanged="OnCollectionViewSelectionChanged" />

Este é o código C# equivalente:

CollectionView collectionView = new CollectionView();
collectionView.SelectionChanged += OnCollectionViewSelectionChanged;

O exemplo a seguir mostra o código do manipulador de eventos para o evento SelectionChanged.

void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    var cv = (CollectionView)sender;
    if (cv.SelectedItem == null)
        return;

    cv.SelectedItem = null;
}

Alterar a cor do item selecionado

A CollectionView tem um VisualState Selected que pode ser usado para iniciar uma alteração visual para o item selecionado na CollectionView. Um caso de uso comum para esse VisualState é alterar a cor da tela de fundo do item selecionado, que é mostrada no seguinte exemplo XAML:

<ContentPage ...>
    <ContentPage.Resources>
        <Style TargetType="Grid">
            <Setter Property="VisualStateManager.VisualStateGroups">
                <VisualStateGroupList>
                    <VisualStateGroup x:Name="CommonStates">
                        <VisualState x:Name="Normal" />
                        <VisualState x:Name="Selected">
                            <VisualState.Setters>
                                <Setter Property="BackgroundColor"
                                        Value="LightSkyBlue" />
                            </VisualState.Setters>
                        </VisualState>
                    </VisualStateGroup>
                </VisualStateGroupList>
            </Setter>
        </Style>
    </ContentPage.Resources>
    <Grid Margin="20">
        <CollectionView ItemsSource="{Binding Monkeys}"
                        SelectionMode="Single">
            <CollectionView.ItemTemplate>
                <DataTemplate>
                    <Grid Padding="10">
                        ...
                    </Grid>
                </DataTemplate>
            </CollectionView.ItemTemplate>
        </CollectionView>
    </Grid>
</ContentPage>

Importante

O Style que contém o VisualState Selected precisa ter um valor da propriedade TargetType que seja o tipo do elemento raiz do DataTemplate, que é definido como o valor da propriedade ItemTemplate.

O código em C# equivalente para o estilo que contém o estado visual é:

using static Microsoft.Maui.Controls.VisualStateManager;
...

Setter backgroundColorSetter = new() { Property = BackgroundColorProperty, Value = Colors.LightSkyBlue };
VisualState stateSelected = new() { Name = CommonStates.Selected, Setters = { backgroundColorSetter } };
VisualState stateNormal = new() { Name = CommonStates.Normal };
VisualStateGroup visualStateGroup = new() { Name = nameof(CommonStates), States = { stateSelected, stateNormal } };
VisualStateGroupList visualStateGroupList = new() { visualStateGroup };
Setter vsgSetter = new() { Property = VisualStateGroupsProperty, Value = visualStateGroupList };
Style style = new(typeof(Grid)) { Setters = { vsgSetter } };

// Add the style to the resource dictionary
Resources.Add(style);

Nesse exemplo, o valor da propriedade Style.TargetType é definido como Grid porque o elemento raiz do ItemTemplate é uma Grid. O VisualState Selected especifica que, quando um item é selecionado na CollectionView, o item BackgroundColor é configurado como LightSkyBlue:

Captura de tela de uma lista vertical da CollectionView com uma única cor de seleção personalizada.

Para obter mais informações sobre estados visuais, consulte Estados visuais.

Desabilitar a seleção

A seleção da CollectionView é desabilitada por padrão. No entanto, se uma CollectionView tiver uma seleção habilitada, esta poderá ser desabilitada ao definir a propriedade SelectionMode como None:

<CollectionView ...
                SelectionMode="None" />

Este é o código C# equivalente:

CollectionView collectionView = new CollectionView
{
    ...
    SelectionMode = SelectionMode.None
};

Quando a propriedade SelectionMode é definida como None, os itens na CollectionView não podem ser selecionados, a propriedade SelectedItem permanece como null e o evento SelectionChanged não é acionado.

Observação

Quando um item tiver sido selecionado e a propriedade SelectionMode for alterada de Single para None, a propriedade SelectedItem será definida como null e o evento SelectionChanged será acionado com uma propriedade CurrentSelection vazia.