Beobachtbare gruppierte Sammlungs-APIs

2024-11-07

Das MVVM-Toolkit verfügt über mehrere feststellbare gruppierte Sammlung und eine Gruppe von Hilfs-APIs, um die Arbeit mit gruppierter Sammlung von Elementen zu erleichtern, die dann an die Benutzeroberfläche gebunden werden können. Dies kann hilfreich sein, wenn Sie UIs erstellen, z. B. gruppierte Kontaktlisten oder eine beliebige Art von gruppierter Sammlung von Elementen, mit denen der Benutzer dann interagieren kann.

Plattform-APIs: ObservableGroup<TKey, TElement>, ReadOnlyObservableGroup<TKey, TElement>, IReadOnlyObservableGroup, IReadOnlyObservableGroup, ObservableGroupedCollection<TKey, TElement>, ReadOnlyObservableGroupedCollection<TKey, TElement>, ObservableGroupedCollectionExtensions

ObservableGroup<TKey, TElement> und ReadOnlyObservableGroup<TKey, TElement>

Die ObservableGroup<TKey, TElement>- und ReadOnlyObservableGroup<TKey, TElement>-Typen sind benutzerdefinierte feststellbare Sammlungstypen, die ObservableCollection<T> erben und ReadOnlyObservableCollection<T> die auch Gruppierungsunterstützung bieten. Dies ist besonders nützlich, wenn eine gruppierte Sammlung von Elementen an die Benutzeroberfläche gebunden wird, z. B. zum Anzeigen einer Liste von Kontakten.

ObservableGroup<TKey, TElement-Features>

ObservableGroup<TKey, TElement> und ReadOnlyObservableGroup<TKey, TElement> haben die folgenden Hauptfunktionen:

Sie erben von ObservableCollection<T> und ReadOnlyObservableCollection<T>stellen somit dieselbe Benachrichtigungsunterstützung bereit, wenn Elemente in der Sammlung hinzugefügt, entfernt oder geändert werden.
Sie implementieren auch die IGrouping<TKey, TElement>-Schnittstelle, sodass Instanzen als Argumente für alle vorhandenen LINQ-Erweiterungen verwendet werden können, die auf Instanzen dieser Schnittstelle arbeiten.
Sie implementieren mehrere Schnittstellen aus dem MVVM-Toolkit (IReadOnlyObservableGroup, IReadOnlyObservableGroup<TKey> und IReadOnlyObservableGroup<TKey, TElement>), die eine unterschiedliche Abstraktionsebene über Instanzen dieser beiden Sammlungstypen ermöglichen. Dies kann besonders bei Datenvorlagen hilfreich sein, bei denen nur Teiltypinformationen verfügbar sind oder verwendet werden können.

ObservableGroupedCollection<TKey, TElement und ReadOnlyObservableGroupedCollection< TKey, TElement>>

ObservableGroupedCollection<TKey, TElement> und ReadOnlyObservableGroupedCollection<TKey, TElement> sind feststellbare Sammlungstypen, bei denen es sich bei jedem Element um einen gruppierten Sammlungstyp (entweder ObservableGroup<TKey, TElement> oder ReadOnlyObservableGroup<TKey, TElement>) handelt, der ebenfalls ILookup<TKey, TElement> implementiert.

ObservableGroupedCollection<TKey, TElement-Features>

ObservableGroupedCollection<TKey, TElement> und ReadOnlyObservableGroupedCollection<TKey, TElement> haben die folgenden Hauptfunktionen:

Sie erben von ObservableCollection<T> und ReadOnlyObservableCollection<T>, also genau wie ObservableGroup<TKey, TElement> und ReadOnlyObservableGroup<TKey, TElement> stellen auch Benachrichtigungen bereit, wenn Elemente (in diesem Fall Gruppen) hinzugefügt, entfernt oder geändert werden.
Sie implementieren die Schnittstelle, um die ILookup<TKey, TElement> LINQ-Interoperabilität zu verbessern.
Sie bieten zusätzliche Hilfsmethoden für die einfache Interaktion mit Gruppen und Elementen in dieser Auflistung über alle APIs des ObservableGroupedCollectionExtensions-Typs.

Funktioniert mit `ObservableGroupedCollection<TKey, TElement>`

Angenommen, wir hatten eine einfache Definition eines Contact-Modells wie folgt:

public sealed record Contact(Name Name, string Email, Picture Picture);

public sealed record Name(string First, string Last)
{
    public override string ToString() => $"{First} {Last}";
}

public sealed record Picture(string Url);

Und dann ein Ansichtsmodell, das zum Einrichten einer Liste von Kontakten verwendet ObservableGroupedCollection<TKey, TElement> wird:

public class ContactsViewModel : ObservableObject
{
    /// <summary>
    /// The <see cref="IContactsService"/> instance currently in use.
    /// </summary>
    private readonly IContactsService contactsService;

    public ContactsViewModel(IContactsService contactsService) 
    {
        this.contactsService = contactsService;

        LoadContactsCommand = new AsyncRelayCommand(LoadContactsAsync);
    }

    public IAsyncRelayCommand LoadContactsCommand { get; }

    /// <summary>
    /// Gets the current collection of contacts
    /// </summary>
    public ObservableGroupedCollection<string, Contact> Contacts { get; private set; } = new();

    /// <summary>
    /// Loads the contacts to display.
    /// </summary>
    private async Task LoadContactsAsync()
    {
        var contacts = await contactsService.GetContactsAsync();

        Contacts = new ObservableGroupedCollection<string, Contact>(
            contacts.Contacts
            .GroupBy(static c => char.ToUpperInvariant(c.Name.First[0]).ToString())
            .OrderBy(static g => g.Key));

        OnPropertyChanged(nameof(Contacts));
    }
}

Und die relative Benutzeroberfläche könnte dann sein (mit WinUI XAML):

<UserControl
    x:Class="MvvmSampleUwp.Views.ContactsView"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:collections="using:CommunityToolkit.Mvvm.Collections"
    xmlns:contacts="using:MvvmSample.Core.Models"
    xmlns:core="using:Microsoft.Xaml.Interactions.Core"
    xmlns:interactivity="using:Microsoft.Xaml.Interactivity"
    xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
    xmlns:system="using:System"
    NavigationCacheMode="Enabled">
    <Page.Resources>

        <!--  SemanticZoom grouped source (this connects the grouped collection to the UI)  -->
        <CollectionViewSource
            x:Name="PeopleViewSource"
            IsSourceGrouped="True"
            Source="{x:Bind ViewModel.Contacts, Mode=OneWay}" />

        <!--  Contact template  -->
        <DataTemplate x:Key="PersonListViewTemplate" x:DataType="contacts:Contact">

            <!-- Some custom template here -->
        </DataTemplate>
    </Page.Resources>

    <!--  A command to load contacts when the control is loaded in the visual tree  -->
    <interactivity:Interaction.Behaviors>
        <core:EventTriggerBehavior EventName="Loaded">
            <core:InvokeCommandAction Command="{x:Bind ViewModel.LoadContactsCommand}" />
        </core:EventTriggerBehavior>
    </interactivity:Interaction.Behaviors>

    <Grid>

        <!--  Loading bar (is displayed when the contacts are loading)  -->
        <muxc:ProgressBar
            HorizontalAlignment="Stretch"
            VerticalAlignment="Top"
            Background="Transparent"
            IsIndeterminate="{x:Bind ViewModel.LoadContactsCommand.IsRunning, Mode=OneWay}" />

        <!--  Contacts view  -->
        <SemanticZoom>
            <SemanticZoom.ZoomedInView>
                <ListView
                    ItemTemplate="{StaticResource PersonListViewTemplate}"
                    ItemsSource="{x:Bind PeopleViewSource.View, Mode=OneWay}"
                    SelectionMode="Single">
                    <ListView.GroupStyle>
                        <GroupStyle HidesIfEmpty="True">

                            <!--  Header template (you can see IReadOnlyObservableGroup being used here)  -->
                            <GroupStyle.HeaderTemplate>
                                <DataTemplate x:DataType="collections:IReadOnlyObservableGroup">
                                    <TextBlock
                                        FontSize="24"
                                        Foreground="{ThemeResource SystemControlHighlightAccentBrush}"
                                        Text="{x:Bind Key}" />
                                </DataTemplate>
                            </GroupStyle.HeaderTemplate>
                        </GroupStyle>
                    </ListView.GroupStyle>
                </ListView>
            </SemanticZoom.ZoomedInView>
            <SemanticZoom.ZoomedOutView>
                <GridView
                    HorizontalAlignment="Stretch"
                    ItemsSource="{x:Bind PeopleViewSource.View.CollectionGroups, Mode=OneWay}"
                    SelectionMode="Single">
                    <GridView.ItemTemplate>

                        <!--  Zoomed out header template (IReadOnlyObservableGroup is used again)  -->
                        <DataTemplate x:DataType="ICollectionViewGroup">
                            <Border Width="80" Height="80">
                                <TextBlock
                                    HorizontalAlignment="Center"
                                    VerticalAlignment="Center"
                                    FontSize="32"
                                    Foreground="{ThemeResource SystemControlHighlightAccentBrush}"
                                    Text="{x:Bind Group.(collections:IReadOnlyObservableGroup.Key)}" />
                            </Border>
                        </DataTemplate>
                    </GridView.ItemTemplate>
                </GridView>
            </SemanticZoom.ZoomedOutView>
        </SemanticZoom>
    </Grid>
</UserControl>

Dadurch würde eine gruppierte Liste von Kontakten angezeigt, wobei jede Gruppe die Initiale ihrer enthaltenen Kontakte als Titel verwendet.

Wenn der Codeausschnitt ausgeführt wird, führt der obige Codeausschnitt zur folgenden Benutzeroberfläche aus der MVVM-Toolkit-Beispiel-App:

Beispiel für die Ansicht „Kontakte“

Beispiele

Sehen Sie sich die Beispiel-App (für mehrere Benutzeroberflächen-Frameworks) an, um das MVVM-Toolkit in Aktion zu sehen.
Weitere Beispiele finden Sie auch in den Komponententests.

Freigeben über