ASP.NET Core MVC中的標籤助手(TagHelper)用法

2022-04-14 10:00:56

1.什麼是標籤助手 Tag Helper

標籤助手是伺服器端程式碼能夠參與在 Razor 檔案中建立和呈現HTML元素。例如，內建的 ImageTagHelper 可以將版本號追加到影象名稱。無論何時更改影象，伺服器都會為影象生成新的唯一版本，因此可以保證使用者端獲取當前影象（而不是過時的快取影象）。內建的標籤助手多用於常見任務，例如建立表單，連結和載入資源等。標籤助手是在 C# 中定義的，它們基於元素名稱，屬性名稱或父標籤來定位HTML元素。例如，當應用 LabelTagHelper 特性時，內建的 LabelTagHelper 可以減少 Razor 檢視中 HTML和 C# 之間的顯示轉換。

標籤助手與HTML助手的差異：

* 標籤助手提供了一HTML友好的開發體驗

在大多數情況下，使用標籤助手的 Razor 標記看起來像標準的 HTML。如果熟悉 HTML/CSS/Javascript的話，可以直接編輯 Razor，不需要學習C#語法。

* 豐富的IntelliSence 環境，用於建立 HTML 和 Razor 標記

HTML Helper 是此前在 Razor 檢視中伺服器端建立標記的方法。IntelliSense 支援 Tag HelpersIntelliSense 解釋環境。即使有 Razor C# 語法經驗的開發人員使用 Tag Helpers ，也比使用 C# Razor 標記更有效率。

還有一種更有效率的方法，並且能夠使用盡在伺服器上提供的資訊生成更強大，可靠和可維護的程式碼。例如，以前更新影象的時候實在更改圖象時更改影象名稱。出於效能原因，應該清除快取，除非更改影象名。內建的 ImageTagHelper 可以自動更改影象名稱， ImageTagHelper 可將版本號追加到影象名稱，因此每當更改影象時，伺服器會自動為影象生成一個新的唯一的版本。保證使用者端可以獲取到當前影象。

大多數內建的標籤助手均指向現有的 HTML 元素，併為元素提供伺服器端屬性。例如，Views/Account 資料夾中許多使用的<input>元素包含 asp-for 屬性，它將指定的模型屬性的名稱提取到呈現的 HTML 中。asp-for 屬性有2 LabelTagHelper 中的 For 屬性提供。

*管理標籤助手範圍

標籤助手範圍由 @addTagHelper, @removeTagHelper 和 “！” 為推出字串的組合控制。

@addTagHelper 使標籤助手可用。預設 _ViewImports.cshtml 檔案：

@using MVCTest
@using MVCTest.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper "MVCTest.TagHelpers.EmailTagHelper,MVCTest"

上面的程式碼使用萬用字元語法（“ * ”）來指定程式集中的所有標籤助手將可用於Views目錄或子目錄中的每個檢視檔案。@addTagHelper 之後的第一個引數指定要裝載的標籤助手，第二個引數 “Microsoft.AspNetCore.Mvc.TagHelpers” 指定包含標籤助手的程式集。 Microsoft.AspNetCore.Mvc.TagHelpers 是內建的 ASP.NET Core 標籤助手的程式集。

如果你的專案包含具有預設名稱空間（AuthoringTagHelpers.TagHelpers.EmailTagHelper）的 EmailTagHelper，則可以提供標籤助手的完全限定名（FQN）：

@using MVCTest
@using MVCTest.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper  「AuthoringTagHelpers.TagHelpers.EmailTagHelper，AuthoringTagHelpers」

要想使用 FQN 向檢視新增標籤助手，請先新增 FQN （AuthoringTagHelpers.TagHelpers.EmailTagHelper），然後再新增程式集名稱（AuthoringTagHelpers）。大多數開發人員喜歡使用 “*” 萬用字元語法。萬用字元語法允許在 FQN 中插入萬用字元 “*” 作為字尾。例如：

@addTagHelper  「AuthoringTagHelpers.TagHelpers.E *，AuthoringTagHelpers」
@addTagHelper  「AuthoringTagHelpers.TagHelpers.Email *，AuthoringTagHelpers」

如果希望選擇啟用將標籤助手僅顯示給那些檢視，則可以再特定檢視中使用 @addTagHelper 指令。

* @removeTagHelper 刪除標籤助手

@removeTagHelper 具有與 @addTagHelper 相同的兩個引數，它會刪除之前新增的標籤助手。例如，應用於特定檢視的 @removeTagHelper 從檢視中刪除指定的標籤助手。在Views/Floder/_ViewImports.cshtml 檔案中使用 @removeTagHelper 從Floder 的所有檢視中刪除指定的標籤助手。

*使用 _ViewImports.cshtml 檔案控制標籤助手範圍

你可以將 ViewImports.cshtml 新增到任何檢視資料夾，並且駛入引擎將來自 ViewImports.cshtml 檔案的指令新增到 Views/ViewImports.cshtml 檔案包含的指令中。如果為 Home 檢視新增一個空的 ViewImports.cshtml 檔案，則不會有任何改變，因為 ViewImports.cshtml 檔案是疊加的。任何新增到 Views/Home/ViewImports.cshtml 檔案的 @addTagHelper 指令都會使用這些標籤助手僅顯示在Home 資料夾中。

*選擇退出個別元素

你可以使用標籤助手退出符（“ ！ ”）在元素級別停用標籤助手。例如，使用標籤助手退出符在<span>中禁用郵件驗證：

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

必須將標籤助手退出符應用於開始和結束標記。新增標籤助手退出符後，元素和標籤助手屬性不再以特殊字型顯示。

2.使用 @tagHelperPrefix 使標籤助手顯示使用

@tagHelperPrefix 指令允許你指定標籤字首字串以啟用標籤助手支援，並使標籤助手顯示使用。例如下面程式碼，標籤助手字首設定為 th: ，因此只使用字首為 th: support Tag Helper （啟用標籤助手的元素特殊字型）的元素。<label>和<input> 元素有標籤助手字首，並且啟用了標籤助手，而<sapn> 元素不啟用：

<div class="form-group">
                <th:label asp-for="Id" class="control-label"></th:label>
                <th:input asp-for="Id" class="form-control" />
                <span asp-validation-for="Id" class="text-danger"></span>
            </div>

適用於 @addTagHelper 的相同層次結構規則也是用於 @tagHelperPrefix。

當在 VS 中建立一個 web 應用時，在 project.json 檔案中新增 “Microsoft.AspNetCore.Razor.Tool”，這就是新增 Tag Helper 工具的包。

在 VS 編輯器中一輸入 <l ，智慧感知就會顯示匹配的元素。智慧感知語句允許用 Tab 鍵來輸入所選值的語句。

你可以在屬性值裡面（雙引號裡）輸入VS的CompleteWord快捷鍵（預設是Ctrl+空格），現在在C#中，就像一個C#類。智慧感知顯示頁面模型的所有方法和屬性，也可以幫助選擇CSS類。

3.標籤助手 Tag Helpers 和 HTML Helpers 比較

標籤助手是附加到 Razor 檢視中的 HTML 元素，而 HTML 助手則是在 Razor 檢視中穿插的 HTML 的方法呼叫。下面的 Razor 標記會建立一個帶 CSS 類 “caption” 的HTML標籤：

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

@符號告訴Razor這是程式碼的開始。接下來的兩個引數（“FirstName” 和 “First Name：”）是字串，因此IntelliSence 不能幫助。最後一個引數 new {@class="caption"} 是用於表示屬性的匿名物件。因為 class 是C#中的關鍵字，所以使用@符號強制C#將@class=解釋為符號。

使用LabelTagHelper，相同的標記可以寫為：

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

使用LabelTagHelper，只要在 VS 中輸入 <l ，智慧感知就會顯示匹配的元素。

下面程式碼是 VS2015 中 ASP.NET 4.5.x MVC 模板生成的 Razor 檢視表單部分：

@using (Html.BeginForm())
{
    @Html.AntiForgeryToken()
    
    <div class="form-horizontal">
        <h4>修改資料</h4>
        <hr />
        @Html.ValidationSummary(true, "", new { @class = "text-danger" })
        @Html.HiddenFor(model => model.Id)
        @Html.HiddenFor(model => model.Account)

        <div class="form-group">
            @Html.LabelFor(model => model.Id, htmlAttributes: new { @class = "control-label col-md-2" })
            <div class="col-md-10" style="padding-top:7px">
                @Html.DisplayFor(model => model.Id, new { htmlAttributes = new { @class = "form-control" } })
            </div>
        </div>

        <div class="form-group">
            @Html.LabelFor(model => model.Account, htmlAttributes: new { @class = "control-label col-md-2" })
            <div class="col-md-10" style="padding-top:7px">
                @Html.DisplayFor(model => model.Account, new { htmlAttributes = new { @class = "form-control" } })
            </div>
        </div>


        <div class="form-group">
            <div class="col-md-offset-2 col-md-10">
                <input type="submit" value="儲存" class="btn btn-default" />
            </div>
        </div>
    </div>
}

下面是 ASP.NET Core MVC 模板的標籤助手錶單部分程式碼：

<div class="col-md-4">
        <form asp-action="Create">
            <div asp-validation-summary="ModelOnly" class="text-danger"></div>
            <div class="form-group">
                <label asp-for="Id" class="control-label"></label>
                <input asp-for="Id" class="form-control" />
                <span asp-validation-for="Id" class="text-danger"></span>
            </div>
            <div class="form-group">
                <label asp-for="Name" class="control-label"></label>
                <input asp-for="Name" class="form-control" />
                <span asp-validation-for="Name" class="text-danger"></span>
            </div>
            <div class="form-group">
                <input type="submit" value="Create" class="btn btn-default" />
            </div>
        </form>
    </div>

4.標籤助手和 WEB 伺服器控制元件比較

Web 伺服器控制元件在頁面上宣告和呼叫。標籤助手不擁有與其關聯的元素，它們只是簡單地參與元素和內容的呈現。

Web 伺服器控制元件有一個不同的生命週期，使其開發和偵錯變得困難。

Web 伺服器控制元件允許通過使用客戶機空間向用戶端檔案物件模型（DOM）新增功能。標籤助手沒有DOM。

Web 伺服器控制元件包括自動瀏覽器檢測，標籤助手不能識別瀏覽器。

多個標籤助手可以對同一元素執行操作，但通常無法編寫 Web 伺服器控制元件。

標籤助手可以修改其範圍限定的HTML元素的標記和內容，但不直接修改頁面上的任何其他內容。

Web 伺服器控制元件使用型別轉換器將字串轉為物件，有了標籤助手，可以在C#中工作，不需要做型別轉換。

Web 伺服器控制元件使用 System.ComponentModel 來實現元件和控制元件的執行時和設計時行為。System.ComponentModel 包括用於實現屬性和類轉換器，繫結到資料來源和許可元件的基礎類別和介面。與標籤助手相比，通常派生自 TagHelper，TagHelper基礎類別僅公開 Process 和 ProcessAsync 兩個方法。

5.自定義標籤助手

1.編寫一個 email 標籤助手

標籤助手是任何實現ITagHelper 介面的類。然而，編寫一個標籤助手時，通常是從 TagHelper 類開始，這樣可以存取 Process 方法。

首先建立一個 TagHelpers 資料夾，新增一個 EmailTagHelper 類：

public class EmailTagHelper:TagHelper
    {
        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            output.TagName = "a"; //用於將 <email> 替換為 <a>
        }
    }

注意：

* 標籤助手使用以目標元素名作為根類名（出去類名中的TagHelper部分）的命名約定，EmailTagHelper最終對應的標籤是 email

* EmailTagHelper 類需派生自 TagHelper，重寫 Process 方法

* Process 或 ProcessAsync 的上下文引數包含了與當前 HTML 標籤執行的相關資訊，輸出引數包含了用來生成HTML標籤和內容的原始碼的靜態HTML元素呈現。

類名字尾不是必須為TagHelper，但是建議加上。

下面在專案中使用 email 標籤助手。在 _ViewImports.cshtml ，使用 addTagHelper 新增 EmailTagHelper類：

@using MVCTest
@using MVCTest.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper "MVCTest.TagHelpers.EmailTagHelper,MVCTest"

@addTagHelper 之後的第一個字串指明要載入的標籤助手，第二個字串指明此標籤助手所在的程式集，在 Views/Home/Contact.cshtml 檔案中加入標籤：

@{
    ViewData["Title"] = "Contact";
}
<h2>@ViewData["Title"]</h2>
<h3>@ViewData["Message"]</h3>

<address>
    One Microsoft Way<br />
    Redmond, WA 98052-6399<br />
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

<address>
    <strong>Support:</strong> <email>Support</email><br />
    <strong>Marketing:</strong> <email>Marketing</email>
</address>

執行程式並使用瀏覽器檢視HTML程式碼，可以看到 email 標籤都被替換成連結標籤。但是沒有一個 href 屬性。

2.完善 email 標籤助手

更新EmailTagHelper類：

public class EmailTagHelper:TagHelper
    {
        private const string EmailDomain = "contoso.com";
        public string MailTo { get; set; } //增加 nail-to 屬性，如 <email mail-to="..." />
        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            output.TagName = "a"; //用於將 <email> 替換為 <a>
            var address = MailTo + "@" + EmailDomain;
            output.Attributes.SetAttribute("href","mailto:"+address);
            output.Content.SetContent(address); //設定標籤助手的內容
        }
    }

更新Views/Home/Contact.cshtml ，加上 mail-to 屬性：

@{
    ViewData["Title"] = "Contact";
}
<h2>@ViewData["Title"]</h2>
<h3>@ViewData["Message"]</h3>

<address>
    One Microsoft Way<br />
    Redmond, WA 98052-6399<br />
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

<address>
    <strong>Support:</strong> <email mail-to="Support">Support</email><br />
    <strong>Marketing:</strong> <email mail-to="Marketing">Marketing</email>
</address>

以 Pascal 形式命名標籤助手的類名及屬性名會被翻譯成它們的小寫 kebab 形式。因此使用 MailTo 屬性，與使用 <eamil mail-to="value" />。

3.非同步標籤助手

更新EmailTagHelper：

public class EmailTagHelper:TagHelper
    {
        private const string EmailDomain = "contoso.com";

        public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
        {
            output.TagName = "a"; //用於將 <email> 替換為 <a>
            var content = await output.GetChildContentAsync();
            var target  = content.GetContent() + "@" + EmailDomain;
            output.Attributes.SetAttribute("href", "mailto:" + target);
            output.Content.SetContent(target);
        }
    }

Views/Home/Contact.cshtml ：

@{
    ViewData["Title"] = "Contact";
}
<h2>@ViewData["Title"]</h2>
<h3>@ViewData["Message"]</h3>

<address>
    One Microsoft Way<br />
    Redmond, WA 98052-6399<br />
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

<address>
    <strong>Support:</strong> <email>Support</email><br />
    <strong>Marketing:</strong> <email>Marketing</email>
</address>

到此這篇關於ASP.NET Core MVC標籤助手(TagHelper)用法的文章就介紹到這了。希望對大家的學習有所幫助，也希望大家多多支援it145.com。