Pomocnicy tagów na platformie ASP.NET Core

Autor: Rick Anderson

Co to są pomocnicy tagów

Pomocnicy tagów umożliwiają udział w tworzeniu i renderowaniu elementów HTML w Razor plikach po stronie serwera. Na przykład wbudowana ImageTagHelper funkcja może dołączyć numer wersji do nazwy obrazu. Za każdym razem, gdy obraz zmieni się, serwer generuje nową unikatową wersję obrazu, więc klienci mają gwarancję pobrania bieżącego obrazu (zamiast nieaktualnego obrazu w pamięci podręcznej). Istnieje wiele wbudowanych pomocników tagów dla typowych zadań — takich jak tworzenie formularzy, linków, ładowanie zasobów i nie tylko — a nawet bardziej dostępne w publicznych repozytoriach GitHub i jako pakiety NuGet. Pomocnicy tagów są autorami w języku C#, a elementami docelowymi są elementy HTML na podstawie nazwy elementu, nazwy atrybutu lub tagu nadrzędnego. Na przykład wbudowany LabelTagHelper element może być przeznaczony dla elementu HTML <label> po zastosowaniu LabelTagHelper atrybutów. Jeśli znasz pomocników HTML, pomocnicy tagów zmniejszają jawne przejścia między kodami HTML i C# w Razor widokach. W wielu przypadkach pomocnicy HTML zapewniają alternatywne podejście do określonego pomocnika tagów, ale ważne jest, aby rozpoznać, że pomocnicy tagów nie zastępują pomocników HTML i nie ma pomocnika tagów dla każdego pomocnika HTML. Pomocnicy tagów w porównaniu z pomocnikami HTML wyjaśniają bardziej szczegółowo różnice.

Pomocnicy tagów nie są obsługiwani w Razor składnikach. Aby uzyskać więcej informacji, zobacz ASP.NET Podstawowe Razor składniki.

Co zapewniają pomocnicy tagów

Środowisko programistyczne przyjazne dla języka HTML

W większości Razor przypadków znaczniki używające pomocników tagów wyglądają jak standardowy kod HTML. Projektanci frontonu konwersujący z językiem HTML/CSS/JavaScript mogą edytować Razor bez uczenia się składni języka C# Razor .

Rozbudowane środowisko IntelliSense do tworzenia kodu HTML i Razor znaczników

Jest to ostry kontrast dla pomocników HTML, poprzednie podejście do tworzenia znaczników po stronie serwera w Razor widokach. Pomocnicy tagów w porównaniu z pomocnikami HTML wyjaśniają bardziej szczegółowo różnice. Obsługa funkcji IntelliSense dla pomocników tagów wyjaśnia środowisko IntelliSense. Nawet deweloperzy doświadczeni w Razor składni języka C# są bardziej wydajni przy użyciu pomocników tagów niż pisanie znaczników w języku C# Razor .

Sposób na zwiększenie produktywności i możliwości tworzenia bardziej niezawodnego, niezawodnego i konserwowalnego kodu przy użyciu informacji dostępnych tylko na serwerze

Na przykład historycznie mantra aktualizowania obrazów miała na celu zmianę nazwy obrazu podczas zmiany obrazu. Obrazy powinny być agresywnie buforowane ze względu na wydajność, a jeśli nie zmienisz nazwy obrazu, ryzykujesz, że klienci otrzymują nieaktualną kopię. W przeszłości po zmodyfikowaniu obrazu nazwa musiała zostać zmieniona, a każde odwołanie do obrazu w aplikacji internetowej musi zostać zaktualizowane. Nie tylko jest to bardzo pracochłonne, ale także podatne na błędy (można przegapić odwołanie, przypadkowo wprowadzić nieprawidłowy ciąg itp.) ImageTagHelper Wbudowana funkcja może to zrobić automatycznie. Element ImageTagHelper może dołączyć numer wersji do nazwy obrazu, więc za każdym razem, gdy obraz zmieni się, serwer automatycznie wygeneruje nową unikatową wersję obrazu. Klienci mają gwarancję pobrania bieżącego obrazu. Ta niezawodność i oszczędności pracy są zasadniczo wolne za pomocą .ImageTagHelper

Większość wbudowanych pomocników tagów jest ukierunkowana na standardowe elementy HTML i udostępnia atrybuty po stronie serwera dla elementu. Na przykład <input> element używany w wielu widokach w folderze Views/Account zawiera asp-for atrybut . Ten atrybut wyodrębnia nazwę określonej właściwości modelu do renderowanego kodu HTML. Razor Rozważ widok z następującym 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 Następujące znaczniki:

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

Generuje następujący kod HTML:

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

Atrybut asp-for jest udostępniany przez For właściwość w obiekcie LabelTagHelper. Aby uzyskać więcej informacji, zobacz Author Tag Helpers (Tworzenie pomocników tagów ).

Zarządzanie zakresem pomocnika tagów

Zakres pomocników tagów jest kontrolowany przez kombinację znaków @addTagHelper, @removeTagHelperi znaku "!" z rezygnacją.

@addTagHelper udostępnia pomocników tagów

Jeśli utworzysz nową aplikację internetową ASP.NET Core o nazwie AuthoringTagHelpers, do projektu zostanie dodany następujący Views/_ViewImports.cshtml plik:

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

Dyrektywa @addTagHelper udostępnia pomocników tagów do widoku. W takim przypadku plik widoku to Pages/_ViewImports.cshtml, który domyślnie jest dziedziczony przez wszystkie pliki w folderze Pages i podfolderach, dzięki czemu są dostępne pomocnicy tagów. Powyższy kod używa składni symboli wieloznacznych ("*"), aby określić, że wszyscy pomocnicy tagów w określonym zestawie (Microsoft.AspNetCore.Mvc.TagHelpers) będą dostępne dla każdego pliku widoku w katalogu Views lub podkatalogu. Pierwszy parametr po @addTagHelper określa pomocników tagów do załadowania (używamy "*" dla wszystkich pomocników tagów) i drugi parametr "Microsoft.AspNetCore.Mvc.TagHelpers" określa zestaw zawierający pomocników tagów. Microsoft.AspNetCore.Mvc.TagHelpers to zestaw wbudowanych pomocników tagów core ASP.NET.

Aby uwidocznić wszystkich pomocników tagów w tym projekcie (co tworzy zestaw o nazwie AuthoringTagHelpers), należy użyć następujących elementów:

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

Jeśli projekt zawiera element EmailTagHelper z domyślną przestrzenią nazw (AuthoringTagHelpers.TagHelpers.EmailTagHelper), możesz podać w pełni kwalifikowaną nazwę (FQN) pomocnika tagów:

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

Aby dodać pomocnika tagów do widoku przy użyciu nazwy FQN, najpierw dodaj nazwę FQN (AuthoringTagHelpers.TagHelpers.EmailTagHelper), a następnie nazwę zestawu (AuthoringTagHelpers). Większość deweloperów woli używać składni symboli wieloznacznych "*". Składnia symboli wieloznacznych umożliwia wstawianie symbolu wieloznakowego "*" jako sufiksu w FQN. Na przykład każda z poniższych dyrektyw wprowadzi element EmailTagHelper:

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

Jak wspomniano wcześniej, dodanie @addTagHelper dyrektywy do Views/_ViewImports.cshtml pliku sprawia, że pomocnik tagów jest dostępny dla wszystkich plików widoku w katalogu Views i podkatalogach. Możesz użyć @addTagHelper dyrektywy w określonych plikach widoku, jeśli chcesz wyrazić zgodę na uwidacznianie pomocnika tagów tylko dla tych widoków.

@removeTagHelper usuwa pomocników tagów

Parametr @removeTagHelper ma te same dwa parametry co @addTagHelperelement i usuwa pomocnika tagów, który został wcześniej dodany. Na przykład @removeTagHelper zastosowane do określonego widoku usuwa określony pomocnik tagów z widoku. Użycie @removeTagHelper w Views/Folder/_ViewImports.cshtml pliku usuwa określony pomocnik tagów ze wszystkich widoków w folderze.

Kontrolowanie zakresu pomocnika tagów za pomocą _ViewImports.cshtml pliku

Można dodać element _ViewImports.cshtml do dowolnego folderu widoku, a aparat widoków stosuje dyrektywy zarówno z tego pliku, jak Views/_ViewImports.cshtml i pliku. W przypadku dodania pustego Views/Home/_ViewImports.cshtml pliku dla Home widoków nie będzie żadnych zmian, ponieważ _ViewImports.cshtml plik jest dodawany. Wszystkie @addTagHelper dyrektywy dodawane do Views/Home/_ViewImports.cshtml pliku (które nie znajdują się w pliku domyślnym Views/_ViewImports.cshtml ) uwidaczniają te pomocniki tagów tylko w widokach w folderze Home .

Rezygnacja z poszczególnych elementów

Pomocnik tagów można wyłączyć na poziomie elementu z znakiem rezygnacji pomocnika tagów ("!"). Na przykład Email walidacja jest wyłączona w elemecie <span> z znakiem rezygnacji pomocnika tagów:

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

Musisz zastosować znak rezygnacji pomocnika tagu do tagu otwierającego i zamykającego. (Edytor programu Visual Studio automatycznie dodaje znak rezygnacji do tagu zamykającego po dodaniu go do tagu otwierającego). Po dodaniu znaku rezygnacji atrybuty elementu i pomocnika tagów nie są już wyświetlane w charakterystycznej czcionki.

Używanie @tagHelperPrefix do jawnego użycia pomocnika tagów

Dyrektywa @tagHelperPrefix umożliwia określenie ciągu prefiksu tagu w celu włączenia obsługi pomocnika tagów i jawnego użycia pomocnika tagów. Możesz na przykład dodać następujący znacznik do Views/_ViewImports.cshtml pliku:

@tagHelperPrefix th:

Na poniższej ilustracji kodu prefiks pomocnika tagów jest ustawiony na th:, więc tylko te elementy używające prefiksu th: obsługują pomocników tagów (elementy pomocnika tagów mają charakterystyczną czcionkę). <label> Elementy i <input> mają prefiks Pomocnika tagów i są włączone pomocnika tagów<span>, a element nie.

Te same reguły hierarchii, które mają zastosowanie @addTagHelper również do @tagHelperPrefixprogramu .

Pomocnicy tagów samodzielnie zamykających

Wielu pomocników tagów nie może być używanych jako tagi zamykające się samodzielnie. Niektóre pomocniki tagów są przeznaczone do samodzielnego zamykania tagów. Użycie pomocnika tagów, który nie został zaprojektowany do samodzielnego zamykania pomija renderowane dane wyjściowe. Samodzielne zamykanie pomocnika tagów powoduje samozamknięcie tagu w renderowanych danych wyjściowych. Aby uzyskać więcej informacji, zobacz tę notatkę w temacie Authoring Tag Helpers (Pomocnicy tagów tworzenia).

C# w atrybucie/deklaracji pomocników tagów

Pomocnicy tagów nie zezwalają na język C# w obszarze atrybutu lub deklaracji tagu elementu. Na przykład następujący kod jest nieprawidłowy:

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

Powyższy kod można napisać jako:

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

@ Zwykle operator wstawia tekstową reprezentację wyrażenia do renderowanego znacznika HTML. Jednak gdy wyrażenie zwróci wartość logiczną false, struktura usuwa atrybut. W poprzednim przykładzie disabled atrybut jest ustawiany na true wartość , jeśli Model element lub LicenseId ma nullwartość .

Inicjatory pomocnika tagów

Chociaż atrybuty mogą służyć do konfigurowania poszczególnych wystąpień pomocników tagów, ITagHelperInitializer<TTagHelper> można użyć do skonfigurowania wszystkich wystąpień pomocnika tagów określonego rodzaju. Rozważmy następujący przykład inicjatora pomocnika tagów, który konfiguruje asp-append-version atrybut lub AppendVersion właściwość dla wszystkich wystąpień ScriptTagHelper w aplikacji:

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

Aby użyć inicjatora, skonfiguruj go, rejestrując go w ramach uruchamiania aplikacji:

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

Automatyczne generowanie wersji pomocnika tagów poza witryną wwwroot

Aby pomocnik tagów wygenerował wersję pliku statycznego poza wwwrootprogramem , zobacz Obsługa plików z wielu lokalizacji

Obsługa funkcji IntelliSense dla pomocników tagów

Rozważ napisanie elementu HTML <label> . Po wprowadzeniu <l w edytorze programu Visual Studio funkcja IntelliSense wyświetla pasujące elementy:

Nie tylko otrzymujesz pomoc HTML, ale także ikonę (symbol "@" z<> "" pod nim).

Ikona identyfikuje element jako docelowy przez pomocników tagów. Czyste elementy HTML (takie jak fieldset) wyświetlają ikonę "<>".

Czysty tag HTML <label> wyświetla tag HTML (z domyślnym motywem kolorów programu Visual Studio) w brązowej czcionki, atrybutach na czerwono i wartości atrybutów w kolorze niebieskim.

Po wprowadzeniu funkcji <labelIntelliSense wyświetla dostępne atrybuty HTML/CSS i atrybuty docelowe pomocnika tagów:

Uzupełnianie instrukcji IntelliSense umożliwia wprowadzenie klawisza tab, aby ukończyć instrukcję z wybraną wartością:

Gdy tylko zostanie wprowadzony atrybut Pomocnika tagów, czcionki tagów i atrybutów zostaną zmienione. Przy użyciu domyślnego motywu kolorów programu Visual Studio "Niebieski" lub "Jasny" czcionka jest pogrubiona purpurowo. Jeśli używasz motywu "Ciemny", czcionka jest pogrubiona. Obrazy w tym dokumencie zostały zrobione przy użyciu motywu domyślnego.

Możesz wprowadzić skrót CompleteWord programu Visual Studio (Ctrl +spacja jest domyślny) wewnątrz podwójnych cudzysłowów (""), a teraz jesteś w języku C#, tak jak w klasie C#. Funkcja IntelliSense wyświetla wszystkie metody i właściwości w modelu strony. Metody i właściwości są dostępne, ponieważ typ właściwości to ModelExpression. Na poniższej ilustracji edytuję Register widok, więc RegisterViewModel jest dostępny.

Funkcja IntelliSense wyświetla listę właściwości i metod dostępnych dla modelu na stronie. Rozbudowane środowisko IntelliSense pomaga wybrać klasę CSS:

Pomocnicy tagów w porównaniu z pomocnikami HTML

Pomocnicy tagów dołączają do elementów HTML w Razor widokach, a pomocnicy HTML są wywoływani jako metody przeplatane kodem HTML w Razor widokach. Rozważmy następujący Razor znacznik, który tworzy etykietę HTML z klasą CSS "podpis":

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

Symbol at (@) informuje Razor , że jest to początek kodu. Dwa następne parametry ("FirstName" i "First Name:") są ciągami, więc funkcja IntelliSense nie może pomóc. Ostatni argument:

new {@class="caption"}

Jest obiektem anonimowym używanym do reprezentowania atrybutów. Ponieważ class jest zastrzeżonym słowem kluczowym w języku C#, należy użyć symbolu @ , aby wymusić interpretację @class= języka C# jako symbolu (nazwy właściwości). Do projektanta frontonu (ktoś zaznajomiony z językiem HTML/CSS/JavaScript i innymi technologiami klienckimi, ale nie zna języka C# i Razor), większość wiersza jest obca. Cały wiersz musi być utworzony bez pomocy funkcji IntelliSense.

LabelTagHelperZa pomocą elementu można napisać ten sam znacznik co:

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

Po wprowadzeniu <l wersji pomocnika tagów w edytorze programu Visual Studio funkcja IntelliSense wyświetla pasujące elementy:

Funkcja IntelliSense ułatwia pisanie całego wiersza.

Poniższy obraz kodu przedstawia część Views/Account/Register.cshtmlRazor formularza widoku wygenerowanego na podstawie szablonu MVC ASP.NET 4.5.x dołączonego do programu Visual Studio.

Edytor programu Visual Studio wyświetla kod języka C# z szarym tłem. Na przykład AntiForgeryToken pomocnik HTML:

@Html.AntiForgeryToken()

jest wyświetlany z szarym tłem. Większość znaczników w widoku Rejestrowanie to C#. Porównaj to z równoważnym podejściem przy użyciu pomocników tagów:

Znaczniki są znacznie bardziej czytelne i łatwiejsze do odczytania, edytowania i obsługi niż podejście pomocników HTML. Kod języka C# jest ograniczony do minimum, o czym serwer musi wiedzieć. Edytor programu Visual Studio wyświetla znaczniki przeznaczone dla pomocnika tagów w charakterystycznej czcionki.

Rozważ grupę Wiadomości 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żdy z atrybutów "asp-" ma wartość "Email", ale "Email" nie jest ciągiem. W tym kontekście wartość "Email" jest właściwością wyrażenia modelu języka C# dla elementu RegisterViewModel.

Edytor programu Visual Studio ułatwia pisanie wszystkich znaczników w podejściu pomocnika tagów formularza rejestracji, podczas gdy program Visual Studio nie zapewnia pomocy dla większości kodu w podejściu pomocników HTML. Obsługa funkcji IntelliSense dla pomocników tagów szczegółowo omawia pracę z pomocnikami tagów w edytorze programu Visual Studio.

Pomocnicy tagów w porównaniu z kontrolkami serwera sieci Web

• Pomocnicy tagów nie są właścicielami elementu, z którymi są skojarzeni; po prostu uczestniczą w renderowaniu elementu i zawartości. ASP.NET kontrolki serwera sieci Web są deklarowane i wywoływane na stronie.

• ASP.NET kontrolki serwera sieci Web mają nietrywialny cykl życia, który może utrudnić opracowywanie i debugowanie.

• Kontrolki serwera sieci Web umożliwiają dodawanie funkcji do elementów MODELU DOM klienta przy użyciu kontrolki klienta. Pomocnicy tagów nie mają modelu DOM.

• Kontrolki serwera sieci Web obejmują automatyczne wykrywanie przeglądarki. Pomocnicy tagów nie mają wiedzy na temat przeglądarki.

• Wielu pomocników tagów może działać na tym samym elemecie (zobacz Unikanie konfliktów pomocnika tagów), podczas gdy zwykle nie można tworzyć kontrolek serwera sieci Web.

• Pomocnicy tagów mogą modyfikować tag i zawartość elementów HTML, do których mają zakres, ale nie modyfikują bezpośrednio niczego innego na stronie. Kontrolki serwera sieci Web mają mniej określony zakres i mogą wykonywać akcje wpływające na inne części strony; włączenie niezamierzonych skutków ubocznych.

• Kontrolki serwera sieci Web używają konwerterów typów do konwertowania ciągów na obiekty. W przypadku pomocników tagów pracujesz natywnie w języku C#, więc nie musisz wykonywać konwersji typów.

• Kontrolki serwera sieci Web służą System.ComponentModel do implementowania zachowania czasu wykonywania i czasu projektowania składników i kontrolek. System.ComponentModel zawiera klasy podstawowe i interfejsy do implementowania atrybutów i konwerterów typów, powiązania ze źródłami danych i składnikami licencjonowania. Z kolei do pomocników tagów, które zwykle pochodzą z TagHelperklasy , a TagHelper klasa bazowa uwidacznia tylko dwie metody i ProcessProcessAsync.

Dostosowywanie czcionki elementu Pomocnika tagów

Czcionkę i kolorowanie można dostosować w obszarze Narzędzia>Opcje>czcionki i kolory środowiska:>

Wbudowani pomocnicy tagów na platformie ASP.NET Core

Kotwica

Cache

Składnik

Rozproszona pamięć podręczna

Środowisko

Formularz

Akcja formularza

Obraz

Dane wejściowe

Etykieta

Link

Partial

Stan trwały składnika

Skrypt

Wybieranie

Obszar tekstu

Komunikat walidacji

Podsumowanie walidacji

Dodatkowe zasoby

• Pomocnicy tagów autora
• Praca z formularzami
• TagHelperSamples w witrynie GitHub zawiera przykłady pomocnika tagów do pracy z narzędziem Bootstrap.