komponen templat ASP.NET Core Blazor

Oleh Robert Haken

Artikel ini menjelaskan bagaimana komponen yang di-template dapat menerima satu atau beberapa templat UI sebagai parameter, yang kemudian dapat digunakan sebagai bagian dari logika penyajian komponen.

Komponen bertemplat

Komponen yang di-template adalah komponen yang menerima satu atau beberapa templat UI sebagai parameter, yang dapat digunakan dalam logika penyajian komponen. Dengan menggunakan komponen templat, Anda dapat membuat komponen tingkat lebih tinggi yang lebih dapat digunakan kembali. Contohnya meliputi:

• Komponen tabel yang memungkinkan pengguna menentukan templat untuk header, baris, dan footer tabel.
• Komponen daftar yang memungkinkan pengguna menentukan templat untuk menyajikan item dalam daftar.
• Komponen bilah navigasi yang memungkinkan pengguna menentukan templat untuk memulai konten dan tautan navigasi.

Komponen templat didefinisikan dengan menentukan satu atau beberapa parameter komponen jenis RenderFragment atau RenderFragment<TValue>. Fragmen render mewakili segmen UI untuk dirender. RenderFragment<TValue> mengambil parameter jenis yang dapat ditentukan ketika fragmen render dipanggil.

Catatan

Untuk informasi selengkapnya tentang RenderFragment, lihat komponen ASP.NET CoreRazor.

Seringkali, komponen templat diketik secara generis, seperti yang ditunjukkan komponen berikut TemplatedNavBar (TemplatedNavBar.razor). Jenis generik (<T>) dalam contoh berikut digunakan untuk merender IReadOnlyList<T> nilai, yang dalam hal ini adalah daftar hewan peliharaan untuk komponen yang menampilkan bilah navigasi dengan tautan ke komponen detail hewan peliharaan.

TemplatedNavBar.razor:

@typeparam TItem

<nav class="navbar navbar-expand navbar-light bg-light">
    <div class="container justify-content-start">
        @StartContent
        <div class="navbar-nav">
            @foreach (var item in Items)
            {
                @ItemTemplate(item)
            }
        </div>
    </div>
</nav>

@code {
    [Parameter]
    public RenderFragment? StartContent { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> ItemTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Saat menggunakan komponen bertemplat, parameter templat dapat ditentukan dengan menggunakan elemen turunan yang cocok dengan nama parameter. Dalam contoh berikut, <StartContent>...</StartContent> dan <ItemTemplate>...</ItemTemplate> berikan RenderFragment<TValue> templat untuk StartContent dan ItemTemplate komponen TemplatedNavBar .

Context Tentukan atribut pada elemen komponen saat Anda ingin menentukan nama parameter konten untuk konten turunan implisit (tanpa elemen turunan pembungkus). Dalam contoh berikut, Context atribut muncul pada TemplatedNavBar elemen dan berlaku untuk semua RenderFragment<TValue> parameter templat.

Pets1.razor:

@page "/pets-1"

<PageTitle>Pets 1</PageTitle>

<h1>Pets Example 1</h1>

<TemplatedNavBar Items="pets" Context="pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-1")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Atau, Anda dapat mengubah nama parameter menggunakan Context atribut pada elemen turunan RenderFragment<TValue> . Dalam contoh berikut, Context diatur ke ItemTemplate bukan TemplatedNavBar.

Pets2.razor:

@page "/pets-2"

<PageTitle>Pets 2</PageTitle>

<h1>Pets Example 2</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate Context="pet">
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-2")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Argumen komponen jenis RenderFragment<TValue> memiliki parameter implisit bernama context, yang dapat digunakan. Dalam contoh berikut, Context tidak diatur. @context.{PROPERTY} memasok nilai hewan peliharaan ke templat, di mana {PROPERTY} adalah Pet properti:

Pets3.razor:

@page "/pets-3"

<PageTitle>Pets 3</PageTitle>

<h1>Pets Example 3</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{context.PetId}?ReturnUrl=%2Fpets-3")" class="nav-link">
            @context.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Saat menggunakan komponen yang diketik generik, parameter jenis disimpulkan jika memungkinkan. Namun, Anda dapat secara eksplisit menentukan jenis dengan atribut yang memiliki nama yang cocok dengan parameter jenis, yang ada TItem dalam contoh sebelumnya:

Pets4.razor:

@page "/pets-4"

<PageTitle>Pets 4</PageTitle>

<h1>Pets Example 4</h1>

<TemplatedNavBar Items="pets" Context="pet" TItem="Pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-4")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 2, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 4, Name = "Salem Saberhagen" },
        new Pet { PetId = 7, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Contoh yang disediakan dalam TemplatedNavBar komponen (TemplatedNavBar.razor) mengasumsikan bahwa Items koleksi tidak berubah setelah render awal; atau bahwa jika memang berubah, mempertahankan status komponen/elemen yang digunakan ItemTemplate tidak diperlukan. Untuk komponen templat di mana penggunaan tersebut tidak dapat diantisipasi, lihat bagian Mempertahankan hubungan dengan @key .

Mempertahankan hubungan dengan @key

Komponen templat sering digunakan untuk merender kumpulan item, seperti tabel atau daftar. Dalam skenario umum seperti itu, kami tidak dapat berasumsi bahwa pengguna akan menghindari komponen/elemen stateful dalam definisi templat item atau bahwa tidak akan ada perubahan tambahan pada Items koleksi. Untuk komponen templat tersebut, perlu untuk mempertahankan hubungan dengan atribut direktif @key .

Catatan

Untuk informasi selengkapnya tentang atribut direktif @key , lihat Mempertahankan elemen, komponen, dan hubungan model di ASP.NET Core Blazor.

Komponen berikut TableTemplate (TableTemplate.razor) menunjukkan komponen templat yang mempertahankan hubungan dengan @key.

TableTemplate.razor:

@typeparam TItem

<table class="table">
    <thead>
        <tr>@TableHeader</tr>
    </thead>
    <tbody>
        @foreach (var item in Items)
        {
            <tr @key="@item">@RowTemplate(item)</tr>
        }
    </tbody>
</table>

@code {
    [Parameter]
    public RenderFragment? TableHeader { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> RowTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Pertimbangkan komponen berikut Pets5 (Pets5.razor), yang menunjukkan pentingnya data kunci untuk mempertahankan hubungan model. Dalam komponen, setiap iterasi penambahan hewan peliharaan OnAfterRenderAsync menghasilkan Blazor rerender komponen TableTemplate .

Pets5.razor:

@page "/pets-5"

<PageTitle>Pets 5</PageTitle>

<h1>Pets Example 5</h1>

<TableTemplate Items="pets" Context="pet">
    <TableHeader>
        <th>ID</th>
        <th>Name</th>
    </TableHeader>
    <RowTemplate>
        <td><input value="@pet.PetId" /></td>
        <td><input value="@pet.Name" /></td>
    </RowTemplate>
</TableTemplate>


@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        // Insert new pet every 5 seconds
        if (pets.Count < 10)
        {
            await Task.Delay(5000);
            pets.Insert(0, new Pet() { PetId = pets.Count + 1, Name = "<new pet>" });
            StateHasChanged();
        }
    }

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Demonstrasi ini memungkinkan Anda untuk:

• <input> Pilih dari beberapa baris tabel yang dirender.
• Pelajari perilaku fokus halaman saat koleksi hewan peliharaan secara otomatis tumbuh.

Tanpa menggunakan @key atribut direktif dalam TableTemplate komponen, fokus halaman tetap pada posisi indeks (baris) tabel yang sama, menyebabkan fokus untuk bergeser setiap kali hewan peliharaan ditambahkan. Untuk menunjukkan hal ini, hapus @key atribut dan nilai direktif, mulai ulang aplikasi, dan coba ubah nilai bidang saat item ditambahkan.

Sumber Daya Tambahan:

• praktik terbaik performa inti Blazor ASP.NET
• Pertahankan hubungan elemen, komponen, dan model di ASP.NET Core Blazor
• Blazorsampel repositori GitHub () (dotnet/blazor-samplescara mengunduh)