komponen ASP.NET Core BlazorQuickGrid

Komponen QuickGrid adalah Razor komponen untuk menampilkan data dalam bentuk tabular dengan cepat dan efisien. QuickGrid menyediakan komponen kisi data yang sederhana dan nyaman untuk skenario penyajian kisi umum dan berfungsi sebagai arsitektur referensi dan garis besar performa untuk membangun komponen kisi data. QuickGrid sangat dioptimalkan dan menggunakan teknik canggih untuk mencapai performa penyajian yang optimal.

Paket

Tambahkan referensi paket untuk paket.Microsoft.AspNetCore.Components.QuickGrid

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Aplikasi sampel

Untuk berbagai QuickGrid demonstrasi, lihat QuickGrid untuk Blazor aplikasi sampel. Situs demo dihosting di Halaman GitHub. Situs ini dimuat dengan cepat berkat prarender statis menggunakan proyek GitHub yang dikelola BlazorWasmPrerendering.Build komunitas.

QuickGrid pelaksanaan

Untuk mengimplementasikan QuickGrid komponen:

• Tentukan tag untuk QuickGrid komponen dalam Razor markup (<QuickGrid>...</QuickGrid>).
• Beri nama sumber data yang dapat dikueri untuk kisi. Gunakan salah satu sumber data berikut:
  • Items: Nullable IQueryable<TGridItem>, di mana TGridItem adalah jenis data yang diwakili oleh setiap baris dalam kisi.
  • ItemsProvider: Panggilan balik yang menyediakan data untuk kisi.
• Class: Nama kelas CSS opsional. Jika disediakan, nama kelas disertakan dalam class atribut tabel yang dirender.
• Theme: Nama tema (nilai default: default). Ini memengaruhi aturan gaya mana yang cocok dengan tabel.
• Virtualize: Jika true, kisi dirender dengan virtualisasi. Ini biasanya digunakan bersama dengan pengguliran dan menyebabkan kisi mengambil dan merender hanya data di sekitar viewport gulir saat ini. Ini dapat sangat meningkatkan performa saat menggulir kumpulan data besar. Jika Anda menggunakan Virtualize, Anda harus menyediakan nilai untuk ItemSize dan harus memastikan bahwa setiap baris dirender dengan tinggi konstan. Umumnya, lebih baik tidak digunakan Virtualize jika jumlah data yang dirender kecil atau jika Anda menggunakan penomoran halaman.
• ItemSize: Hanya berlaku saat menggunakan Virtualize. ItemSize menentukan tinggi yang diharapkan dalam piksel untuk setiap baris, memungkinkan mekanisme virtualisasi untuk mengambil jumlah item yang benar agar sesuai dengan ukuran tampilan dan untuk memastikan pengguliran yang akurat.
• ItemKey: Secara opsional mendefinisikan nilai untuk @key pada setiap baris yang dirender. Biasanya, ini digunakan untuk menentukan pengidentifikasi unik, seperti nilai kunci utama, untuk setiap item data. Ini memungkinkan kisi untuk mempertahankan hubungan antara elemen baris dan item data berdasarkan pengidentifikasi uniknya, bahkan ketika TGridItem instans digantikan oleh salinan baru (misalnya, setelah kueri baru terhadap penyimpanan data yang mendasarinya). Jika tidak diatur, @key adalah TGridItem instansnya.
• Pagination: Secara opsional menautkan instans ini TGridItem dengan PaginationState model, menyebabkan kisi mengambil dan merender hanya halaman data saat ini. Ini biasanya digunakan bersama dengan Paginator komponen atau beberapa logika UI lain yang menampilkan dan memperbarui instans yang disediakan PaginationState .
• QuickGrid Dalam konten anak (RenderFragment), tentukan PropertyColumn<TGridItem,TProp>s, yang mewakili TGridItem kolom yang selnya menampilkan nilai:
  • Property: Menentukan nilai yang akan ditampilkan dalam sel kolom ini.
  • Format: Secara opsional menentukan string format untuk nilai . Menggunakan Format memerlukan TProp jenis untuk mengimplementasikan IFormattable.
  • Sortable: Menunjukkan apakah data harus dapat diurutkan berdasarkan kolom ini. Nilai default dapat bervariasi sesuai dengan jenis kolom. Misalnya, TemplateColumn<TGridItem> dapat diurutkan secara default jika ada SortBy parameter yang ditentukan.
  • InitialSortDirection: Menunjukkan arah pengurutan jika IsDefaultSortColumn adalah true.
  • IsDefaultSortColumn: Menunjukkan apakah kolom ini harus diurutkan secara default.
  • PlaceholderTemplate: Jika ditentukan, kisi virtual menggunakan templat ini untuk merender sel yang datanya belum dimuat.
  • HeaderTemplate: Templat opsional untuk sel header kolom ini. Jika tidak ditentukan, templat header default menyertakan Title, bersama dengan indikator pengurutan dan tombol opsi yang berlaku.
  • Title: Teks judul untuk kolom. Judul dirender secara otomatis jika HeaderTemplate tidak digunakan.

Misalnya, tambahkan komponen berikut untuk merender kisi.

Komponen mengasumsikan bahwa mode render Server Interaktif (InteractiveServer) diwarisi dari komponen induk atau diterapkan secara global ke aplikasi, yang memungkinkan fitur interaktif. Untuk contoh berikut, satu-satunya fitur interaktif adalah kolom yang dapat diurutkan.

PromotionGrid.razor:

@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();
}

Akses komponen di browser di jalur /promotion-gridrelatif .

Tidak ada rencana saat ini untuk diperluas QuickGrid dengan fitur yang cenderung ditawarkan kisi komersial lengkap, misalnya, baris hierarkis, kolom seret-ke-urutkan ulang, atau pilihan rentang seperti Excel. Jika Anda memerlukan fitur lanjutan yang tidak ingin Anda kembangkan sendiri, lanjutkan menggunakan kisi pihak ketiga.

Atribut dan gaya kustom

QuickGrid juga mendukung meneruskan atribut kustom dan kelas gaya ke elemen tabel yang dirender:

<QuickGrid Items="..." custom-attribute="value" class="custom-class">

Sumber data Entity Framework Core (EF Core)

EF CoreDbContextDbSet<TEntity> menyediakan properti untuk setiap tabel dalam database. Berikan properti ke Items parameter .

Contoh berikut menggunakan PeopleDbSet<TEntity> (tabel) sebagai sumber data:

@inject ApplicationDbContext AppDbContext

<QuickGrid Items="@AppDbContext.People">
    ...
</QuickGrid>

Anda juga dapat menggunakan operator LINQ yang didukung EF untuk memfilter data sebelum meneruskannya ke Items parameter .

Contoh berikut memfilter dokumen menurut ID kategori:

<QuickGrid Items="@AppDbContext.Documents.Where(d => d.CategoryId == categoryId)">
    ...
</QuickGrid>

QuickGrid mengenali instans yang disediakan IQueryable EF dan tahu cara mengatasi kueri secara asinkron untuk efisiensi.

Mulailah dengan menambahkan referensi paket untuk Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter paket NuGet.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Panggil AddQuickGridEntityFrameworkAdapter pengumpulan layanan dalam Program file untuk mendaftarkan implementasi sadar IAsyncQueryExecutor EF:

builder.Services.AddQuickGridEntityFrameworkAdapter();

Dukungan nama tampilan

Judul kolom dapat ditetapkan menggunakan ColumnBase<TGridItem>.Title di PropertyColumn<TGridItem,TProp>tag . Dalam contoh berikut, kolom diberi nama "Release Date" untuk data tanggal rilis film kolom:

<PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />

Namun, mengelola judul kolom (nama) dari properti model terikat biasanya merupakan pilihan yang lebih baik untuk memelihara aplikasi. Model dapat mengontrol nama tampilan properti dengan [Display] atribut . Dalam contoh berikut, model menentukan nama tampilan tanggal rilis film "Release Date" untuk propertinya ReleaseDate :

[Display(Name = "Release Date")]
public DateTime ReleaseDate { get; set; }

Untuk mengaktifkan QuickGrid komponen untuk menggunakan DisplayAttribute.Name, subkelas PropertyColumn<TGridItem,TProp> baik di komponen atau di kelas terpisah:

public class DisplayNameColumn<TGridItem, TProp> : PropertyColumn<TGridItem, TProp>
{
    protected override void OnParametersSet()
    {
        if (Title is null && Property.Body is MemberExpression memberExpression)
        {
            var memberInfo = memberExpression.Member;
            Title = 
                memberInfo.GetCustomAttribute<DisplayNameAttribute>().DisplayName ??
                memberInfo.GetCustomAttribute<DisplayAttribute>().Name ??
                memberInfo.Name;
        }

        base.OnParametersSet();
    }
}

Gunakan subkelas dalam QuickGrid komponen. Dalam contoh berikut, sebelumnya DisplayNameColumn digunakan. Nama "Release Date" disediakan oleh [Display] atribut dalam model, jadi tidak perlu menentukan Title:

<DisplayNameColumn Property="movie => movie.ReleaseDate" />

Atribut [DisplayName] ini juga didukung:

[DisplayName("Release Date")]
public DateTime ReleaseDate { get; set; }

Namun, [Display] atribut disarankan karena membuat properti tambahan tersedia. Misalnya, [Display] atribut menawarkan kemampuan untuk menetapkan jenis sumber daya untuk pelokalan.

Data jarak jauh

Dalam Blazor WebAssembly aplikasi, mengambil data dari JSAPI web berbasis ON di server adalah persyaratan umum. Untuk mengambil hanya data yang diperlukan untuk halaman/viewport data saat ini dan menerapkan aturan pengurutan atau pemfilteran di server, gunakan ItemsProvider parameter .

ItemsProvider juga dapat digunakan di aplikasi sisi Blazor server jika aplikasi diperlukan untuk mengkueri titik akhir eksternal atau dalam kasus lain di mana persyaratan tidak tercakup oleh IQueryable.

Berikan panggilan balik yang cocok dengan GridItemsProvider<TGridItem> jenis delegasi, di mana TGridItem adalah jenis data yang ditampilkan di kisi. Panggilan balik diberi parameter jenis GridItemsProviderRequest<TGridItem>, yang menentukan indeks mulai, jumlah baris maksimum, dan urutan pengurutan data yang akan dikembalikan. Selain mengembalikan item yang cocok, jumlah item total (totalItemCount) juga diperlukan agar halaman dan virtualisasi berfungsi dengan benar.

Contoh berikut memperoleh data dari database OpenFDA Food Enforcement publik.

mengonversi GridItemsProvider<TGridItem>GridItemsProviderRequest<TGridItem> menjadi kueri terhadap database OpenFDA. Parameter kueri diterjemahkan ke dalam format URL tertentu yang didukung oleh ON API eksternal JS. Anda hanya dapat melakukan pengurutan dan pemfilteran melalui pengurutan dan pemfilteran yang didukung oleh API eksternal. Titik akhir OpenFDA tidak mendukung pengurutan, sehingga tidak ada kolom yang ditandai sebagai dapat diurutkan. Namun, ini mendukung melompati rekaman (skip parameter) dan membatasi pengembalian rekaman (limit parameter), sehingga komponen dapat mengaktifkan virtualisasi dan menggulir dengan cepat melalui puluhan ribu rekaman.

FoodRecalls.razor:

@page "/food-recalls"
@inject HttpClient Http
@inject NavigationManager NavManager

<PageTitle>Food Recalls</PageTitle>

<h1>OpenFDA Food Recalls</h1>

<div class="grid" tabindex="-1">
    <QuickGrid ItemsProvider="@foodRecallProvider" Virtualize="true">
        <PropertyColumn Title="ID" Property="@(c => c.Event_Id)" />
        <PropertyColumn Property="@(c => c.State)" />
        <PropertyColumn Property="@(c => c.City)" />
        <PropertyColumn Title="Company" Property="@(c => c.Recalling_Firm)" />
        <PropertyColumn Property="@(c => c.Status)" />
    </QuickGrid>
</div>

<p>Total: <strong>@numResults results found</strong></p>

@code {
    GridItemsProvider<FoodRecall>? foodRecallProvider;
    int numResults;

    protected override async Task OnInitializedAsync()
    {
        foodRecallProvider = async req =>
        {
            var url = NavManager.GetUriWithQueryParameters(
                "https://api.fda.gov/food/enforcement.json", 
                new Dictionary<string, object?>
            {
                { "skip", req.StartIndex },
                { "limit", req.Count },
            });

            var response = await Http.GetFromJsonAsync<FoodRecallQueryResult>(
                url, req.CancellationToken);

            return GridItemsProviderResult.From(
                items: response!.Results,
                totalItemCount: response!.Meta.Results.Total);
        };

        numResults = (await Http.GetFromJsonAsync<FoodRecallQueryResult>(
            "https://api.fda.gov/food/enforcement.json"))!.Meta.Results.Total;
    }
}

Untuk informasi selengkapnya tentang memanggil API web, lihat Memanggil API web dari aplikasi ASP.NET CoreBlazor.

QuickGrid perancah

Perancah QuickGrid perancah mengacah Razor komponen dengan QuickGrid untuk menampilkan data dari database.

Perancah menghasilkan halaman Buat, Baca, Perbarui, dan Hapus (CRUD) dasar berdasarkan model data Entity Framework Core. Anda dapat membuat perancah halaman individual atau semua halaman CRUD. Anda memilih kelas model dan DbContext, secara opsional membuat baru DbContext jika diperlukan.

Komponen yang dibuat perancah Razor ditambahkan ke folder proyek Pages dalam folder yang dihasilkan yang dinamai sesuai kelas model. Komponen yang dihasilkan Index menggunakan QuickGrid untuk menampilkan data. Sesuaikan komponen yang dihasilkan sesuai kebutuhan dan aktifkan interaktivitas untuk memanfaatkan fitur interaktif, seperti pengurutan dan pemfilteran.

Komponen yang dihasilkan oleh perancah memerlukan penyajian sisi server (SSR), sehingga tidak didukung saat berjalan di WebAssembly.

Untuk menggunakan perancah di Visual Studio, klik kanan proyek di Penjelajah Solusi dan pilih Tambahkan>Item Perancah Baru. Buka Komponen UmumRazor> yang Diinstal.> Pilih Razor Komponen menggunakan Kerangka Kerja Entitas (CRUD). Untuk menggunakan perancah dengan .NET CLI, lihat ASP.NET Alat generator kode inti ('aspnet-codegenerator').