CollectionView

Przeglądaj przykład. Przeglądanie przykładu

Interfejs użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) CollectionView to widok przedstawiający listy danych przy użyciu różnych specyfikacji układu. Ma na celu zapewnienie bardziej elastycznej i wydajnej alternatywy dla ListView.

Poniższy zrzut ekranu przedstawia obiekt CollectionView, który używa dwukolumnowej pionowej siatki i umożliwia wielokrotny wybór.

Zrzut ekranu przedstawiający układ siatki pionowej CollectionView.

CollectionView należy użyć do prezentowania list danych, które wymagają przewijania lub zaznaczenia. Układ możliwy do powiązania może być używany, gdy wyświetlane dane nie wymagają przewijania ani zaznaczenia. Aby uzyskać więcej informacji, zobacz BindableLayout.

Uwaga / Notatka

W systemach iOS i Mac Catalyst zoptymalizowane programy obsługi, które były opcjonalne na platformie .NET 9, są domyślnymi procedurami obsługi na CollectionView platformie .NET 10, zapewniając lepszą wydajność i stabilność.

Przywracanie zachowania platformy .NET 9

Zalecamy użycie nowego obsługiwacza dla CollectionView, ale jeśli chcesz zrezygnować z tego zachowania i powrócić do obsługiwacza .NET 9, możesz użyć kodu poniżej w swoim MauiProgram.cs.

#if IOS || MACCATALYST
builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler>();
});
#endif

Migrowanie niestandardowych procedur obsługi w systemach iOS i Mac Catalyst

W .NET MAUI 11 starsze interfejsy API handlerów Apple w przestrzeni nazw Microsoft.Maui.Controls.Handlers.Items, w tym CollectionViewHandler, generują ostrzeżenia o przestarzałości w systemach iOS i Mac Catalyst. Sama kontrolka CollectionView nie jest przestarzała. Ostrzeżenia dotyczą starszych interfejsów API procedur obsługi, a nie każdego typu w przestrzeni nazw Items ani procedur obsługi na innych platformach.

Jeśli zarejestrowano starszy program obsługi tylko w celu przywrócenia zachowania .NET 9, usuń tę rejestrację, aby użyć domyślnego zoptymalizowanego programu obsługi. Aby zmienić jawną rejestrację na zoptymalizowaną procedurę obsługi, użyj:

#if IOS || MACCATALYST
builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2>();
});
#endif

W przypadku niestandardowej procedury obsługi należy dziedziczyć po Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2 zamiast przestarzałym CollectionViewHandler, a podklasę zarejestrować zamiast CollectionViewHandler2. Zaktualizuj dostosowania mapera, aby używać maperów zoptymalizowanego handlera. Starsze punkty rozszerzenia kontrolera, komórki i układu nie wszystkie mają bezpośredni odpowiednik 1:1. Dostosuj te niestandardowe dostosowania do programu obsługi Items2 oraz natywnych punktów rozszerzeń UICollectionViewLayout.

Rejestracja starszego modułu obsługi pozostaje dostępna jako tymczasowa rezygnacja z trybu zgodności podczas migracji. W .NET MAUI 11 ta rejestracja generuje przestarzałe ostrzeżenia w systemach iOS i Mac Catalyst.

Program obsługi CollectionView systemu Windows w platformie .NET 11

W środowisku .NET MAUI 11 system Windows domyślnie używa programu obsługi Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2 dla elementu CollectionView. Moduł obsługi jest sterowany za pomocą przełącznika Microsoft.Maui.RuntimeFeature.IsWindowsCollectionView2HandlerEnabledAppContext, który jest domyślnie włączony. Właściwość UseWindowsCollectionView2Handler MSBuild odpowiada temu przełącznikowi.

Ta procedura obsługi oparta na interfejsie WinUI ItemsRepeaterpoprawia zachowanie wirtualizacji i przewijania oraz dopasowuje architekturę Windows CollectionView do zoptymalizowanych procedur obsługi na innych platformach. Sposób wizualizacji zaznaczenia również różni się od starszego modułu obsługi systemu Windows: zaznaczone elementy są wyróżniane obramowaniem otaczającym element, a interfejs wielokrotnego zaznaczania różni się od poprzedniego modułu obsługi opartego na ListView.

Starszy Windows CollectionViewHandler i jego interfejsy API procedur obsługi pozostają obsługiwane i nie są przestarzałe w .NET MAUI 11.

Jeśli aplikacja zależy od starszego zachowania Windows CollectionView lub niestandardowych założeń dotyczących modułu obsługi, podczas migracji tymczasowo wyłącz tę funkcję, ustawiając właściwość MSBuild UseWindowsCollectionView2Handler na false w pliku projektu:

<PropertyGroup>
    <UseWindowsCollectionView2Handler>false</UseWindowsCollectionView2Handler>
</PropertyGroup>

Różnice między CollectionView i ListView

Chociaż interfejsy API CollectionView i ListView są podobne, istnieją pewne istotne różnice:

  • CollectionView ma elastyczny model układu, który umożliwia prezentowanie danych w pionie lub w poziomie na liście lub w siatce.
  • CollectionView obsługuje wybór pojedynczy i wielokrotny.
  • CollectionView nie ma pojęcia komórek. Zamiast tego szablon danych służy do definiowania wyglądu każdego elementu danych na liście.
  • CollectionView automatycznie wykorzystuje wirtualizację dostarczaną przez podstawowe kontrolki natywne.
  • CollectionView zmniejsza zakres interfejsu API ListView. Wiele właściwości i zdarzeń z ListView nie jest obecnych w CollectionView.
  • CollectionView nie zawiera wbudowanych separatorów.
  • CollectionView zgłosi wyjątek, jeśli ItemsSource zostanie zaktualizowany poza wątkiem interfejsu użytkownika.

Przechodzenie z widoku ListView do obiektu CollectionView

ListView implementacje można przenieść do CollectionView implementacji za pomocą tej tabeli:

Concept ListView API CollectionView
Dane ItemsSource Obiekt CollectionView jest wypełniany danymi, ustawiając jego ItemsSource właściwość. Aby uzyskać więcej informacji, zobacz Wypełnianie obiektu CollectionView danymi.
Wygląd elementu ItemTemplate Wygląd każdego elementu w obiekcie CollectionView można zdefiniować, ustawiając właściwość ItemTemplate na wartość DataTemplate. Aby uzyskać więcej informacji, zobacz Definiowanie wyglądu elementu.
Komórki TextCell ImageCell ViewCell CollectionView nie ma pojęcia komórek, a zatem nie ma pojęcia wskaźników ujawnienia. Zamiast tego szablon danych służy do definiowania wyglądu każdego elementu danych na liście.
Separatory wierszy SeparatorColor, SeparatorVisibility CollectionView nie zawiera wbudowanych separatorów. Można je podać w razie potrzeby w szablonie elementu.
Selekcja SelectionMode, SelectedItem CollectionView obsługuje wybór pojedynczy i wielokrotny. Aby uzyskać więcej informacji, zobacz Konfigurowanie wyboru elementu CollectionView.
Wysokość wiersza HasUnevenRows, RowHeight W elemencie CollectionView wysokość wiersza każdego elementu jest określana przez właściwość ItemSizingStrategy. Aby uzyskać więcej informacji, zobacz Ustalanie rozmiaru elementu.
Caching CachingStrategy CollectionView automatycznie używa wirtualizacji udostępnianej przez podstawowe kontrolki natywne.
Nagłówki i stopki Header, , HeaderElement, HeaderTemplate, Footer, , FooterElementFooterTemplate CollectionView może prezentować nagłówek i stopkę, które przewijają się wraz z elementami na liście za pośrednictwem właściwości Header, Footer, HeaderTemplate i FooterTemplate. Aby uzyskać więcej informacji, zobacz Nagłówki i stopki.
Grupowanie GroupDisplayBinding, , GroupHeaderTemplate, , GroupShortNameBindingIsGroupingEnabled CollectionView Wyświetla poprawnie zgrupowane dane, ustawiając jego IsGrouped właściwość na true. Nagłówki grup i stopki grup można dostosować, ustawiając właściwości GroupHeaderTemplate i GroupFooterTemplate na obiekty DataTemplate. Aby uzyskać więcej informacji, zobacz Wyświetlanie pogrupowanych danych w obiekcie CollectionView.
Przeciągnij, aby odświeżyć IsPullToRefreshEnabled, IsRefreshing, , RefreshAllowed, RefreshCommand, RefreshControlColor, , BeginRefresh()EndRefresh() Funkcja „przeciągnij, aby odświeżyć” jest obsługiwana przez ustawienie CollectionView jako element podrzędny RefreshView. Aby uzyskać więcej informacji, zobacz Przeciągnij, aby odświeżyć.
Elementy menu kontekstowego ContextActions Elementy menu kontekstowego są obsługiwane przez ustawienie SwipeView jako głównego widoku w DataTemplate, który definiuje wygląd każdego elementu danych w elemencie CollectionView. Aby uzyskać więcej informacji, zobacz Menu kontekstowe.
Przewijanie ScrollTo() CollectionView definiuje ScrollTo metody, które przewijają elementy do widoku. Aby uzyskać więcej informacji, zobacz Przewijanie kontrolki w kontrolce CollectionView.
  • Ostatnia aktualizacja o