Tampilan parsial di ASP.NET Core

Oleh Steve Smith, Maher JENDOUBI, Rick Anderson, dan Scott Sauber

Tampilan parsial adalah Razor file markup (.cshtml) tanpa @page direktif yang merender output HTML dalam output yang dirender file markup lain.

Istilah tampilan parsial digunakan saat mengembangkan aplikasi MVC, di mana file markup disebut tampilan, atau Razor aplikasi Pages, tempat file markup disebut halaman. Topik ini secara umum mengacu pada tampilan MVC dan Razor halaman Halaman sebagai file markup.

Melihat atau mengunduh kode sampel (cara mengunduh)

Kapan menggunakan tampilan parsial

Tampilan parsial adalah cara yang efektif untuk:

• Memecah file markup besar menjadi komponen yang lebih kecil.

  Dalam file markup besar dan kompleks yang terdiri dari beberapa bagian logis, ada keuntungan untuk bekerja dengan setiap bagian yang diisolasi menjadi tampilan parsial. Kode dalam file markup dapat dikelola karena markup hanya berisi struktur halaman keseluruhan dan referensi ke tampilan parsial.

• Kurangi duplikasi konten markup umum di seluruh file markup.

  Ketika elemen markup yang sama digunakan di seluruh file markup, tampilan parsial menghapus duplikasi konten markup ke dalam satu file tampilan parsial. Saat markup diubah dalam tampilan parsial, markup akan memperbarui output file markup yang dirender yang menggunakan tampilan parsial.

Tampilan parsial tidak boleh digunakan untuk mempertahankan elemen tata letak umum. Elemen tata letak umum harus ditentukan dalam file _Layout.cshtml .

Jangan gunakan tampilan parsial di mana logika penyajian kompleks atau eksekusi kode diperlukan untuk merender markup. Alih-alih tampilan parsial, gunakan komponen tampilan.

Mendeklarasikan tampilan parsial

Tampilan parsial adalah .cshtml file markup tanpa direktif yang @page dipertahankan dalam folder Tampilan (MVC) atau folder Halaman (Razor Halaman).

Dalam ASP.NET Core MVC, pengontrol ViewResult mampu mengembalikan tampilan atau tampilan parsial. Di Razor Halaman, PageModel bisa mengembalikan tampilan parsial yang diwakili sebagai PartialViewResult objek. Mereferensikan dan merender tampilan parsial dijelaskan di bagian Referensi tampilan parsial.

Tidak seperti tampilan MVC atau penyajian halaman, tampilan parsial tidak berjalan _ViewStart.cshtml. Untuk informasi selengkapnya tentang _ViewStart.cshtml, lihat Tata Letak di ASP.NET Core.

Nama file tampilan parsial sering dimulai dengan garis bawah (_). Konvensi penamaan ini tidak diperlukan, tetapi membantu membedakan tampilan parsial secara visual dari tampilan dan halaman.

Mereferensikan tampilan parsial

Menggunakan tampilan parsial di Razor PageModel Halaman

Dalam ASP.NET Core 2.0 atau 2.1, metode handler berikut merender tampilan parsial _AuthorPartialRP.cshtml ke respons:

public IActionResult OnGetPartial() =>
    new PartialViewResult
    {
        ViewName = "_AuthorPartialRP",
        ViewData = ViewData,
    };

Dalam ASP.NET Core 2.2 atau yang lebih baru, metode handler dapat memanggil Partial metode untuk menghasilkan PartialViewResult objek:

public IActionResult OnGetPartial() =>
    Partial("_AuthorPartialRP");

Menggunakan tampilan parsial dalam file markup

Dalam file markup, ada beberapa cara untuk mereferensikan tampilan parsial. Sebaiknya aplikasi menggunakan salah satu pendekatan penyajian asinkron berikut:

• Pembantu Tag Parsial
• Pembantu HTML Asinkron

Bantuan Tag Parsial

Pembantu Tag Parsial memerlukan ASP.NET Core 2.1 atau yang lebih baru.

Pembantu Tag Parsial merender konten secara asinkron dan menggunakan sintaks seperti HTML:

<partial name="_PartialName" />

Saat ekstensi file ada, Pembantu Tag mereferensikan tampilan parsial yang harus berada di folder yang sama dengan file markup yang memanggil tampilan parsial:

<partial name="_PartialName.cshtml" />

Contoh berikut mereferensikan tampilan parsial dari akar aplikasi. Jalur yang dimulai dengan garis miring-tilde (~/) atau garis miring (/) merujuk ke akar aplikasi:

Razor Pages

<partial name="~/Pages/Folder/_PartialName.cshtml" />
<partial name="/Pages/Folder/_PartialName.cshtml" />

MVC

<partial name="~/Views/Folder/_PartialName.cshtml" />
<partial name="/Views/Folder/_PartialName.cshtml" />

Contoh berikut mereferensikan tampilan parsial dengan jalur relatif:

<partial name="../Account/_PartialName.cshtml" />

Untuk informasi selengkapnya, lihat Pembantu Tag Parsial di ASP.NET Core.

Pembantu HTML Asinkron

Saat menggunakan Pembantu HTML, praktik terbaiknya adalah menggunakan PartialAsync. PartialAsync mengembalikan jenis yang IHtmlContent dibungkus dalam Task<TResult>. Metode ini direferensikan dengan awalan panggilan yang ditunggu dengan @ karakter:

@await Html.PartialAsync("_PartialName")

Saat ekstensi file ada, Pembantu HTML mereferensikan tampilan parsial yang harus berada di folder yang sama dengan file markup yang memanggil tampilan parsial:

@await Html.PartialAsync("_PartialName.cshtml")

Contoh berikut mereferensikan tampilan parsial dari akar aplikasi. Jalur yang dimulai dengan garis miring-tilde (~/) atau garis miring (/) merujuk ke akar aplikasi:

Razor Pages

@await Html.PartialAsync("~/Pages/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Pages/Folder/_PartialName.cshtml")

MVC

@await Html.PartialAsync("~/Views/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Views/Folder/_PartialName.cshtml")

Contoh berikut mereferensikan tampilan parsial dengan jalur relatif:

@await Html.PartialAsync("../Account/_LoginPartial.cshtml")

Atau, Anda dapat merender tampilan parsial dengan RenderPartialAsync. Metode ini tidak mengembalikan IHtmlContent. Ini mengalirkan output yang dirender langsung ke respons. Karena metode tidak mengembalikan hasil, metode harus dipanggil dalam Razor blok kode:

@{
    await Html.RenderPartialAsync("_AuthorPartial");
}

Karena RenderPartialAsync streaming konten yang dirender, ini memberikan performa yang lebih baik dalam beberapa skenario. Dalam situasi kritis performa, tolok ukur halaman menggunakan kedua pendekatan dan gunakan pendekatan yang menghasilkan respons yang lebih cepat.

Pembantu HTML Sinkron

Partial dan RenderPartial merupakan setara sinkron dan PartialAsync RenderPartialAsync, masing-masing. Setara sinkron tidak disarankan karena ada skenario di mana mereka mengalami kebuntuan. Metode sinkron ditargetkan untuk dihapus dalam rilis mendatang.

Penting

Jika Anda perlu menjalankan kode, gunakan komponen tampilan alih-alih tampilan parsial.

Memanggil Partial atau RenderPartial menghasilkan peringatan penganalisis Visual Studio. Misalnya, kehadiran Partial menghasilkan pesan peringatan berikut:

Penggunaan IHtmlHelper.Partial dapat mengakibatkan kebuntuan aplikasi. Pertimbangkan untuk menggunakan <Pembantu Tag parsial> atau IHtmlHelper.PartialAsync.

Ganti panggilan ke @Html.Partial dengan @await Html.PartialAsync atau Pembantu Tag Parsial. Untuk informasi selengkapnya tentang migrasi Pembantu Tag Parsial, lihat Migrasi dari Pembantu HTML.

Penemuan tampilan parsial

Saat tampilan parsial direferensikan berdasarkan nama tanpa ekstensi file, lokasi berikut dicari dalam urutan yang dinyatakan:

Razor Pages

1. Saat ini menjalankan folder halaman
2. Grafik direktori di atas folder halaman
3. /Shared
4. /Pages/Shared
5. /Views/Shared

MVC

1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
4. /Pages/Shared

Konvensi berikut berlaku untuk penemuan tampilan parsial:

• Tampilan parsial yang berbeda dengan nama file yang sama diizinkan ketika tampilan parsial berada di folder yang berbeda.
• Saat mereferensikan tampilan parsial berdasarkan nama tanpa ekstensi file dan tampilan parsial ada di folder pemanggil dan folder Bersama , tampilan parsial di folder penelepon memasok tampilan parsial. Jika tampilan parsial tidak ada di folder penelepon, tampilan parsial disediakan dari folder Bersama . Tampilan parsial di folder Bersama disebut tampilan parsial bersama atau tampilan parsial default.
• Tampilan parsial dapat ditautkan—tampilan parsial dapat memanggil tampilan parsial lain jika referensi melingkar tidak dibentuk oleh panggilan. Jalur relatif selalu relatif terhadap file saat ini, bukan ke akar atau induk file.

Catatan

Yang Razor section ditentukan dalam tampilan parsial tidak terlihat oleh file markup induk. section hanya terlihat oleh tampilan parsial tempat tampilan didefinisikan.

Mengakses data dari tampilan parsial

Saat tampilan parsial dibuat, tampilan menerima salinan kamus indukViewData. Pembaruan yang dibuat pada data dalam tampilan parsial tidak dipertahankan ke tampilan induk. ViewData perubahan dalam tampilan parsial hilang saat tampilan parsial kembali.

Contoh berikut menunjukkan cara meneruskan instans ViewDataDictionary ke tampilan parsial:

@await Html.PartialAsync("_PartialName", customViewData)

Anda dapat meneruskan model ke dalam tampilan parsial. Model dapat menjadi objek kustom. Anda dapat meneruskan model dengan PartialAsync (merender blok konten ke pemanggil) atau RenderPartialAsync (mengalirkan konten ke output):

@await Html.PartialAsync("_PartialName", model)

Razor Pages

Markup berikut di aplikasi sampel berasal dari Pages/ArticlesRP/ReadRP.cshtml halaman. Halaman berisi dua tampilan parsial. Tampilan parsial kedua meneruskan model dan ViewData ke tampilan parsial. Overload ViewDataDictionary konstruktor digunakan untuk meneruskan kamus baru ViewData sambil mempertahankan kamus yang ada ViewData .

@model ReadRPModel

<h2>@Model.Article.Title</h2>
@* Pass the author's name to Pages\Shared\_AuthorPartialRP.cshtml *@
@await Html.PartialAsync("../Shared/_AuthorPartialRP", Model.Article.AuthorName)
@Model.Article.PublicationDate

@* Loop over the Sections and pass in a section and additional ViewData to 
   the strongly typed Pages\ArticlesRP\_ArticleSectionRP.cshtml partial view. *@
@{
    var index = 0;

    foreach (var section in Model.Article.Sections)
    {
        await Html.PartialAsync("_ArticleSectionRP", 
                                section,
                                new ViewDataDictionary(ViewData)
                                {
                                    { "index", index }
                                });

        index++;
    }
}

Pages/Shared/_AuthorPartialRP.cshtml adalah tampilan parsial pertama yang dirujuk ReadRP.cshtml oleh file markup:

@model string
<div>
    <h3>@Model</h3>
    This partial view from /Pages/Shared/_AuthorPartialRP.cshtml.
</div>

Pages/ArticlesRP/_ArticleSectionRP.cshtml adalah tampilan parsial kedua yang dirujuk ReadRP.cshtml oleh file markup:

@using PartialViewsSample.ViewModels
@model ArticleSection

<h3>@Model.Title Index: @ViewData["index"]</h3>
<div>
    @Model.Content
</div>

MVC

Markup berikut di aplikasi sampel memperlihatkan Views/Articles/Read.cshtml tampilan. Tampilan berisi dua tampilan parsial. Tampilan parsial kedua meneruskan model dan ViewData ke tampilan parsial. Overload ViewDataDictionary konstruktor digunakan untuk meneruskan kamus baru ViewData sambil mempertahankan kamus yang ada ViewData .

@model PartialViewsSample.ViewModels.Article

<h2>@Model.Title</h2>
@* Pass the author's name to Views\Shared\_AuthorPartial.cshtml *@
@await Html.PartialAsync("_AuthorPartial", Model.AuthorName)
@Model.PublicationDate

@* Loop over the Sections and pass in a section and additional ViewData to 
   the strongly typed Views\Articles\_ArticleSection.cshtml partial view. *@
@{
    var index = 0;

    foreach (var section in Model.Sections)
    {
        @(await Html.PartialAsync("_ArticleSection", 
                                section,
                                new ViewDataDictionary(ViewData)
                                {
                                    { "index", index }
                                }))

        index++;
    }
}

Views/Shared/_AuthorPartial.cshtml adalah tampilan parsial pertama yang dirujuk Read.cshtml oleh file markup:

@model string
<div>
    <h3>@Model</h3>
    This partial view from /Views/Shared/_AuthorPartial.cshtml.
</div>

Views/Articles/_ArticleSection.cshtml adalah tampilan parsial kedua yang dirujuk Read.cshtml oleh file markup:

@using PartialViewsSample.ViewModels
@model ArticleSection

<h3>@Model.Title Index: @ViewData["index"]</h3>
<div>
    @Model.Content
</div>

Pada runtime, parsial dirender ke dalam output yang dirender file markup induk, yang dirender dalam bersama _Layout.cshtml. Tampilan parsial pertama merender nama penulis artikel dan tanggal publikasi:

Abraham Lincoln

Tampilan parsial ini dari <jalur> file tampilan parsial bersama. 19/11/1863 12:00:00 AM

Tampilan parsial kedua merender bagian artikel:

Indeks Bagian Satu: 0

Empat skor dan tujuh tahun yang lalu ...

Indeks Bagian Dua: 1

Sekarang kita terlibat dalam perang saudara besar, pengujian ...

Indeks Bagian Tiga: 2

Tapi, dalam arti yang lebih besar, kita tidak bisa mendedikasikan ...

Sumber Daya Tambahan:

• Referensi sintaks Razor untuk ASP.NET Core
• Menandai Pembantu di ASP.NET Core
• Pembantu Tag Parsial di ASP.NET Core
• Lihat komponen di ASP.NET Core
• Area di ASP.NET Core