Configurar a seleção de itens CollectionView

Navegue pelo exemplo

A interface do usuário do aplicativo multiplataforma .NET (.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 de TwoWay, e tem um null valor quando nenhum item é selecionado.
• SelectedItems, do tipo IList<object>, os itens selecionados na lista. Essa propriedade tem um modo de vinculação padrão de OneWay, e tem um null valor quando nenhum item é 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, CollectionView a seleção está desabilitada. No entanto, esse comportamento pode ser alterado definindo o SelectionMode valor da propriedade para um dos membros de SelectionMode enumeração:

• None – indica que os itens não podem ser selecionados. Esse é o valor padrão.
• Single – indica que um único item pode ser selecionado, com o item selecionado sendo destacado.
• Multiple – indica que vários itens podem ser selecionados, com os itens selecionados sendo destacados.

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

• PreviousSelection – a lista de itens que foram selecionados, antes da seleção mudar.
• CurrentSelection – a lista de itens que são selecionados, após a mudança de seleção.

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

Seleção única

Quando a SelectionMode propriedade é definida como Single, um único item no CollectionView pode ser selecionado. Quando um item é selecionado, a SelectedItem propriedade é definida como o valor do item selecionado. Quando essa propriedade é alterada, o é executado (com o valor do SelectionChangedCommandParameter sendo passado para o ) e o SelectionChangedSelectionChangedCommandICommandevento é acionado.

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

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

Neste exemplo de código, o manipulador de eventos é executado quando o evento é acionado, com o manipulador de eventos recuperando o item selecionado anteriormente e o OnCollectionViewSelectionChangedSelectionChanged 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 SelectionChanged evento pode ser acionado por alterações que ocorrem como resultado da alteração da SelectionMode propriedade.

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

Seleção múltipla

Quando a SelectionMode propriedade é definida como Multiple, vários itens no CollectionView podem ser selecionados. Quando os itens são selecionados, a propriedade é definida como os SelectedItems itens selecionados. Quando essa propriedade é alterada, o é executado (com o valor do SelectionChangedCommandParameter sendo passado para o , e o SelectionChangedSelectionChangedCommandICommandevento é acionado.

O exemplo XAML a seguir mostra um que pode responder à seleção de CollectionView 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;

Neste exemplo de código, o manipulador de eventos é executado quando o evento é acionado, com o OnCollectionViewSelectionChangedSelectionChanged manipulador de eventos recuperando os itens selecionados anteriormente e os itens selecionados atualmente:

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

Importante

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

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

Pré-seleção única

Quando a propriedade é definida como Single, um único item no CollectionView pode ser pré-selecionado definindo a SelectionModeSelectedItem propriedade para o item. O exemplo XAML a seguir mostra um que pré-seleciona um CollectionView ú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 SelectedItem propriedade tem um modo de vinculação padrão de TwoWay.

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

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 o CollectionView aparece, o quarto item da lista é pré-selecionado:

Pré-seleção múltipla

Quando a SelectionMode propriedade é definida como Multiple, vários itens no CollectionView podem ser pré-selecionados. O exemplo XAML a seguir mostra um 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 SelectedItems propriedade tem um modo de vinculação padrão de OneWay.

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

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 o aparece, o CollectionView segundo, quarto e quinto itens da lista são pré-selecionados:

Limpar seleções

As SelectedItem propriedades e SelectedItems podem ser limpas definindo-as, ou os objetos aos quais se vinculam, como null. Quando uma dessas propriedades é limpa, o evento é gerado com uma propriedade vazia CurrentSelection e o SelectionChangedSelectionChangedCommand é executado.

Alterar a cor do item selecionado

CollectionView tem um SelectedVisualState que pode ser usado para iniciar uma alteração visual no item selecionado no CollectionView. Um caso de uso comum para isso VisualState é alterar a cor do plano de fundo do item selecionado, que é mostrado no exemplo XAML a seguir:

<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 deve ter um TargetType valor de propriedade que é o tipo do elemento raiz do , que é definido como o SelectedVisualState valor da ItemTemplateDataTemplatepropriedade.

O código 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);

Neste exemplo, o valor da propriedade é definido como Grid porque o Style.TargetType elemento raiz do ItemTemplate é um Gridarquivo . O SelectedVisualState especifica que, quando um item no CollectionView é selecionado, o BackgroundColor do item é definido como LightSkyBlue:

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

Desativar seleção

CollectionView A seleção está desabilitada por padrão. No entanto, se uma CollectionView seleção estiver habilitada, ela poderá ser desabilitada definindo a SelectionMode propriedade como None:

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

Este é o código C# equivalente:

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

Quando a propriedade é definida como None, os itens no CollectionView não podem ser selecionados, a SelectedItemSelectionMode propriedade permanece nulle o SelectionChanged evento não é disparado.

Observação

Quando um item tiver sido selecionado e a propriedade for alterada de para None, a SelectedItemSelectionMode propriedade será definida como null e o evento será disparado SelectionChanged com uma propriedade vaziaCurrentSelection.Single