Pomocné rutiny značek v ASP.NET Core

Článek
11/30/2023

Co jsou pomocné rutiny značek

Pomocné rutiny značek umožňují, aby se účastnili vytváření a vykreslování elementů HTML v Razor souborech. Například předdefinovaný ImageTagHelper může k názvu image připojit číslo verze. Pokaždé, když se image změní, server vygeneruje novou jedinečnou verzi image, takže klienti budou mít zaručené získání aktuální image (místo zastaralé image uložené v mezipaměti). Existuje mnoho předdefinovaných pomocných rutin značek pro běžné úlohy , jako jsou vytváření formulářů, odkazů, načítání prostředků a další – a ještě více dostupných ve veřejných úložištích GitHubu a jako balíčky NuGet. Pomocné rutiny značek jsou vytvořené v jazyce C# a cílí na elementy HTML na základě názvu elementu, názvu atributu nebo nadřazené značky. Například předdefinovaný LabelTagHelper může cílit na element HTML <label> při LabelTagHelper použití atributů. Pokud znáte pomocné rutiny HTML, pomocné rutiny značek zmenšují explicitní přechody mezi HTML a C# v Razor zobrazeních. V mnoha případech poskytují pomocné rutiny HTML alternativní přístup ke konkrétním pomocným rutině značek, ale je důležité si uvědomit, že pomocné rutiny značky nenahrazovat pomocné rutiny HTML a pro každého pomocníka HTML není pomocník značky. Pomocné rutiny značek ve srovnání s pomocnými rutinami HTML podrobněji vysvětlují rozdíly.

Pomocné rutiny značek nejsou podporovány v Razor součástech. Další informace najdete v tématu ASP.NET základní Razor komponenty.

Jaké pomocné rutiny značek poskytují

Prostředí pro vývoj vhodné pro HTML

Ve většině případů Razor značky pomocí pomocných rutin značek vypadá jako standardní HTML. Návrháři front-endu konversantní s HTML/CSS/JavaScriptem můžou upravovat Razor bez učení syntaxe jazyka C# Razor .

Bohaté prostředí IntelliSense pro vytváření HTML a Razor revizí

To je v ostrém kontrastu s pomocnými rutiny HTML, předchozí přístup k vytváření revizí na straně serveru v Razor zobrazeních. Pomocné rutiny značek ve srovnání s pomocnými rutinami HTML podrobněji vysvětlují rozdíly. Podpora Technologie IntelliSense pro pomocné rutiny značek vysvětluje prostředí IntelliSense. Dokonce i vývojáři se Razor syntaxí jazyka C# jsou produktivnější pomocí pomocných rutin značek než psaní značek C# Razor .

Způsob, jak zvýšit produktivitu a schopnost vytvářet robustnější, spolehlivější a udržovatelný kód s využitím informací dostupných pouze na serveru

Například v minulosti byla mantra při aktualizaci obrázků při změně názvu obrázku změněna. Image by se měly agresivně ukládat do mezipaměti z důvodů výkonu a pokud nezměníte název image, riskujete, že klienti zdají zastaralou kopii. Po úpravě obrázku bylo v minulosti nutné změnit název a každý odkaz na obrázek ve webové aplikaci je potřeba aktualizovat. Nejen že je to velmi náročné na práci, je to také náchylné k chybám (mohli byste vynechat odkaz, omylem zadat nesprávný řetězec atd.). ImageTagHelper Integrované funkce vám to umožní automaticky. Číslo ImageTagHelper verze může k názvu image připojit, takže při každé změně image server automaticky vygeneruje novou jedinečnou verzi image. Klienti mají zaručené získání aktuální image. Tato robustnost a úspory práce jsou v podstatě zdarma pomocí ImageTagHelper.

Většina integrovaných pomocných rutin značek cílí na standardní elementy HTML a poskytuje atributy na straně serveru pro element. Například <input> prvek použitý v mnoha zobrazeních ve složce Views/Account obsahuje asp-for atribut. Tento atribut extrahuje název zadané vlastnosti modelu do vykresleného kódu HTML. Razor Zvažte zobrazení s následujícím modelem:

public class Movie
{
    public int ID { get; set; }
    public string Title { get; set; }
    public DateTime ReleaseDate { get; set; }
    public string Genre { get; set; }
    public decimal Price { get; set; }
}

Razor Následující kód:

<label asp-for="Movie.Title"></label>

Generuje následující kód HTML:

<label for="Movie_Title">Title</label>

Atribut asp-for je zpřístupněn For vlastností v objektu LabelTagHelper. Další informace najdete v tématu Pomocné rutiny značek pro autory .

Správa oboru pomocné rutiny značek

Rozsah pomocných rutin značek je řízen kombinací znaku @addTagHelper, @removeTagHelper, a znaku "!" odhlášení.

`@addTagHelper` zpřístupňuje pomocné rutiny značek.

Pokud vytvoříte novou webovou aplikaci ASP.NET Core s názvem AuthoringTagHelpers, do projektu se přidá následující Views/_ViewImports.cshtml soubor:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

Direktiva @addTagHelper zpřístupňuje pomocné rutiny značek pro zobrazení. V tomto případě je Pages/_ViewImports.cshtmlsoubor zobrazení , který ve výchozím nastavení dědí všechny soubory ve složce Stránky a podsložky; zpřístupňuje pomocné rutiny značek. Výše uvedený kód používá syntaxi zástupných znaků (*) k určení, že všechny pomocné rutiny značek v zadaném sestavení (Microsoft.AspNetCore.Mvc.TagHelpers) budou k dispozici pro každý soubor zobrazení v adresáři Zobrazení nebo podadresáři. První parametr po @addTagHelper zadání pomocných rutin značek k načtení (používáme "*" pro všechny pomocné rutiny značek) a druhý parametr "Microsoft.AspNetCore.Mvc.TagHelpers" určuje sestavení obsahující pomocné rutiny značek. Microsoft.AspNetCore.Mvc.TagHelpers je sestavení pro integrované pomocné rutiny značek ASP.NET Core.

K zveřejnění všech pomocných rutin značek v tomto projektu (který vytvoří sestavení s názvem AuthoringTagHelpers), byste použili následující:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

Pokud váš projekt obsahuje EmailTagHelper výchozí obor názvů (AuthoringTagHelpers.TagHelpers.EmailTagHelper), můžete zadat plně kvalifikovaný název (FQN) pomocné rutiny značek:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

Pokud chcete přidat pomocníka značky do zobrazení pomocí plně kvalifikovaného názvu domény, nejprve přidejte plně kvalifikovaný název domény (AuthoringTagHelpers.TagHelpers.EmailTagHelperFQN) a pak název sestavení (AuthoringTagHelpers). Většina vývojářů preferuje použití syntaxe zástupných znaků "*". Syntaxe zástupných znaků umožňuje vložit zástupný znak "*" jako příponu do plně kvalifikovaného názvu domény. Například některá z následujících direktiv bude mít následující EmailTagHelper:

@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers

Jak už bylo zmíněno dříve, přidání @addTagHelper direktivy do Views/_ViewImports.cshtml souboru zpřístupňuje pomocné rutiny značek všem souborům zobrazení v adresáři Zobrazení a podadresářích. Direktivu @addTagHelper můžete použít v konkrétních souborech zobrazení, pokud chcete vyjádřit výslovný souhlas s zveřejněním pomocné rutiny značek pouze těmto zobrazením.

`@removeTagHelper` odebere pomocné rutiny značek.

Má @removeTagHelper stejné dva parametry jako @addTagHelpera odebere pomocnou rutinu značky, která byla přidána dříve. @removeTagHelper Například použitý u konkrétního zobrazení odebere ze zobrazení zadanou pomocnou rutinu značek. Použití @removeTagHelper v Views/Folder/_ViewImports.cshtml souboru odebere zadanou pomocnou rutinu značek ze všech zobrazení ve složce.

Řízení oboru pomocné rutiny značek pomocí `_ViewImports.cshtml` souboru

Můžete přidat _ViewImports.cshtml do libovolné složky zobrazení a modul zobrazení použije direktivy z tohoto souboru i Views/_ViewImports.cshtml souboru. Pokud jste přidali prázdný Views/Home/_ViewImports.cshtml soubor pro Home zobrazení, nedošlo by k žádné změně, protože _ViewImports.cshtml soubor je sčítá. Všechny @addTagHelper direktivy, které přidáte do Views/Home/_ViewImports.cshtml souboru (které nejsou ve výchozím Views/_ViewImports.cshtml souboru), by tyto pomocné rutiny značek zpřístupnily pouze zobrazení ve Home složce.

Odhlášení z jednotlivých prvků

Pomocnou rutinu značek můžete zakázat na úrovni elementu pomocí znaku odhlasování značek ("!"). Ověření je například Email zakázáno v pomocném znaku <span> značky:

<!span asp-validation-for="Email" class="text-danger"></!span>

Pro levou a pravou značku musíte použít znak odhlašovacího znaku pomocníka značky. (Editor sady Visual Studio automaticky přidá znak odhlášení do uzavírací značky, když ho přidáte do počáteční značky). Po přidání znaku odhlášení se už atributy elementu a pomocné rutiny značek nezobrazují v odlišném písmu.

Použití `@tagHelperPrefix` k explicitnímu použití pomocných rutin značek

Tato @tagHelperPrefix direktiva umožňuje zadat řetězec předpony značky, který povolí podporu pomocných rutin značek a explicitní použití pomocné rutiny značek. Do souboru můžete například přidat následující kód Views/_ViewImports.cshtml :

@tagHelperPrefix th:

Na obrázku kódu níže je předpona Pomocné rutiny značky nastavená na th:, takže pouze ty prvky používající pomocné rutiny značek th: podporují (pomocné prvky značky mají výrazný písmo). <input> Prvky <label> mají předponu Pomocné rutiny značek a jsou povoleny pomocné rutiny <span> značek, zatímco prvek ne.

Razor markup with Tag Helper prefix set to

Stejná pravidla hierarchie, která platí také pro @addTagHelper@tagHelperPrefix.

Pomocné rutiny značek samozavírací

Mnoho pomocných rutin značek se nedá použít jako samozavírací značky. Některé pomocné rutiny značek jsou navržené jako samozavírací značky. Použití pomocné rutiny značky, která nebyla navržena tak, aby se sama zavřela, potlačuje vykreslený výstup. Při samovírání pomocné rutiny značky vznikne ve vykresleném výstupu značka samozavírací značky. Další informace najdete v této poznámce v pomocných rutinách značek pro vytváření.

C# v atributu nebo deklaraci pomocných rutin značek

Pomocné rutiny značek neumožňují jazyk C# v oblasti atributu elementu nebo deklarace značky. Například následující kód není platný:

<input asp-for="LastName"  
       @(Model?.LicenseId == null ? "disabled" : string.Empty) />

Předchozí kód lze napsat takto:

<input asp-for="LastName" 
       disabled="@(Model?.LicenseId == null)" />

@ Operátor obvykle vloží textovou reprezentaci výrazu do vykresleného kódu HTML. Pokud se však výraz vyhodnotí jako logický false, architektura místo toho odebere atribut. V předchozím příkladu disabled je atribut nastaven na true hodnotu, pokud je nebo ModelLicenseId je null.

Inicializátory pomocných rutin značek

Atributy lze použít ke konfiguraci jednotlivých instancí pomocných rutin značek, ITagHelperInitializer<TTagHelper> lze je použít ke konfiguraci všech pomocných instancí značek určitého druhu. Představte si následující příklad inicializátoru pomocných rutin značek, který nakonfiguruje asp-append-version atribut nebo AppendVersion vlastnost pro všechny instance ScriptTagHelper v aplikaci:

public class AppendVersionTagHelperInitializer : ITagHelperInitializer<ScriptTagHelper>
{
    public void Initialize(ScriptTagHelper helper, ViewContext context)
    {
        helper.AppendVersion = true;
    }
}

Pokud chcete inicializátor použít, nakonfigurujte ho tak, že ho zaregistrujete jako součást spuštění aplikace:

builder.Services.AddSingleton
    <ITagHelperInitializer<ScriptTagHelper>, AppendVersionTagHelperInitializer>();

Automatické generování verzí značek mimo wwwroot

Pomocná rutina značek, která vygeneruje verzi statického souboru mimo wwwroot, najdete v tématu Obsluha souborů z více umístění.

Podpora IntelliSense pro pomocné rutiny značek

Zvažte vytvoření elementu HTML <label> . Jakmile zadáte <l do editoru sady Visual Studio, IntelliSense zobrazí odpovídající prvky:

After typing

Nejen, že získáte nápovědu HTML, ale také ikonu (symbol @s "<>" pod ním).

The

Ikona identifikuje prvek určený pomocnými rutinami značek. Čisté elementy HTML (například fieldset) zobrazují ikonu "<>".

Čistá značka HTML zobrazí značku HTML <label> (s výchozím barevným motivem sady Visual Studio) v hnědém písmu, atributy červeně a hodnoty atributů modře.

Example

Po zadání <labelfunkce IntelliSense zobrazí seznam dostupných atributů HTML/CSS a atributů cílených na pomocné rutiny značek:

The user has typed an opening bracket and the HTML element name

Doplňování příkazů IntelliSense umožňuje zadat klávesu Tab k dokončení příkazu s vybranou hodnotou:

The user has typed an opening bracket, the HTML element name

Jakmile se zadá pomocný atribut značky, změní se písma značek a atributů. Pomocí výchozího barevného motivu sady Visual Studio Blue nebo Light je písmo tučné fialové. Pokud používáte tmavý motiv, písmo je tučné teální. Obrázky v tomto dokumentu byly pořízeny pomocí výchozího motivu.

The user selected

Do dvojitých uvozovek ("") můžete zadat klávesovou zkratku Visual Studio CompleteWord (Ctrl +mezerník je výchozí) a teď jste v jazyce C#, stejně jako jste ve třídě C#. IntelliSense zobrazí všechny metody a vlastnosti na modelu stránky. Metody a vlastnosti jsou k dispozici, protože typ vlastnosti je ModelExpression. Na následujícím obrázku upravujem Register zobrazení, takže RegisterViewModel je k dispozici.

The user types

IntelliSense uvádí vlastnosti a metody dostupné pro model na stránce. Bohaté prostředí IntelliSense vám pomůže vybrat třídu CSS:

The user types

Pomocné rutiny značek ve srovnání s pomocnými rutiny HTML

Pomocné rutiny značek se připojují k elementům HTML v Razor zobrazeních, zatímco pomocné rutiny HTML jsou vyvolány jako metody propletené s HTML v Razor zobrazeních. Zvažte následující Razor kód, který vytvoří popisek HTML s třídou CSS "popis":

@Html.Label("FirstName", "First Name:", new {@class="caption"})

Symbol at (@) říká Razor , že je to začátek kódu. Další dva parametry ("FirstName" a "First Name:") jsou řetězce, takže IntelliSense nemůže pomoct. Poslední argument:

new {@class="caption"}

Je anonymní objekt používaný k reprezentaci atributů. Vzhledem k tomu class , že je rezervované klíčové slovo v jazyce C#, použijete @ symbol k vynucení interpretace @class= jazyka C# jako symbolu (názvu vlastnosti). Front-endový návrhář (někdo obeznámený s HTML/CSS/JavaScriptem a dalšími klientskými technologiemi, ale není obeznámen s jazykem C# a Razor), je většina řádku cizí. Celý řádek musí být vytvořený bez pomoci intelliSense.

LabelTagHelperPomocí , stejné značky lze zapsat jako:

<label class="caption" asp-for="FirstName"></label>

Jakmile v editoru sady Visual Studio zadáte <l pomocnou verzi značek, IntelliSense zobrazí odpovídající prvky:

The user types

IntelliSense vám pomůže napsat celý řádek.

Následující obrázek kódu znázorňuje část formulářového Views/Account/Register.cshtmlRazor zobrazení vygenerovaného ze šablony ASP.NET 4.5.x MVC, která je součástí sady Visual Studio.

Razor markup for the form portion of the Register Razor view for ASP.NET 4.5 MVC project template

Editor sady Visual Studio zobrazí kód jazyka C# se šedým pozadím. Například AntiForgeryToken pomocník HTML:

@Html.AntiForgeryToken()

se zobrazí se šedým pozadím. Většina značek v zobrazení Registrace je C#. Porovnejte to s ekvivalentním přístupem pomocí pomocných rutin značek:

Razor markup with Tag Helpers for the form portion of the Register Razor view for an ASP.NET Core project template

Revize jsou mnohem přehlednější a snadněji čitelné, upravovat a udržovat než přístup pomocných rutin HTML. Kód jazyka C# je omezen na minimum, o které server potřebuje vědět. Editor sady Visual Studio zobrazuje značky cílené pomocným pomocníkem značek v odlišném písmu.

Představte si skupinu E-mail:

<div class="form-group">
    <label asp-for="Email" class="col-md-2 control-label"></label>
    <div class="col-md-10">
        <input asp-for="Email" class="form-control" />
        <span asp-validation-for="Email" class="text-danger"></span>
    </div>
</div>

Každý z atributů "asp-" má hodnotu "E-mail", ale "E-mail" není řetězec. V tomto kontextu je "Email" vlastnost výrazu modelu jazyka RegisterViewModelC# pro .

Editor sady Visual Studio vám pomůže napsat všechny značky v pomocném přístupu značek registračního formuláře, zatímco Visual Studio neposkytuje žádnou nápovědu pro většinu kódu v přístupu pomocných rutin HTML. Podpora IntelliSense pro pomocné rutiny značek podrobně pracuje s pomocnými rutinami značek v editoru sady Visual Studio.

Pomocné rutiny značek ve srovnání s ovládacími prvky webového serveru

Pomocné rutiny značek nevlastní prvek, ke kterým jsou přidruženy; jednoduše se účastní vykreslování elementu a obsahu. ASP.NET ovládací prvky webového serveru jsou deklarovány a vyvolány na stránce.
ASP.NET ovládací prvky webového serveru mají jiný než triviální životní cyklus, který může ztížit vývoj a ladění.
Ovládací prvky webového serveru umožňují přidat funkce do prvků klientského systému DOM pomocí klientského ovládacího prvku. Pomocné rutiny značek nemají žádný objekt DOM.
Ovládací prvky webového serveru zahrnují automatickou detekci prohlížeče. Pomocné rutiny značek nemají žádné znalosti prohlížeče.
Několik pomocných rutin značek může pracovat se stejným prvkem (viz Zabránění konfliktům pomocných rutin značek), zatímco obvykle nemůžete vytvářet ovládací prvky webového serveru.
Pomocné rutiny značek můžou změnit značku a obsah elementů HTML, na které mají obor, ale přímo neupravují nic jiného na stránce. Ovládací prvky webového serveru mají méně specifický obor a mohou provádět akce, které ovlivňují jiné části stránky; povolení nežádoucích vedlejších účinků.
Ovládací prvky webového serveru používají převaděče typů k převodu řetězců na objekty. S pomocnými rutinami značek pracujete nativně v jazyce C#, takže nemusíte provádět převod typů.
Ovládací prvky webového serveru slouží System.ComponentModel k implementaci chování komponent a ovládacích prvků za běhu a návrhu. System.ComponentModel obsahuje základní třídy a rozhraní pro implementaci atributů a převaděčů typů, vazby ke zdrojům dat a licenčních komponent. Na rozdíl od pomocných rutin značek, které jsou obvykle odvozeny od TagHelper, a TagHelper základní třída zveřejňuje pouze dvě metody, Process a ProcessAsync.