Zobrazení komponent v ASP.NET Core

Autor: Rick Anderson

Komponenty zobrazení

Komponenty zobrazení se podobají částečným zobrazením, ale jsou mnohem výkonnější. Komponenty zobrazení nepoužívají vazbu modelu, závisí na datech předaných při volání komponenty zobrazení. Tento článek byl napsán pomocí kontrolerů a zobrazení, ale komponenty zobrazení fungují se stránkamiRazor.

Součást zobrazení:

• Vykreslí blok dat místo celé odpovědi.
• Zahrnuje stejné výhody oddělení a testovatelnosti, které byly nalezeny mezi kontrolerem a zobrazením.
• Může mít parametry a obchodní logiku.
• Obvykle je vyvolána ze stránky rozložení.

Součásti zobrazení jsou určené kdekoli opakovaně použitelná logika vykreslování, která je pro částečné zobrazení příliš složitá, například:

• Dynamické navigační nabídky
• Označování cloudu, kde se dotazuje databáze
• Panel Přihlášení
• Nákupní košík
• Nedávno publikované články
• Obsah bočního panelu na blogu
• Přihlašovací panel, který by se vykresloval na každé stránce a zobrazoval odkazy pro odhlášení nebo přihlášení v závislosti na stavu přihlášení uživatele

Součást zobrazení se skládá ze dvou částí:

• Třída, obvykle odvozená z ViewComponent
• Výsledek, který vrátí, obvykle zobrazení.

Podobně jako kontrolery může být komponenta zobrazení POCO, ale většina vývojářů využívá metody a vlastnosti, které jsou k dispozici odvozením z ViewComponent.

Při zvažování, jestli komponenty zobrazení splňují specifikace aplikace, zvažte místo toho použití Razor komponent. Razor komponenty také kombinují značky s kódem jazyka C#, aby se vytvořily opakovaně použitelné jednotky uživatelského rozhraní. Razor komponenty jsou navržené pro produktivitu vývojářů při poskytování logiky a složení uživatelského rozhraní na straně klienta. Další informace najdete v tématu ASP.NET základní Razor komponenty. Informace o tom, jak začlenit Razor komponenty do aplikace MVC nebo Razor Pages, najdete v tématu Integrace komponent ASP.NET Core Razor do aplikací ASP.NET Core.

Vytvoření komponenty zobrazení

Tato část obsahuje požadavky vysoké úrovně pro vytvoření komponenty zobrazení. Později v článku podrobně prozkoumáme jednotlivé kroky a vytvoříme součást zobrazení.

Třída komponenty view

Třídu komponenty zobrazení lze vytvořit některou z následujících možností:

• Odvození z ViewComponent
• Dekódování třídy atributem [ViewComponent] nebo odvození od třídy atributem [ViewComponent]
• Vytvoření třídy, kde název končí příponou ViewComponent

Podobně jako kontrolery musí být součásti zobrazení veřejné, vnořené a ne abstraktní třídy. Název komponenty zobrazení je název třídy s odebranou příponou ViewComponent . Lze ho Name také explicitně zadat pomocí vlastnosti.

Třída komponenty view:

• Podporuje injektáž závislostí konstruktoru .
• Neúčastní se životního cyklu kontroleru, proto se filtry nedají použít v komponentě zobrazení.

Chcete-li zabránit třídě, která má příponu nerozlišující ViewComponent malá a velká písmena, aby byla považována za součást zobrazení, ozdobte třídu atributem [NonViewComponent] :

using Microsoft.AspNetCore.Mvc;

[NonViewComponent]
public class ReviewComponent
{
    public string Status(string name) => JobStatus.GetCurrentStatus(name);
}

Zobrazení metod komponent

Komponenta zobrazení definuje svou logiku v:

• InvokeAsync metoda, která vrací Task<IViewComponentResult>.
• Invoke synchronní metoda, která vrací hodnotu IViewComponentResult.

Parametry pocházejí přímo z vyvolání komponenty zobrazení, nikoli z vazby modelu. Komponenta zobrazení nikdy přímo nezpracuje požadavek. Komponenta zobrazení obvykle inicializuje model a předává ho do zobrazení voláním View metody. V souhrnu zobrazte metody komponent:

• Definujte metodu InvokeAsyncTask<IViewComponentResult>, která vrací nebo synchronní Invoke metodu, která vrací .IViewComponentResult
• Obvykle inicializuje model a předá ho do zobrazení voláním ViewComponent.View metoda.
• Parametry pocházejí z volající metody, nikoli HTTP. Neexistuje žádná vazba modelu.
• Není dostupný přímo jako koncový bod HTTP. Obvykle se vyvolávají v zobrazení. Komponenta zobrazení nikdy nezpracuje požadavek.
• Jsou přetíženy u podpisu místo jakýchkoli podrobností z aktuálního požadavku HTTP.

Zobrazit cestu hledání

Modul runtime hledá zobrazení v následujících cestách:

• /Views/{Controller Name}/Components/{View Component Name}/{View Name}
• /Views/Shared/Components/{View Component Name}/{View Name}
• /Pages/Shared/Components/{View Component Name}/{View Name}
• /Areas/{Area Name}/Views/Shared/Components/{View Component Name}/{View Name}

Cesta hledání se vztahuje na projekty používající kontrolery a zobrazení a Razor stránky.

Výchozí název zobrazení komponenty zobrazení je Default, což znamená, že soubory zobrazení budou obvykle pojmenovány Default.cshtml. Při vytváření výsledku komponenty zobrazení nebo při volání View metody lze zadat jiný název zobrazení.

Doporučujeme pojmenovat soubor Default.cshtml zobrazení a použít cestu Views/Shared/Components/{View Component Name}/{View Name} . Součást zobrazení použitá PriorityList v této ukázce se používá Views/Shared/Components/PriorityList/Default.cshtml pro zobrazení komponenty zobrazení.

Přizpůsobení cesty hledání zobrazení

Pokud chcete upravit cestu hledání zobrazení, upravte Razorkolekci ViewLocationFormats . Pokud například chcete vyhledat zobrazení v cestě /Components/{View Component Name}/{View Name}, přidejte do kolekce novou položku:

using Microsoft.EntityFrameworkCore;
using ViewComponentSample.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews()
    .AddRazorOptions(options =>
    {
        options.ViewLocationFormats.Add("/{0}.cshtml");
    });

builder.Services.AddDbContext<ToDoContext>(options =>
        options.UseInMemoryDatabase("db"));

var app = builder.Build();

// Remaining code removed for brevity.

V předchozím kódu zástupný symbol {0} představuje cestu Components/{View Component Name}/{View Name}.

Vyvolání komponenty zobrazení

Chcete-li použít součást zobrazení, zavolejte v zobrazení následující:

@await Component.InvokeAsync("Name of view component",
                             {Anonymous Type Containing Parameters})

Parametry jsou předány metodě InvokeAsync . Komponenta PriorityList zobrazení vyvinutá v článku se vyvolá ze Views/ToDo/Index.cshtml souboru zobrazení. V následujícím kódu InvokeAsync je volána metoda se dvěma parametry:

</table>

<div>
    Maximum Priority: @ViewData["maxPriority"] <br />
    Is Complete:  @ViewData["isDone"]
    @await Component.InvokeAsync("PriorityList",
                     new { 
                         maxPriority =  ViewData["maxPriority"],
                         isDone = ViewData["isDone"]  }
                     )
</div>

Vyvolání komponenty zobrazení jako pomocné rutiny značek

Komponentu zobrazení lze vyvolat jako pomocnou rutinu značky:

<div>
       Maxium Priority: @ViewData["maxPriority"] <br />
       Is Complete:  @ViewData["isDone"]
    @{
        int maxPriority = Convert.ToInt32(ViewData["maxPriority"]);
        bool isDone = Convert.ToBoolean(ViewData["isDone"]);
    }
    <vc:priority-list max-priority=maxPriority is-done=isDone>
    </vc:priority-list>
</div>

Pascal-cased třídy a parametry metody pro pomocné rutiny značek jsou přeloženy do jejich kebab case. Pomocná rutina značky k vyvolání komponenty zobrazení používá <vc></vc> element. Součást zobrazení je určena následujícím způsobem:

<vc:[view-component-name]
  parameter1="parameter1 value"
  parameter2="parameter2 value">
</vc:[view-component-name]>

Chcete-li použít součást zobrazení jako pomocník značky, zaregistrujte sestavení obsahující součást zobrazení pomocí direktivy @addTagHelper . Pokud je součást zobrazení v sestavení volána MyWebApp, přidejte do souboru následující direktivu _ViewImports.cshtml :

@addTagHelper *, MyWebApp

Součást zobrazení lze zaregistrovat jako pomocnou rutinu značky do libovolného souboru, který odkazuje na komponentu zobrazení. Další informace o registraci pomocných rutin značek najdete v tématu Správa oboru pomocných rutin značek.

Metoda použitá InvokeAsync v tomto kurzu:

@await Component.InvokeAsync("PriorityList",
                 new { 
                     maxPriority =  ViewData["maxPriority"],
                     isDone = ViewData["isDone"]  }
                 )

V předchozím kódu se komponenta PriorityList zobrazení stane priority-list. Parametry komponenty zobrazení se předávají jako atributy v případě kebabu.

Vyvolání komponenty zobrazení přímo z kontroleru

Komponenty zobrazení jsou obvykle vyvolány ze zobrazení, ale lze je vyvolat přímo z metody kontroleru. I když komponenty zobrazení nedefinují koncové body, jako jsou kontrolery, akce kontroleru, která vrací obsah nějakého ViewComponentResult obsahu, je možné implementovat.

V následujícím příkladu se komponenta zobrazení volá přímo z kontroleru:

public IActionResult IndexVC(int maxPriority = 2, bool isDone = false)
{
    return ViewComponent("PriorityList",
        new { 
           maxPriority = maxPriority,
           isDone = isDone
        });
}

Vytvoření komponenty základního zobrazení

Stáhněte, sestavte a otestujte počáteční kód. Jedná se o základní projekt s kontrolerem ToDo , který zobrazuje seznam položek úkolů .

Aktualizace kontroleru tak, aby předával prioritu a stav dokončení

Aktualizujte metodu Index tak, aby používala parametry stavu priority a dokončení:

using Microsoft.AspNetCore.Mvc;
using ViewComponentSample.Models;

namespace ViewComponentSample.Controllers;
public class ToDoController : Controller
{
    private readonly ToDoContext _ToDoContext;

    public ToDoController(ToDoContext context)
    {
        _ToDoContext = context;
        _ToDoContext.Database.EnsureCreated();
    }

    public IActionResult Index(int maxPriority = 2, bool isDone = false)
    {
        var model = _ToDoContext!.ToDo!.ToList();
        ViewData["maxPriority"] = maxPriority;
        ViewData["isDone"] = isDone;
        return View(model);
    }

Přidání třídy ViewComponent

Přidejte třídu ViewComponent do ViewComponents/PriorityListViewComponent.cs:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using ViewComponentSample.Models;

namespace ViewComponentSample.ViewComponents;

public class PriorityListViewComponent : ViewComponent
{
    private readonly ToDoContext db;

    public PriorityListViewComponent(ToDoContext context) => db = context;

    public async Task<IViewComponentResult> InvokeAsync(
                                            int maxPriority, bool isDone)
    {
        var items = await GetItemsAsync(maxPriority, isDone);
        return View(items);
    }

    private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
    {
        return db!.ToDo!.Where(x => x.IsDone == isDone &&
                             x.Priority <= maxPriority).ToListAsync();
    }
}

Poznámky k kódu:

• Třídy komponent zobrazení mohou být obsaženy v libovolné složce v projektu.

• Vzhledem k tomu, že název třídy PriorityListViewComponent končí příponou ViewComponent, modul runtime používá řetězec PriorityList při odkazování na komponentu třídy ze zobrazení.

• Atribut [ViewComponent] může změnit název použitý pro odkaz na součást zobrazení. Třída může mít například název XYZ s následujícím [ViewComponent] atributem:

  [ViewComponent(Name = "PriorityList")]
     public class XYZ : ViewComponent
  

• Atribut [ViewComponent] v předchozím kódu říká selektoru komponenty zobrazení, který má použít:

  • Název PriorityList při hledání zobrazení přidružených ke komponentě
  • Řetězec PriorityList při odkazování na komponentu třídy ze zobrazení.

• Komponenta používá injektáž závislostí k zpřístupnění kontextu dat.

• InvokeAsync zveřejňuje metodu, kterou lze volat ze zobrazení, a může mít libovolný počet argumentů.

• Metoda InvokeAsync vrátí sadu ToDo položek, které vyhovují parametrůmisDone.maxPriority

Vytvoření zobrazení komponenty Razor zobrazení

• Vytvořte složku Views/Shared/Components. Tato složka musí mít název Součásti.

• Vytvořte složku Views/Shared/Components/PriorityList. Tento název složky musí odpovídat názvu třídy komponenty zobrazení nebo názvu třídy minus příponu. ViewComponent Pokud se atribut použije, název třídy by se měl shodovat s označením atributu.

• Vytvoření Views/Shared/Components/PriorityList/Default.cshtmlRazor zobrazení:

  @model IEnumerable<ViewComponentSample.Models.TodoItem>
  
  <h3>Priority Items</h3>
  <ul>
      @foreach (var todo in Model)
      {
          <li>@todo.Name</li>
      }
  </ul>
  

  Zobrazení Razor obsahuje seznam TodoItem a zobrazuje je. Pokud metoda komponenty InvokeAsync view nepředá název zobrazení, použije se výchozí pro název zobrazení podle konvence. Pokud chcete přepsat výchozí styl konkrétního kontroleru, přidejte zobrazení do složky zobrazení specifické pro kontroler (například Views/ToDo/Components/PriorityList/Default.cshtml).

  Pokud je součást zobrazení specifická pro řadič, lze ji přidat do složky specifické pro kontroler. Například Views/ToDo/Components/PriorityList/Default.cshtml je specifický pro kontroler.

• div Přidejte do dolní části Views/ToDo/index.cshtml souboru volání obsahující volání komponenty seznamu priorit:

  </table>
  
  <div>
      Maximum Priority: @ViewData["maxPriority"] <br />
      Is Complete:  @ViewData["isDone"]
      @await Component.InvokeAsync("PriorityList",
                       new { 
                           maxPriority =  ViewData["maxPriority"],
                           isDone = ViewData["isDone"]  }
                       )
  </div>
  

@await Component.InvokeAsync Revize zobrazuje syntaxi pro komponenty zobrazení volání. Prvním argumentem je název komponenty, kterou chceme vyvolat nebo volat. Další parametry se předají komponentě. InvokeAsync může mít libovolný počet argumentů.

Otestujete aplikaci. Následující obrázek ukazuje seznam úkolů a prioritní položky:

Komponentu zobrazení lze volat přímo z kontroleru:

public IActionResult IndexVC(int maxPriority = 2, bool isDone = false)
{
    return ViewComponent("PriorityList",
        new { 
           maxPriority = maxPriority,
           isDone = isDone
        });
}

Zadání názvu komponenty zobrazení

Komponenta komplexního zobrazení může za určitých podmínek potřebovat zadat jiné než výchozí zobrazení. Následující kód ukazuje, jak určit zobrazení PVC z InvokeAsync metody. Aktualizujte metodu InvokeAsyncPriorityListViewComponent ve třídě.

public async Task<IViewComponentResult> InvokeAsync(
                                           int maxPriority, bool isDone)
{
    string MyView = "Default";
    // If asking for all completed tasks, render with the "PVC" view.
    if (maxPriority > 3 && isDone == true)
    {
        MyView = "PVC";
    }
    var items = await GetItemsAsync(maxPriority, isDone);
    return View(MyView, items);
}

Views/Shared/Components/PriorityList/Default.cshtml Zkopírujte soubor do zobrazení s názvem Views/Shared/Components/PriorityList/PVC.cshtml. Přidejte nadpis, který označuje, že se používá zobrazení PVC.

@model IEnumerable<ViewComponentSample.Models.TodoItem>

<h2> PVC Named Priority Component View</h2>
<h4>@ViewBag.PriorityMessage</h4>
<ul>
    @foreach (var todo in Model)
    {
        <li>@todo.Name</li>
    }
</ul>

Spusťte aplikaci a ověřte zobrazení PVC.

Pokud zobrazení PVC není vykreslené, ověřte, zda je volána součást zobrazení s prioritou 4 nebo vyšší.

Prozkoumání cesty zobrazení

• Změňte parametr priority na tři nebo méně, takže se nevrátí zobrazení priority.

• Dočasně přejmenujte Views/ToDo/Components/PriorityList/Default.cshtml na 1Default.cshtml.

• Otestujte aplikaci, dojde k následující chybě:

  An unhandled exception occurred while processing the request.
  InvalidOperationException: The view 'Components/PriorityList/Default' wasn't found. The following locations were searched:
  /Views/ToDo/Components/PriorityList/Default.cshtml
  /Views/Shared/Components/PriorityList/Default.cshtml
  

• Zkopírujte soubor Views/ToDo/Components/PriorityList/1Default.cshtml do složky Views/Shared/Components/PriorityList/Default.cshtml.

• Přidejte do zobrazení komponenty zobrazení Sdílené toDo nějaké revize, které indikují, že zobrazení je ze sdílené složky.

• Otestujte zobrazení sdílené komponenty.

Vyhněte se pevně zakódovaným řetězcům

Pro zabezpečení doby kompilace nahraďte pevně zakódovaný název komponenty zobrazení názvem třídy. Aktualizujte soubor PriorityListViewComponent.cs tak, aby nepoužít příponu ViewComponent:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using ViewComponentSample.Models;

namespace ViewComponentSample.ViewComponents;

public class PriorityList : ViewComponent
{
    private readonly ToDoContext db;

    public PriorityList(ToDoContext context)
    {
        db = context;
    }

    public async Task<IViewComponentResult> InvokeAsync(
                                               int maxPriority, bool isDone)
    {
        var items = await GetItemsAsync(maxPriority, isDone);
        return View(items);
    }

    private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
    {
        return db!.ToDo!.Where(x => x.IsDone == isDone &&
                             x.Priority <= maxPriority).ToListAsync();
    }
}

Soubor zobrazení :

</table>

<div>
    Testing nameof(PriorityList) <br />

    Maxium Priority: @ViewData["maxPriority"] <br />
    Is Complete:  @ViewData["isDone"]
    @await Component.InvokeAsync(nameof(PriorityList),
                     new { 
                         maxPriority =  ViewData["maxPriority"],
                         isDone = ViewData["isDone"]  }
                     )
</div>

Přetížení Component.InvokeAsync metody, která přebírá typ CLR, používá typeof operátor:

</table>

<div>
    Testing typeof(PriorityList) <br />

    Maxium Priority: @ViewData["maxPriority"] <br />
    Is Complete:  @ViewData["isDone"]
    @await Component.InvokeAsync(typeof(PriorityList),
                     new { 
                         maxPriority =  ViewData["maxPriority"],
                         isDone = ViewData["isDone"]  }
                     )
</div>

Provádění synchronní práce

Architektura zpracovává vyvolání synchronní Invoke metody, pokud není vyžadována asynchronní práce. Následující metoda vytvoří synchronní Invoke komponentu zobrazení:

using Microsoft.AspNetCore.Mvc;
using ViewComponentSample.Models;

namespace ViewComponentSample.ViewComponents
{
    public class PriorityListSync : ViewComponent
    {
        private readonly ToDoContext db;

        public PriorityListSync(ToDoContext context)
        {
            db = context;
        }

        public IViewComponentResult Invoke(int maxPriority, bool isDone)
        {
 
            var x = db!.ToDo!.Where(x => x.IsDone == isDone &&
                                  x.Priority <= maxPriority).ToList();
            return View(x);
        }
    }
}

Soubor komponenty Razor zobrazení:

<div>
    Testing nameof(PriorityList) <br />

    Maxium Priority: @ViewData["maxPriority"] <br />
    Is Complete:  @ViewData["isDone"]
    @await Component.InvokeAsync(nameof(PriorityListSync),
                     new { 
                         maxPriority =  ViewData["maxPriority"],
                         isDone = ViewData["isDone"]  }
                     )
</div>

Komponenta Razor zobrazení se vyvolá v souboru (například Views/Home/Index.cshtml) pomocí jednoho z následujících přístupů:

• IViewComponentHelper
• Pomocná rutina značek

Pokud chcete použít IViewComponentHelper přístup, zavolejte Component.InvokeAsync:

@await Component.InvokeAsync(nameof(PriorityList),
                             new { maxPriority = 4, isDone = true })

Chcete-li použít pomocné rutiny značek, zaregistrujte sestavení obsahující součást Zobrazení pomocí direktivy @addTagHelper (součást zobrazení je v sestavení s názvem MyWebApp):

@addTagHelper *, MyWebApp

V souboru značek použijte pomocné rutiny značky Razor komponenty zobrazení:

<vc:priority-list max-priority="999" is-done="false">
</vc:priority-list>

Podpis PriorityList.Invoke metody je synchronní, ale Razor najde a volá metodu v Component.InvokeAsync souboru značek.

Další prostředky

• Zobrazení nebo stažení ukázkového kódu (postup stažení)
• Injektáž závislostí do zobrazení
• Zobrazení součástí na Razor stránkách
• Proč byste měli v ASP.NET jádru používat komponenty zobrazení, nikoli částečná zobrazení