Komponent ASP.NET Core BlazorQuickGrid

• Określ tagi składnika QuickGrid w Razor znaczniku (<QuickGrid>...</QuickGrid>).
• Nadaj siatce nazwę możliwe do utworzenia zapytania źródło danych. Użyj jednego z następujących źródeł danych:
  • Items: dopuszczana IQueryable<TGridItem>wartość null , gdzie TGridItem jest typem danych reprezentowanych przez każdy wiersz w siatce.
  • ItemsProvider: wywołanie zwrotne, które dostarcza dane dla siatki.
• QueryParameterNameOptions: Określa nazwy parametrów ciągu zapytania, które utrwalają kolumnę sortowania siatki, kierunek sortowania i numer strony w adresie URL. Wartość domyślna to wystąpienie, które powoduje wyświetlenie parametrów zapytania o nazwach "sort", "direction" i "page". Przypisywanie unikatowych nazw do tych parametrów ciągu zapytania umożliwia używanie wielu QuickGrid składników na tej samej stronie bez konfliktów parametrów adresu URL ze sobą. Aby uzyskać więcej informacji, zobacz sekcje tryby stronicowania, nazwy parametrów zapytania i wiele siatek na tej samej stronie.
• Class: opcjonalna nazwa klasy CSS. Jeśli zostanie podana, nazwa klasy jest uwzględniona w atrybucie class renderowanej tabeli.
• Theme: Nazwa motywu (wartość domyślna: default). Ma to wpływ na to, które reguły stylu pasują do tabeli.
• Virtualize: Jeśli true, siatka jest renderowana przy użyciu wirtualizacji. Jest to zwykle używane w połączeniu z przewijaniem i umożliwia pobranie oraz renderowanie tylko danych wokół obszaru przewijanego widoku. Może to znacznie poprawić wydajność podczas przewijania dużych zestawów danych. Jeśli używasz Virtualize, należy podać wartość dla ItemSize i upewnić się, że każdy wiersz jest renderowany ze stałą wysokością. Ogólnie rzecz biorąc, zaleca się nie używać Virtualize , jeśli ilość renderowanych danych jest mała lub jeśli używasz stronicowania.
• ItemSize: dotyczy tylko podczas korzystania z Virtualize. ItemSize definiuje oczekiwaną wysokość w pikselach dla każdego wiersza, umożliwiając mechanizmowi wirtualizacji pobranie prawidłowej liczby elementów odpowiadających rozmiarowi wyświetlania i zapewnienie dokładnego przewijania.
• ItemKey: Opcjonalnie definiuje wartość dla @key każdego renderowanego wiersza. Zazwyczaj służy do określania unikatowego identyfikatora, takiego jak wartość klucza podstawowego, dla każdego elementu danych. Dzięki temu siatka może zachować skojarzenie między elementami wierszy a elementami danych na podstawie ich unikalnych identyfikatorów, nawet jeśli TGridItem wystąpienia są zastępowane przez nowe kopie (na przykład po nowym zapytaniu względem bazowego magazynu danych). Jeśli @key nie jest ustawiona, to jest instancja TGridItem.
• OverscanCount: definiuje liczbę dodatkowych elementów do renderowania przed i po widocznym regionie w celu zmniejszenia częstotliwości renderowania podczas przewijania. Chociaż wyższe wartości mogą poprawić płynność przewijania przez renderowanie większej liczby elementów poza ekranem, wyższa wartość może również spowodować wzrost początkowych czasów ładowania. Zalecane jest znalezienie równowagi na podstawie rozmiaru zestawu danych i wymagań dotyczących środowiska użytkownika. Domyślna wartość to 3. Dostępne tylko w przypadku korzystania z programu Virtualize.
• InitialItemIndex: dotyczy tylko podczas korzystania z Virtualize. Przewija siatkę do podanego indeksu wiersza liczonego od zera podczas pierwszego renderowania interaktywnego. Wartość jest stosowana jednokrotnie i ograniczana do dopuszczalnego zakresu. To przekierowuje do wewnętrznego składnika Virtualize. Aby uzyskać więcej informacji, zobacz wirtualizację komponentów w ASP.NET Core.
• ScrollToItemAsync: dotyczy tylko podczas korzystania z Virtualize. Programowo przewija siatkę do wiersza o podanym indeksie liczonym od zera, tak aby znalazł się u góry. Ostatnie wywołanie wygrywa, a metoda zgłasza InvalidOperationException błąd, gdy wirtualizacja jest wyłączona lub siatka nie jest jeszcze renderowana. To przekierowuje do wewnętrznego składnika Virtualize. Aby uzyskać więcej informacji, zobacz wirtualizację komponentów w ASP.NET Core.
• AnchorMode: dotyczy tylko podczas korzystania z Virtualize. Określa sposób działania widoku na krawędziach listy, gdy elementy są dodawane dynamicznie (ustawienie domyślne: Start). Jest to eksperymentalny interfejs API, który wymaga włączenia diagnostyki ASP0030 i przekazuje dalej do wewnętrznego składnika Virtualize. Aby uzyskać więcej informacji, zobacz wirtualizację komponentów w ASP.NET Core.
• ItemComparer: dotyczy tylko podczas korzystania z Virtualize. Komparator używany do wykrywania, czy elementy zostały dodane na początku czy na końcu między kolejnymi załadowaniami danych, co jest przydatne w przypadku elementów typu klasowego dostarczanych przez element ItemsProvider. Jest to eksperymentalny interfejs API, który wymaga włączenia diagnostyki ASP0030 i przekazuje dalej do wewnętrznego składnika Virtualize. Aby uzyskać więcej informacji, zobacz wirtualizację komponentów w ASP.NET Core.
• Pagination: opcjonalnie łączy to wystąpienie TGridItem z modelem PaginationState, poprzez co siatka pobiera i renderuje tylko bieżącą stronę danych. Jest to zwykle używane w połączeniu ze składnikiem Paginator lub inną logiką interfejsu użytkownika, która wyświetla i aktualizuje podane wystąpienie PaginationState. PaginationState Zawiera interfejs API umożliwiający interakcję z bieżącym indeksem stron opartym na zera, liczbą elementów na każdej stronie, indeksem zerowym ostatniej strony oraz całkowitą liczbą elementów na wszystkich stronach.
• W treści podrzędnej QuickGrid (RenderFragment) określ elementy PropertyColumn<TGridItem,TProp>, reprezentujące kolumny TGridItem, których komórki wyświetlają wartości:
  • Property: definiuje wartość, która ma być wyświetlana w komórkach tej kolumny.
  • Format: opcjonalnie określa ciąg formatu dla wartości. Użycie Format wymaga, aby typ TProp implementował IFormattable.
  • Sortable: wskazuje, czy dane powinny być sortowalne według tej kolumny. Wartość domyślna może się różnić w zależności od typu kolumny. Na przykład element TemplateColumn<TGridItem> jest sortowany, jeśli określono jakikolwiek SortBy parametr.
  • InitialSortDirection: wskazuje kierunek sortowania, jeśli IsDefaultSortColumn ma wartość true.
  • IsDefaultSortColumn: wskazuje, czy ta kolumna ma być sortowana domyślnie.
  • PlaceholderTemplate: Jeśli określono, zwirtualizowane siatki używają tego szablonu do renderowania komórek, których dane nie zostały załadowane.
  • HeaderTemplate: opcjonalny szablon komórki nagłówka tej kolumny. Jeśli nie zostanie określony, domyślny szablon nagłówka zawiera element Title, wraz z odpowiednimi wskaźnikami sortowania i przyciskami opcji.
  • Title: tekst tytułu kolumny. Tytuł jest renderowany automatycznie, jeśli HeaderTemplate nie jest używany.

• Określ tagi składnika QuickGrid w Razor znaczniku (<QuickGrid>...</QuickGrid>).
• Nadaj siatce nazwę możliwe do utworzenia zapytania źródło danych. Użyj jednego z następujących źródeł danych:
  • Items: dopuszczana IQueryable<TGridItem>wartość null , gdzie TGridItem jest typem danych reprezentowanych przez każdy wiersz w siatce.
  • ItemsProvider: wywołanie zwrotne, które dostarcza dane dla siatki.
• Class: opcjonalna nazwa klasy CSS. Jeśli zostanie podana, nazwa klasy jest uwzględniona w atrybucie class renderowanej tabeli.
• Theme: Nazwa motywu (wartość domyślna: default). Ma to wpływ na to, które reguły stylu pasują do tabeli.
• Virtualize: Jeśli true, siatka jest renderowana przy użyciu wirtualizacji. Jest to zwykle używane w połączeniu z przewijaniem i umożliwia pobranie oraz renderowanie tylko danych wokół obszaru przewijanego widoku. Może to znacznie poprawić wydajność podczas przewijania dużych zestawów danych. Jeśli używasz Virtualize, należy podać wartość dla ItemSize i upewnić się, że każdy wiersz jest renderowany ze stałą wysokością. Ogólnie rzecz biorąc, zaleca się nie używać Virtualize , jeśli ilość renderowanych danych jest mała lub jeśli używasz stronicowania.
• ItemSize: dotyczy tylko podczas korzystania z Virtualize. ItemSize definiuje oczekiwaną wysokość w pikselach dla każdego wiersza, umożliwiając mechanizmowi wirtualizacji pobranie prawidłowej liczby elementów odpowiadających rozmiarowi wyświetlania i zapewnienie dokładnego przewijania.
• ItemKey: Opcjonalnie definiuje wartość dla @key każdego renderowanego wiersza. Zazwyczaj służy do określania unikatowego identyfikatora, takiego jak wartość klucza podstawowego, dla każdego elementu danych. Dzięki temu siatka może zachować skojarzenie między elementami wierszy a elementami danych na podstawie ich unikalnych identyfikatorów, nawet jeśli TGridItem wystąpienia są zastępowane przez nowe kopie (na przykład po nowym zapytaniu względem bazowego magazynu danych). Jeśli @key nie jest ustawiona, to jest instancja TGridItem.
• OverscanCount: definiuje liczbę dodatkowych elementów do renderowania przed i po widocznym regionie w celu zmniejszenia częstotliwości renderowania podczas przewijania. Chociaż wyższe wartości mogą poprawić płynność przewijania przez renderowanie większej liczby elementów poza ekranem, wyższa wartość może również spowodować wzrost początkowych czasów ładowania. Zalecane jest znalezienie równowagi na podstawie rozmiaru zestawu danych i wymagań dotyczących środowiska użytkownika. Domyślna wartość to 3. Dostępne tylko w przypadku korzystania z programu Virtualize.
• Pagination: opcjonalnie łączy to wystąpienie TGridItem z modelem PaginationState, poprzez co siatka pobiera i renderuje tylko bieżącą stronę danych. Jest to zwykle używane w połączeniu ze składnikiem Paginator lub inną logiką interfejsu użytkownika, która wyświetla i aktualizuje podane wystąpienie PaginationState. PaginationState Zawiera interfejs API umożliwiający interakcję z bieżącym indeksem stron opartym na zera, liczbą elementów na każdej stronie, indeksem zerowym ostatniej strony oraz całkowitą liczbą elementów na wszystkich stronach.
• W treści podrzędnej QuickGrid (RenderFragment) określ elementy PropertyColumn<TGridItem,TProp>, reprezentujące kolumny TGridItem, których komórki wyświetlają wartości:
  • Property: definiuje wartość, która ma być wyświetlana w komórkach tej kolumny.
  • Format: opcjonalnie określa ciąg formatu dla wartości. Użycie Format wymaga, aby typ TProp implementował IFormattable.
  • Sortable: wskazuje, czy dane powinny być sortowalne według tej kolumny. Wartość domyślna może się różnić w zależności od typu kolumny. Na przykład element TemplateColumn<TGridItem> jest sortowany, jeśli określono jakikolwiek SortBy parametr.
  • InitialSortDirection: wskazuje kierunek sortowania, jeśli IsDefaultSortColumn ma wartość true.
  • IsDefaultSortColumn: wskazuje, czy ta kolumna ma być sortowana domyślnie.
  • PlaceholderTemplate: Jeśli określono, zwirtualizowane siatki używają tego szablonu do renderowania komórek, których dane nie zostały załadowane.
  • HeaderTemplate: opcjonalny szablon komórki nagłówka tej kolumny. Jeśli nie zostanie określony, domyślny szablon nagłówka zawiera element Title, wraz z odpowiednimi wskaźnikami sortowania i przyciskami opcji.
  • Title: tekst tytułu kolumny. Tytuł jest renderowany automatycznie, jeśli HeaderTemplate nie jest używany.

• Określ tagi składnika QuickGrid w Razor znaczniku (<QuickGrid>...</QuickGrid>).
• Nadaj siatce nazwę możliwe do utworzenia zapytania źródło danych. Użyj jednego z następujących źródeł danych:
  • Items: dopuszczana IQueryable<TGridItem>wartość null , gdzie TGridItem jest typem danych reprezentowanych przez każdy wiersz w siatce.
  • ItemsProvider: wywołanie zwrotne, które dostarcza dane dla siatki.
• Class: opcjonalna nazwa klasy CSS. Jeśli zostanie podana, nazwa klasy jest uwzględniona w atrybucie class renderowanej tabeli.
• Theme: Nazwa motywu (wartość domyślna: default). Ma to wpływ na to, które reguły stylu pasują do tabeli.
• Virtualize: Jeśli true, siatka jest renderowana przy użyciu wirtualizacji. Jest to zwykle używane w połączeniu z przewijaniem i umożliwia pobranie oraz renderowanie tylko danych wokół obszaru przewijanego widoku. Może to znacznie poprawić wydajność podczas przewijania dużych zestawów danych. Jeśli używasz Virtualize, należy podać wartość dla ItemSize i upewnić się, że każdy wiersz jest renderowany ze stałą wysokością. Ogólnie rzecz biorąc, zaleca się nie używać Virtualize , jeśli ilość renderowanych danych jest mała lub jeśli używasz stronicowania.
• ItemSize: dotyczy tylko podczas korzystania z Virtualize. ItemSize definiuje oczekiwaną wysokość w pikselach dla każdego wiersza, umożliwiając mechanizmowi wirtualizacji pobranie prawidłowej liczby elementów odpowiadających rozmiarowi wyświetlania i zapewnienie dokładnego przewijania.
• ItemKey: Opcjonalnie definiuje wartość dla @key każdego renderowanego wiersza. Zazwyczaj służy do określania unikatowego identyfikatora, takiego jak wartość klucza podstawowego, dla każdego elementu danych. Dzięki temu siatka może zachować skojarzenie między elementami wierszy a elementami danych na podstawie ich unikalnych identyfikatorów, nawet jeśli TGridItem wystąpienia są zastępowane przez nowe kopie (na przykład po nowym zapytaniu względem bazowego magazynu danych). Jeśli @key nie jest ustawiona, to jest instancja TGridItem.
• Pagination: opcjonalnie łączy to wystąpienie TGridItem z modelem PaginationState, poprzez co siatka pobiera i renderuje tylko bieżącą stronę danych. Jest to zwykle używane w połączeniu ze składnikiem Paginator lub inną logiką interfejsu użytkownika, która wyświetla i aktualizuje podane wystąpienie PaginationState. PaginationState Zawiera interfejs API umożliwiający interakcję z bieżącym indeksem stron opartym na zera, liczbą elementów na każdej stronie, indeksem zerowym ostatniej strony oraz całkowitą liczbą elementów na wszystkich stronach.
• W treści podrzędnej QuickGrid (RenderFragment) określ elementy PropertyColumn<TGridItem,TProp>, reprezentujące kolumny TGridItem, których komórki wyświetlają wartości:
  • Property: definiuje wartość, która ma być wyświetlana w komórkach tej kolumny.
  • Format: opcjonalnie określa ciąg formatu dla wartości. Użycie Format wymaga, aby typ TProp implementował IFormattable.
  • Sortable: wskazuje, czy dane powinny być sortowalne według tej kolumny. Wartość domyślna może się różnić w zależności od typu kolumny. Na przykład element TemplateColumn<TGridItem> jest sortowany, jeśli określono jakikolwiek SortBy parametr.
  • InitialSortDirection: wskazuje kierunek sortowania, jeśli IsDefaultSortColumn ma wartość true.
  • IsDefaultSortColumn: wskazuje, czy ta kolumna ma być sortowana domyślnie.
  • PlaceholderTemplate: Jeśli określono, zwirtualizowane siatki używają tego szablonu do renderowania komórek, których dane nie zostały załadowane.
  • HeaderTemplate: opcjonalny szablon komórki nagłówka tej kolumny. Jeśli nie zostanie określony, domyślny szablon nagłówka zawiera element Title, wraz z odpowiednimi wskaźnikami sortowania i przyciskami opcji.
  • Title: tekst tytułu kolumny. Tytuł jest renderowany automatycznie, jeśli HeaderTemplate nie jest używany.

W przypadku komponent musi przyjąć interaktywny tryb renderowania aby włączyć funkcje interaktywne, takie jak stronicowanie i sortowanie.

@page "/promotion-grid"
@using Microsoft.AspNetCore.Components.QuickGrid

<PageTitle>Promotion Grid</PageTitle>

<h1>Promotion Grid Example</h1>

<QuickGrid Items="people">
    <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
    private record Person(int PersonId, string Name, DateOnly PromotionDate);

    private IQueryable<Person> people = new[]
    {
        new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
        new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
        new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
        new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
        new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
        new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
    }.AsQueryable();
}

@page "/promotion-grid"
@using Microsoft.AspNetCore.Components.QuickGrid

<PageTitle>Promotion Grid</PageTitle>

<h1>Promotion Grid Example</h1>

<QuickGrid Items="people">
    <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
    private record Person(int PersonId, string Name, DateOnly PromotionDate);

    private IQueryable<Person> people = new[]
    {
        new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
        new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
        new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
        new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
        new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
        new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
    }.AsQueryable();
}

Składnik QuickGrid może stronicować dane ze źródła danych.

Składnik QuickGrid może stronicować dane ze źródła danych. W Blazor Web App wymaga się, aby przy stronicowaniu składnik przyjął tryb renderowania interakcyjnego.

Aby zapewnić interfejs użytkownika do stronicowania, dodaj składnik Paginator powyżej, poniżej lub zarówno powyżej, jak i poniżej składnika QuickGrid. Ustaw Paginator.State na pagination.

Aby udostępnić interfejs użytkownika na potrzeby stronicowania, dodaj Paginator składnik powyżej lub poniżej QuickGrid składnika. Ustaw Paginator.State na pagination.

QuickGrid renderuje dodatkowe puste wiersze, aby wypełnić ostatnią stronę danych w przypadku użycia ze składnikiem Paginator. W .NET 9 lub nowszych puste komórki danych (<td></td>) są dodawane do pustych wierszy. Puste wiersze służą ułatwieniu renderowania QuickGrid z zachowaniem stabilnej wysokości wierszy i stylizacji na wszystkich stronach.

GetPageUrl Zwraca adres URL z numerem strony liczonym od 1. Indeks strony 0 (strona 1) pomija całkowicie parametr zapytania.

QuickGrid Obsługuje nawigację opartą na adresach URL z podziałem na strony i stan sortowania utrwalone przez ciąg zapytania adresu URL. Gdy użytkownicy stronicują lub sortują, adres URL zostanie zaktualizowany (na przykład: ?page=2&sort=Name&direction=asc). Umożliwia to udostępnianie linków, powrót/przekierowanie przeglądarki i statyczne usługi SSR bez interakcyjności.

Sortowalne nagłówki kolumn i kontrolki paginatora są renderowane jako <a> elementy z atrybutami href . Linki obsługują standardowe zachowanie przeglądarki, takie jak otwieranie strony w nowej karcie lub oknie. Element StaticHtmlRenderer renderuje te kotwice. Na każdym żądaniu serwer odczytuje ciąg zapytania w celu określenia bieżącej strony i stanu sortowania — nie jest wymagane środowisko uruchomieniowe języka JavaScript.

Parametry ciągu zapytania:

• page: Numer strony liczony od 1. Pierwsza strona pomija parametr dla czystych adresów URL.
• sort: tytuł kolumny do sortowania siatki.
• direction: Rosnąco (asc) lub malejąco (desc).

page Jeśli wartość jest źle sformułowana, zero lub ujemna, QuickGrid wyświetla pierwszą stronę. Jeśli wartość jest większa niż liczba dostępnych stron, QuickGrid zostanie wyświetlona ostatnia strona. To zachowanie obowiązuje, gdy siatka odbiera dane z elementu Items lub ItemsProvider. ItemsProvider musi zwracać dokładną łączną liczbę elementów, aby QuickGrid mogło prawidłowo określić ostatnią stronę.

Zmień nazwę poprzednich parametrów ciągu zapytania za pomocą parametru QueryParameterNameOptions . Aby uzyskać więcej informacji, zobacz sekcję Nazwy parametrów zapytania .

Kolumna sort jest identyfikowana przez właściwość kolumny Title . Kolumny bez elementu Title renderują nieklikalny nagłówek <div>.

QuickGrid odczytuje adres URL podczas inicjalizacji i subskrybuje NavigationManager.LocationChanged, dzięki czemu działają przyciski Wstecz/Dalej w przeglądarce oraz bezpośrednie wpisanie adresu URL. Po usunięciu parametrów sortowania z adresu URL zostanie on przywrócony do domyślnej kolumny sortowania/kierunku.

Stronicowanie i stan sortowania są zarządzane w pamięci wewnątrz komponentu QuickGrid bez zmiany adresu URL, co nazywa się nawigacją opartą na stanie wewnętrznym. Wymagany jest tryb renderowania interakcyjnego.

Aby wyłączyć nawigację opartą na adresach URL, ustaw przełącznik AppContext tej funkcji na false:

AppContext.SetSwitch(
    "Microsoft.AspNetCore.Components.QuickGrid.EnableUrlBasedQuickGridNavigationAndSorting",
    false);

Spowoduje to przywrócenie <button> elementów za pomocą @onclick programów obsługi. Wymagany jest tryb renderowania interakcyjnego.

Przełącznik steruje tylko renderowanym elementem HTML (<a> zamiast <button>). Nawet wtedy, gdy jest wyłączony, QuickGrid nadal odczytuje i zapisuje stan do ciągu zapytania adresu URL wewnętrznie. SortByColumnAsync i Paginator.GoToPageAsync nawigują za pomocą NavigationManager.NavigateTo niezależnie od flagi.

Nazwy parametrów zapytania

Parametr QueryParameterNameOptionsQuickGrid składnika steruje nazwami parametrów ciągu zapytania, które utrwalają stan siatki w adresie URL. Klasa QueryParameterNameOptions ma trzy właściwości konfigurowalne:

• Sort: nazwa parametru ciągu zapytania, który zawiera kolumnę sortowania. Domyślna wartość to sort.
• Direction: nazwa parametru ciągu zapytania, który zawiera kierunek sortowania. Domyślna wartość to direction.
• Page: nazwa parametru ciągu zapytania, który zawiera numer strony. Domyślna wartość to page.

Parametr nigdy nie ma wartości null. Jeśli parametr nie jest ustawiony, komponent QuickGrid używa instancji utworzonej przez konstruktor bezparametrowy, w wyniku czego używane są domyślne nazwy z powyższej listy.

Konstruktor przyjmuje opcjonalny argument prefiksu, który jest poprzedzony wszystkimi trzema nazwami domyślnymi. Prefiks musi zawierać dowolny znak separatora, który ma być wyświetlany między prefiksem a nazwą. W poniższym przykładzie parametry ciągu zapytania mają nazwę products_sort, products_directioni products_page:

@using Microsoft.AspNetCore.Components.QuickGrid

<QuickGrid ... 
    QueryParameterNameOptions="@(new QueryParameterNameOptions("products_"))">
    ...
</QuickGrid>

Aby kontrolować nazwy indywidualnie, ustaw właściwości klasy. Zestaw właściwości jawnie ma pierwszeństwo przed prefiksem przekazanym do konstruktora, więc dwa podejścia można połączyć. W poniższym przykładzie parametry ciągu zapytania mają nazwy orderBy, orderDir i p:

@using Microsoft.AspNetCore.Components.QuickGrid

<QuickGrid ... QueryParameterNameOptions="@queryParameterNames">
    ...
</QuickGrid>

@code {
    private QueryParameterNameOptions queryParameterNames = new()
    {
        Sort = "orderBy",
        Direction = "orderDir",
        Page = "p"
    };
}

Nazwa parametru zapytania strony jest stosowana względem wystąpienia PaginationState przypisanego do parametru Pagination siatki, więc powiązany komponent Paginator automatycznie odczytuje i zapisuje tę samą nazwę parametru.

Wiele siatek na jednej stronie

Wiele QuickGrid składników na tej samej stronie wymaga unikatowych nazw parametrów zapytania, aby uniknąć konfliktów ciągu zapytania. Przypisz parametr QueryParameterNameOptions do wszystkich siatek z wyjątkiem jednej. Aby uzyskać więcej informacji, zobacz sekcję Nazwy parametrów zapytania .

Każdy QuickGrid musi mieć własną instancję PaginationState. Wiele siatek nie może współdzielić elementu PaginationState, jeśli używają różnych nazw parametrów zapytania — ostatnia renderowana siatka nadpisze nazwę parametru zapytania we współdzielonym stanie, co spowoduje, że Paginator będzie odczytywać dane z niewłaściwego parametru.

W poniższym przykładzie pierwszy QuickGrid używa domyślnych nazw parametrów zapytania, podczas gdy drugi używa prefiksu cities_ :

<QuickGrid ... Pagination="@pagination1">
    ...
</QuickGrid>

<Paginator State="pagination1" />

<QuickGrid ... Pagination="@pagination2" 
    QueryParameterNameOptions="@(new QueryParameterNameOptions("cities_"))">
    ...
</QuickGrid>

<Paginator State="pagination2" />

W następującym ciągu zapytania:

• Część page=2&sort=Name&direction=asc ma zastosowanie do pierwszego QuickGrid składnika.
• Część cities_page=3&cities_sort=Population&cities_direction=desc ma zastosowanie do drugiego QuickGrid składnika.

?page=2&sort=Name&direction=asc&cities_page=3&cities_sort=Population&cities_direction=desc

Zdarzenie kliknięcia wiersza (OnRowClick)

Komponent QuickGrid obsługuje zdarzenia kliknięcia wiersza za pomocą parametru OnRowClick. Po ustawieniu siatka automatycznie stosuje odpowiedni styl (wskaźnik kursora) i wywołuje wywołanie zwrotne za pomocą klikniętego elementu:

@using Microsoft.AspNetCore.Components.QuickGrid
@inject NavigationManager NavigationManager

<QuickGrid Items="@people.AsQueryable()" 
    OnRowClick="@((Person args) => HandleRowClick(args))">
    <PropertyColumn Property="@(p => p.Name)" />
    <PropertyColumn Property="@(p => p.Email)" />
</QuickGrid>

@code {
    private List<Person> people = new()
    {
        new(1, "Alice Smith", "alice@example.com", "Engineering"),
        new(2, "Bob Johnson", "bob@example.com", "Marketing"),
        new(3, "Carol Williams", "carol@example.com", "Engineering"),
    };

    private void HandleRowClick(Person person)
    {
        NavigationManager.NavigateTo($"/person/{person.Id}");
    }

    private record Person(int Id, string Name, string Email, string Department);
}

Ta funkcja zawiera wbudowane style CSS, które za pomocą klasy CSS row-clickable ustawiają kursor wskaźnika dla klikalnych wierszy, zapewniając użytkownikom wyraźną informację wizualną. Klasa jest stosowana do elementu tr każdego wiersza danych, gdy ustawiono OnRowClick, i jest łączona z każdą klasą zwracaną przez parametr RowClass.

Propagacja zdarzeń z interaktywnej treści komórki

Procedura obsługi kliknięcia wiersza jest zarejestrowana na elemencie tr wiersza, więc kliknięcie elementu interaktywnego wewnątrz komórki, takiego jak przycisk, pole wyboru lub łącze, jest propagowane w górę i powoduje również wywołanie OnRowClick. Aby uruchomić tylko własny program obsługi kontrolki, zatrzymaj propagację w kontrolce, używając atrybutu dyrektywy @onclick:stopPropagation:

<QuickGrid Items="@people.AsQueryable()" 
    OnRowClick="@((Person args) => HandleRowClick(args))">
    <PropertyColumn Property="@(p => p.Name)" />
    <TemplateColumn Title="Actions">
        <button @onclick="@(() => Delete(context))" 
            @onclick:stopPropagation="true">
            Delete
        </button>
    </TemplateColumn>
</QuickGrid>

Accessibility

OnRowClick jest wygodą opartą na wskaźniku. Zgodnie z projektem nie zmienia semantyki tabeli siatki, więc wiersze nie otrzymują fokusu klawiatury, nie reagują na klawisz Enter lub Spacja i nie są ogłaszane jako interaktywne przez technologie pomocnicze. Uczynienie wiersza elementem, który może otrzymać fokus za pomocą tabindex i role="button", nie jest obsługiwanym obejściem, ponieważ narusza semantykę tabeli, na której polegają technologie wspomagające, aby poruszać się po siatce.

Traktuj kliknięcie wiersza jako skrót dla użytkowników wskaźnika, a nie jedyną ścieżkę do akcji. Dla każdej akcji uruchamianej przez kliknięcie wiersza zapewnij w komórce element sterujący dostępny z klawiatury, na przykład przycisk lub łącze:

<TemplateColumn Title="Details">
    <a href="@($"/person/{context.Id}")">View</a>
</TemplateColumn>

Składnik QuickGrid może sortować elementy według kolumn. Wybranie nagłówka powoduje przejście do adresu URL ze zaktualizowanymi parametrami sort i direction. SortByColumnAsync przechodzi przez metodę NavigationManager.NavigateTo(GetSortQueryStringUrl(...)), więc adres URL zawsze odzwierciedla stan sortowania.

Składnik QuickGrid może sortować elementy według kolumn. W Blazor Web App sortowanie wymaga, aby składnik przyjął tryb renderowania interaktywnego.

Stan sortowania w adresie URL używa właściwości kolumny Title jako identyfikatora. Parametr zapytania sort jest ustawiony na column.Title (na przykład dla tytułu kolumny Name: ?sort=Name&direction=asc). Po zmianie adresu URL element QuickGrid dopasowuje wartość sort z powrotem do kolumny, wykonując _columns.FirstOrDefault(c => c.Title == sort.ColumnTitle). Jeśli żaden tytuł kolumny nie jest zgodny, sortowanie jest ignorowane, a siatka wraca do domyślnego sortowania.

Zmiana nazwy kolumny Title to zmiana powodująca niezgodność adresów URL. Wszystkie zakładki lub udostępnione adresy URL zawierające stary tytuł w parametrze sort przestają pasować, a siatka dyskretnie wraca do domyślnego sortowania zamiast sortowania według zamierzonej kolumny. W przypadku PropertyColumn parametr Title domyślnie przyjmuje nazwę właściwości (na przykład: Property="@(p => p.FirstName)" daje Title="First Name"), więc zarówno zmiana nazwy właściwości, jak i jawne ustawienie parametru Title powodują, że istniejące adresy URL przestają działać.

Komponent z paginacją QuickGrid może otworzyć stronę szczegółów rekordu i wrócić do właściwej strony wyników, korzystając z podejścia opisanego w tej sekcji. Nawigacja oparta na adresach URL służy do zapisywania numeru strony i zwracania użytkownika do tej samej strony elementów ze strony szczegółów.

Komponent z paginacją QuickGrid może otworzyć stronę szczegółów rekordu i wrócić do właściwej strony wyników, korzystając z podejścia opisanego w tej sekcji.

Używany jest następujący interfejs API:

• PaginationState.CurrentPageIndex: Pobiera bieżący indeks strony oparty na zerach.
• PaginationState.SetCurrentPageIndexAsync: Ustawia bieżący indeks strony i powiadamia wszystkie powiązane komponenty QuickGrid, aby pobrały i wyrenderowały zaktualizowane dane.

• Automatycznie ustawia stronicowanie składnika podczas inicjalizacji składnika QuickGrid przy użyciu nawigacji opartej na adresie URL, która ustawia indeks strony na podstawie wartości parametru page ciągu zapytania, jeśli istnieje.
• Otwiera poprzedzający komponent Details z bieżącym numerem strony, który jest równy bieżącemu indeksowi strony (CurrentPageIndex) powiększonemu o jeden, aby uzyskać indeks zaczynający się od 1 w parametrach zapytania. Indeks zaczynający się od 1 dla parametru ciągu zapytania page odpowiada renderowanemu w interfejsie użytkownika numerowi strony zaczynającemu się od 1 w renderowanym składniku Paginator.

ScifiCharacters.razor:

@page "/scifi-characters"
@using Microsoft.AspNetCore.Components.QuickGrid
@inject NavigationManager Navigation

<QuickGrid Items="characters" Pagination="pagination" 
    OnRowClick="@((Character args) => HandleRowClick(args))">
    <PropertyColumn Property="@(c => c.Id)" />
    <PropertyColumn Property="@(c => c.Name)" />
</QuickGrid>

<Paginator State="pagination" />

@code {
    PaginationState pagination = new PaginationState { ItemsPerPage = 3 };

    private record Character(int Id, string Name);

    private IQueryable<Character> characters = new[]
    {
        new Character(0, "Ellen Ripley"),
        new Character(1, "Darth Vader"),
        new Character(2, "Rick Deckard"),
        new Character(3, "Sarah Connor"),
        new Character(4, "Malcolm Reynolds"),
        new Character(5, "Kara Thrace"),
        new Character(6, "James Kirk"),
        new Character(7, "Flash Gordon"),
        new Character(8, "Max Rockatansky"),
        new Character(9, "Katniss Everdeen"),
        new Character(10, "Ellie Sattler"),
        new Character(11, "Leela")
    }.AsQueryable();

    private void HandleRowClick(Character character)
    {
        Navigation.NavigateTo(
            $"/details?id={character.Id}&page={pagination.CurrentPageIndex + 1}");
    }
}

Jeśli komponent QuickGrid ustawia QueryParameterNameOptions, ustaw klucz parametru w ciągu zapytania dla strony wyników w komponencie Details tak, aby odpowiadał właściwości Page opcji. W poniższym przykładzie do komponentu QuickGrid przypisano wystąpienie QueryParameterNameOptions z prefiksem scifi-characters-quickgrid_, co skutkuje utworzeniem parametru ciągu zapytania strony o nazwie scifi-characters-quickgrid_page.

W pliku Characters.razor:

<QuickGrid ... 
    QueryParameterNameOptions="@(new QueryParameterNameOptions("scifi-characters-quickgrid_"))">

W pliku Details.razor:

<a href="@($"/scifi-characters?scifi-characters-quickgrid_page={Page}")">Back to List</a>

AppContext.SetSwitch(
    "Microsoft.AspNetCore.Components.QuickGrid.EnableUrlBasedQuickGridNavigationAndSorting", 
    false);

• Ustawia stronicowanie komponentu QuickGrid przez wywołanie PaginationState.SetCurrentPageIndexAsync podczas inicjalizacji komponentu, ustawiając indeks strony na wartość Page (numer strony) minus jeden (-1). page Parametr ciągu zapytania jest usuwany po ustawieniu indeksu strony przy użyciu parametrów NavigateTo i GetUriWithQueryParameter.
• Otwiera poprzedzający komponent Details z bieżącym numerem strony, z indeksem strony zwiększonym o jeden (+1), aby wartość była indeksem liczonym od 1 (CurrentPageIndex) w ciągu zapytania. Indeks zaczynający się od 1 dla parametru ciągu zapytania page odpowiada renderowanemu w interfejsie użytkownika numerowi strony zaczynającemu się od 1 w renderowanym składniku Paginator.

ScifiCharacters.razor:

@page "/scifi-characters"
@rendermode InteractiveServer
@using Microsoft.AspNetCore.Components.QuickGrid
@inject NavigationManager Navigation

<QuickGrid Items="characters" Pagination="pagination">
    <PropertyColumn Property="@(c => c.Id)" />
    <PropertyColumn Property="@(c => c.Name)" />
    <TemplateColumn Context="c">
        <a href="@($"/details?id={c.Id}&page={pagination.CurrentPageIndex + 1}")">
            Details
        </a>
    </TemplateColumn>
</QuickGrid>

<Paginator State="pagination" />

@code {
    PaginationState pagination = new PaginationState { ItemsPerPage = 3 };

    private record Character(int Id, string Name);

    private IQueryable<Character> characters = new[]
    {
        new Character(0, "Ellen Ripley"),
        new Character(1, "Darth Vader"),
        new Character(2, "Rick Deckard"),
        new Character(3, "Sarah Connor"),
        new Character(4, "Malcolm Reynolds"),
        new Character(5, "Kara Thrace"),
        new Character(6, "James Kirk"),
        new Character(7, "Flash Gordon"),
        new Character(8, "Max Rockatansky"),
        new Character(9, "Katniss Everdeen"),
        new Character(10, "Ellie Sattler"),
        new Character(11, "Leela")
    }.AsQueryable();

    [SupplyParameterFromQuery]
    private int? Page { get; set; }

    protected override async Task OnInitializedAsync()
    {
        if (Page.HasValue && Page > 0)
        {
            await pagination.SetCurrentPageIndexAsync(Page.Value - 1);
            Navigation.NavigateTo(
                Navigation.GetUriWithQueryParameter("page", (int?)null));
        }
    }
}

Sformatuj wiersz tabeli na podstawie elementu wiersza

Zastosuj klasę arkusza stylów do wiersza siatki, wykorzystując do tego parametr RowClass, w zależności od elementu wiersza.

W poniższym przykładzie:

• Element wiersza jest reprezentowany przez rekord Person. Rekord Person zawiera właściwość FirstName.
• Metoda GetRowCssClass stosuje style klasy highlight-row do dowolnego wiersza, w którym imię osoby to "Julie".

<QuickGrid ... RowClass="GetRowCssClass">
    ...
</QuickGrid>

@code {
    private record Person(int PersonId, string FirstName, string LastName);

    private string GetRowCssClass(Person person) =>
        person.FirstName == "Julie" ? "highlight-row" : null;
}

Zamknij opcje kolumny QuickGrid

Zamknij interfejs użytkownika opcji kolumny QuickGrid za pomocą metody HideColumnOptionsAsync.

Poniższy przykład zamyka interfejs użytkownika opcji kolumn natychmiast po zastosowaniu filtru tytułu:

<QuickGrid @ref="movieGrid" Items="movies">
    <PropertyColumn Property="@(m => m.Title)" Title="Title">
        <ColumnOptions>
            <input type="search" @bind="titleFilter" placeholder="Filter by title" 
                @bind:after="@(() => movieGrid.HideColumnOptionsAsync())" />
        </ColumnOptions>
    </PropertyColumn>
    <PropertyColumn Property="@(m => m.Genre)" Title="Genre" />
    <PropertyColumn Property="@(m => m.ReleaseYear)" Title="Release Year" />
</QuickGrid>

@code {
    private QuickGrid<Movie>? movieGrid;
    private string titleFilter = string.Empty;
    private IQueryable<Movie> movies = new List<Movie> { ... }.AsQueryable();
    private IQueryable<Movie> filteredMovies => 
        movies.Where(m => m.Title!.Contains(titleFilter));
}