ASP.NET Core 3.0 : 二十五. TagHelper
什麼是TagHelper？這是ASP.NET Core 中新出現的一個名詞，它的作用是使伺服器端程式碼可以在Razor 檔案中參與建立和呈現HTML 元素。(ASP.NET Core 系列目錄)
一、概述
上面的解釋有點拗口？那麼換一個名詞，HtmlHelper大家都知道吧，在ASP.NET Core中，TagHelper類似HtmlHelper，但可以說是青出於藍而勝於藍。那麼TagHelper的作用也就大概明白了吧。
首先通過一個例子看一下TagHelper是怎麼使用的，看看它和HtmlHelper有什麼區別。新建一個Book類：
public class Book
{
[Display(Name = "編號")]
public string Code { get; set; }
[Display(Name = "名稱")]
public string Name { get; set; }
}新建對應的Controller和Action：
public class BookController : Controller
{
// GET: /<controller>/
public IActionResult Index()
{
return View(new Book() { Code = "001", Name = "ASP" });
}
}
最後就是View了：
@model Book
@{
Layout = null;
}
@Html.LabelFor(m => m.Name)
@Html.EditorFor(m => m.Name)
<br />
<label asp-for="Name"></label>
<input asp-for="Name" />這裡分別通過HtmlHelper和TagHelper兩種方式實現了一個文字和輸入框的顯示。檢視網頁原始碼，可以看到二者生成的HTML如下:
<label for="Name">Name</label> <input class="text-box single-line" id="Name" name="Name" type="text" value="ASP" /> <br/> <label for="Name">Name</label> <input type="text" id="Name" name="Name" value="ASP" />
目前看起來二者差不多，從工作量上來看也是區別不大。現在功能實現了，需要做一些樣式處理。簡單舉個例子，現在希望Book的編號（Code）對應的label的顏色設定為紅色，定義了一個css如下：
<style type="text/css">
.codeColor {
color:red;
}
</style>
然後準備把這個樣式應用到label上，這時如果是HtmlHelper就很有可能會被問：“class寫在哪”，估計好多人都被問過。然後我們告訴他可以這樣寫：
@Html.LabelFor(m=>m.Name,new {@class="codeColor"})
前端工程師新增後達到了想要的效果，但同時表示記不住這個寫法，下次可能還會問。
如果是TagHelper就方便了，告訴他可以像平時給Html的標籤新增class一樣操作即可，也就是：
<label asp-for="Name" class="codeColor"></label>
前端工程師表示這種寫法“真是太友好了”。同樣對於Form及驗證，比較一下兩種寫法的不同，HtmlHelper版：
@using (Html.BeginForm("Index", "Home", FormMethod.Post)){
@Html.LabelFor(m => m.Code)
@Html.EditorFor(m => m.Code) @Html.ValidationMessageFor(m => m.Code) <input type="submit" value="提交" />
}
TagHelper版：
<form asp-action="Index" asp-controller="Home" method="post">
<label asp-for="Code"></label>
<input asp-for="Code" />
<span asp-validation-for="Code"></span>
<input type="submit" value="提交" />
</form>
二、自定義TagHelper
現在有這樣的需求，用於顯示Book的編號的label不止要新增名為codeColor的css樣式，還要給書的編號自動新增一個字首，例如“BJ”。
對於這樣的需求，希望可以通過一個簡單的標記，然後由TagHelper自動實現。例如：
<label show-type="bookCode">1001</label>
自定義了一個屬性“show-type”，用於標識這個label的顯示類別，“1001”為假定的圖書編號。通過這樣的設定方式，將來如果需求有變化，需要對編號的顯示做更多的修飾，只需修改對應的TagHelper即可，而頁面部分不需要做任何調整。
系統提供了方便的自定義TagHelper的方式，就是繼承系統提供的TagHelper類，並重寫它的Process/ProcessAsync方法，例如下面的例子：
public class LabelTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
if (output.Attributes.TryGetAttribute("show-type", out TagHelperAttribute showTypeAttribute))
{
if (showTypeAttribute.Value.ToString().Equals("bookCode"))
{
output.Attributes.SetAttribute("class", "codeColor");
string content = output.Content.IsModified ? output.Content.GetContent() : (await output.GetChildContentAsync()).GetContent(); ;
output.Content.SetContent("BJ" + content);
}
}
}
}
首先判斷label是否被設定了show-type="bookCode"，然後獲取當前label的Content內容，將其新增字首“BJ”後作為此label的Content的新內容。注意一下Content的獲取方式，如果它沒有被修改，憑感覺直接通過output.Content.GetContent()獲取到的內容是空的。
訪問index頁面，可以看到改標籤已被處理，如下圖：
備註：a.關於獲取show-type的值，還可以有其他方式，下文會講到。
b.從規範化命名的角度，建議將自定義的TagHelper其命名為XXXagHelper這樣的格式。
三、TagHelper的註冊
TagHelper自定義之後需要將其註冊一下，否則它是不會生效的。開啟_ViewImports.cshtml，預設為：
@using TagHelperDemo @using TagHelperDemo.Models @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
在最下面新增一條
@addTagHelper *, TagHelperDemo
最後新增的這一句話是什麼意思呢？也就是將程式集TagHelperDemo（即第二個引數）中的所有TagHelper（第一個引數為“*”，即所有）全部啟用。假如還定義了一個PasswordTagHelper，但只想只新增LabelTagHelper，可以這樣寫：
@addTagHelper TagHelperDemo.TagHelpers. LabelTagHelper, TagHelperDemo
如果想新增所有自定義的TagHelper，但要去除LabelTagHelper呢？
那麼可以先新增所有，再去除這個LabelTagHelper。
@addTagHelper *, TagHelperDemo @removeTagHelper TagHelperDemo.TagHelpers. LabelTagHelper, TagHelperDemo
四、TagHelper的作用範圍
在專案中，可能不止使用label標籤來顯示Book的Code，還有可能會是p、span等型別的標籤，現在的需求是，無論是上述哪一種標籤，都要實現新增css和字首的功能。
現在將index.cshtml中新增一個p標籤如下：
<p show-type="bookCode">1002</p>
訪問這個頁面發現1002未被處理。這是因為我們定義的TagHelper名為LabelTagHelper，在預設的情況下只會處理label標籤。當然也可以做特殊設定，例如下面程式碼的寫法：
[HtmlTargetElement("p")]
public class LabelTagHelper : TagHelper
{
//程式碼省略
}
通過“[HtmlTargetElement("p")]”指定本TagHelper只能被使用於p標籤。再次訪問此頁面，發現p標籤被處理了，而label未被處理。這說明這樣的顯式指定的優先順序要高於預設的名稱匹配。除了設定指定標籤，還可以有一些其他的輔助設定：
[HtmlTargetElement("p", Attributes = "show-type", ParentTag = "div")]
public class LabelTagHelper : TagHelper
可以這樣寫，會匹配p標籤，要求該標籤擁有show-type屬性，並且父標籤為div。這幾個條件是“and”的關係。如果還想匹配label標籤，可以新增對label的設定，例如下面程式碼這樣：
[HtmlTargetElement("p", Attributes = "show-type", ParentTag = "div")]
[HtmlTargetElement("label", Attributes = "show-type", ParentTag = "div")]
public class LabelTagHelper : TagHelper
這兩個HtmlTargetElement的關係是“or”。通過這樣的設定，可以極大的縮小目標標籤的範圍。
但是這樣設定之後，這個TagHelper的名字再叫LabelTagHelper就不合適了，例如可以改為BookCodeTagHelper，最終程式碼如下：
[HtmlTargetElement("p", Attributes = "show-type", ParentTag = "div")]
[HtmlTargetElement("label", Attributes = "show-type", ParentTag = "div")]
public class BookCodeTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
if (output.Attributes.TryGetAttribute("show-type", out TagHelperAttribute showTypeAttribute))
{
if (showTypeAttribute.Value.ToString().Equals("bookCode"))
{
output.Attributes.SetAttribute("class", "codeColor");
string content = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent(); ;
output.Content.SetContent("BJ" + content);
}
}
}
}
如果想使個別Html標籤遮蔽TagHelper的作用，可以使用“!”。例如下面兩個標籤：
<!label show-type="bookCode">1001</label>
五、自定義標籤
上一節最終形成了一個名為BookCodeTagHelper的TagHelper，我們知道LabelTagHelper是可以按名稱預設匹配label標籤的，那麼是否可以自定義一個BookCode標籤呢？在index.cshtml中新增這樣的程式碼：
<BookCode>1003</BookCode>
由於自定義bookcode標籤的目的就是專門顯示Book的Code，所以也不必新增show-type屬性了。然後修改BookCodeTagHelper，修改後的程式碼如下：
public class BookCodeTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
output.Attributes.SetAttribute("class", "codeColor");
string content = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent(); ;
output.Content.SetContent("BJ" + content);
}
}
去掉了兩個HtmlTargetElement設定並取消了對show-type的判斷，訪問index頁面檢視新建的bookcode標籤是否會被處理，結果是沒有被處理。這是為什麼呢？
這是由於TagHelper會將採用Pascal 大小寫格式的類和屬性名將轉換為各自相應的短橫線格式。即“BookCode”對應“book-code”，獲取標籤的屬性值，同樣遵循這樣的規則。所以將標籤改為如下寫法即可：
<book-code>1003</book-code>
再次執行測試，發現這個新標籤被成功處理。檢視網頁原始碼，被處理後的Html程式碼是這樣的：
<book-code class="codeColor">TJ1003</book-code>
如果想將其改變為label，可以在BookCodeTagHelper中通過指定TagName實現：
public class BookCodeTagHelper : TagHelper
{
public Book Book { get; set; }
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "label";
output.Attributes.SetAttribute("class", "codeColor");
string content = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent(); ;
output.Content.SetContent(Book.Prefix + content);
}
}
六、TagHelper與頁面之間的資料傳遞
假如現在的新需求是圖書編碼的字首不再固定為“BJ”了，需要在標籤中定義，例如這樣：
<book-code prefix="SH">1003</book-code>
需要獲取prefix的值，在上面的例子中採用的是TryGetAttribute方法，其實還有簡單的方式，修改BookCodeTagHelper，程式碼如下：
public class BookCodeTagHelper : TagHelper
{
public string Prefix { get; set; }
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
output.Attributes.SetAttribute("class", "codeColor");
string content = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent(); ;
output.Content.SetContent(Prefix + content);
}
}
標籤中的prefix的值會自動賦值給BookCodeTagHelper.Prefix，是不是更方便了。那麼如果是Model中的值呢？假如Book類有一個屬性“public string Prefix { get; set; } ”，這和傳入一個字串沒什麼區別，那麼可以這樣寫：
<book-code prefix="@Model.Prefix">1003</book-code>
這種傳值方式不止是支援字串，將Model整體傳入也是支援的，將標籤修改如下：
<book-code book="@Model">1003</book-code>
修改BookCodeTagHelper程式碼：
public class BookCodeTagHelper : TagHelper
{
public Book Book { get; set; }
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
output.Attributes.SetAttribute("class", "codeColor");
string content = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent(); ;
output.Content.SetContent(Book.Prefix + content);
}
}
七、取消標籤輸出
前面的幾個例子都是對滿足條件的標籤的修改，TagHelper也可以取消對應標籤的輸出，例如存在這樣一個標籤：
<div simple-type="Simple1"></div>
如果不想讓它出現在生成的Html中，可以這樣處理：
[HtmlTargetElement("div",Attributes = "simple-type")]
public class Simple1TagHelpers : TagHelper
{
public string SimpleType { get; set; }
public override void Process(TagHelperContext context, TagHelperOutput output)
{
if (SimpleType.Equals("Simple1")) //可以是其他一些判斷規則
{
output.SuppressOutput();
}
}
}
八、TagBuilder
在TagHelper中，可以用TagBuilder來輔助生成標籤，例如存在如下兩個div：
<div simple-type="Simple2"></div> <div simple-type="Simple3"></div>
想在div中新增Html元素可以這樣寫：
[HtmlTargetElement("div",Attributes = "simple-type")]
public class Simple1TagHelpers : TagHelper
{
public string SimpleType { get; set; }
public override void Process(TagHelperContext context, TagHelperOutput output)
{
if (SimpleType.Equals("Simple2"))
{
output.Content.SetHtmlContent("<p>Simple2</p>");
}
else if (SimpleType.Equals("Simple3"))
{
var p = new TagBuilder("p");
p.InnerHtml.Append("Simple3");
output.Content.SetHtmlContent(p);
}
}
}
通過TagBuilder生成了一個新的p標籤，並將它插入到div中。
&n