重學(xué)ASP.NET Core 中的標(biāo)記幫助程序

標(biāo)記幫助程序是什么

標(biāo)記幫助程序使服務(wù)器端代碼可以在 Razor 文件中參與創(chuàng)建和呈現(xiàn) HTML 元素。?例如，內(nèi)置的?ImageTagHelper?可以將版本號追加到圖片名稱。??每當(dāng)圖片發(fā)生變化時(shí)，服務(wù)器都會為圖像生成一個(gè)新的唯一版本號，因此客戶端總能獲得當(dāng)前圖像（而不是過時(shí)的緩存圖像）。

作者：依樂祝
原文鏈接：https://www.cnblogs.com/yilezhu/p/13197922.html

標(biāo)記幫助程序的作用域是如何控制的

標(biāo)記幫助程序作用域由?@addTagHelper、@removeTagHelper?和“!”選擇退出字符等聯(lián)合控制。下面就一一的進(jìn)行相關(guān)的介紹吧。

使用?@addTagHelper?添加標(biāo)記幫助程序

@addTagHelper?指令讓視圖可以使用標(biāo)記幫助程序。?在這種情況下，視圖文件是_pages/ViewImports，默認(rèn)情況下，它由_pages_文件夾和子文件夾中的所有文件繼承，這使得標(biāo)記幫助程序可用。?
這里公開標(biāo)記幫助程序有兩種方式，如下所示：
第一種：使用通配符語法（" * "）指定指定程序集（AspNetCore）中的所有標(biāo)記幫助程序都可用于_Views_目錄及其子目錄中的每個(gè)視圖文件。

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

第二種：使用標(biāo)記幫助程序的完全限定名，添加某個(gè)特定的標(biāo)記幫助程序。

@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

說明：@addTagHelper?后第一個(gè)參數(shù)指定要加載的標(biāo)記幫助程序（我們使用“*”指定加載所有標(biāo)記幫助程序），第二個(gè)參數(shù)“Microsoft.AspNetCore.Mvc.TagHelpers”指定包含標(biāo)記幫助程序的程序集。?
注：Microsoft.AspNetCore.Mvc.TagHelpers 是內(nèi)置 ASP.NET Core 標(biāo)記幫助程序的程序集。

@removeTagHelper?刪除標(biāo)記幫助程序

@removeTagHelper?與?@addTagHelper?具有相同的兩個(gè)參數(shù)，它會刪除之前添加的標(biāo)記幫助程序。?例如，應(yīng)用于特定視圖的?@removeTagHelper?會刪除該視圖中的指定標(biāo)記幫助程序。?在 Views/Folder/_ViewImports.cshtml 文件中使用?@removeTagHelper，將從 Folder 中的所有視圖刪除指定的標(biāo)記幫助程序。

使用?_ViewImports.cshtml? 文件控制標(biāo)記幫助程序作用域

可將 _ViewImports.cshtml 添加到任何視圖文件夾，視圖引擎將同時(shí)應(yīng)用該文件和 Views/_ViewImports.cshtml 文件中的指令。

說明：

1. 如果為 Home 視圖添加空的 Views/Home/_ViewImports.cshtml 文件，則不會發(fā)生任何更改，因?yàn)?_ViewImports.cshtml 文件是附加的。

2. 添加到 Views/Home/_ViewImports.cshtml 文件（不在默認(rèn) Views/_ViewImports.cshtml 文件中）的任何?@addTagHelper?指令，都只會將這些標(biāo)記幫助程序公開給 Home 文件夾中的視圖。

選擇退出字符（“!”）元素級別退出標(biāo)記幫助程序

使用標(biāo)記幫助程序選擇退出字符（“!”），可在元素級別禁用標(biāo)記幫助程序。?例如，使用標(biāo)記幫助程序選擇退出字符在??中禁用?Email?驗(yàn)證：

for="Email" class="text-danger">

說明：
須將標(biāo)記幫助程序選擇退出字符應(yīng)用于開始和結(jié)束標(biāo)記。?（將選擇退出字符添加到開始標(biāo)記時(shí)，Visual Studio 編輯器會自動(dòng)為結(jié)束標(biāo)記添加相應(yīng)字符）。?
添加選擇退出字符后，元素和標(biāo)記幫助程序?qū)傩圆辉僖元?dú)特字體顯示。

使用?@tagHelperPrefix?闡明標(biāo)記幫助程序用途

@tagHelperPrefix?指令可指定一個(gè)標(biāo)記前綴字符串，以啟用標(biāo)記幫助程序支持并闡明標(biāo)記幫助程序用途。?例如，可以將以下標(biāo)記添加到 Views/_ViewImports.cshtml 文件：

@tagHelperPrefix th:

在以下代碼圖像中，標(biāo)記幫助程序前綴設(shè)置為?th:，所以只有使用前綴?th:?的元素才支持標(biāo)記幫助程序（可使用標(biāo)記幫助程序的元素以獨(dú)特字體顯示）。??和??元素具有標(biāo)記幫助程序前綴，可使用標(biāo)記幫助程序，而??元素則相反。

適用于?@addTagHelper?的層次結(jié)構(gòu)規(guī)則也適用于?@tagHelperPrefix。

標(biāo)記幫助程序的 Intellisense 支持

在 Visual Studio 中創(chuàng)建新的 ASP.NET Core web 應(yīng)用時(shí)，它將添加AspNetCore Razor的NuGet 包 。它 是添加標(biāo)記幫助程序的工具包。
假設(shè)編寫 HTML??元素。只要在 Visual Studio 編輯器中輸入?，IntelliSense 就會顯示匹配的元素：


不僅會獲得 HTML 幫助，還會有圖標(biāo)（下方帶有“<>”的“@" symbol with "）




將該元素標(biāo)識為標(biāo)記幫助程序的目標(biāo)。純 HTML 元素（如 `fieldset`）顯示“<>”圖標(biāo)。
純 HTML `` 標(biāo)記以棕色字體顯示 HTML 標(biāo)記（使用默認(rèn) Visual Studio 顏色主題時(shí)），以紅色字體顯示屬性，并以藍(lán)色字體顯示屬性值。

輸入??后，IntelliSense 會列出可用的 HTML/CSS 屬性和以標(biāo)記幫助程序?yàn)槟繕?biāo)的屬性：

通過 IntelliSense 語句完成功能，按 Tab 鍵即可用選擇的值完成語句：

只要輸入標(biāo)記幫助程序?qū)傩裕瑯?biāo)記和屬性字體就會更改。如果使用默認(rèn)的 Visual Studio“藍(lán)色”或“淺色”顏色主題，則字體是粗體紫色。如果使用“深色”主題，則字體為粗體青色。本文檔中的圖像在使用默認(rèn)主題時(shí)截取的。

可在雙引號 ("") 內(nèi)輸入 Visual Studio CompleteWord 快捷方式（默認(rèn)值為 Ctrl+空格鍵），即可使用 C#，就像在 C# 類中一樣。IntelliSense 會顯示頁面模型上的所有方法和屬性。由于屬性類型是?ModelExpression，所以這些方法和屬性可用。在下圖中，我正在編輯?Register?視圖，所以?RegisterViewModel?是可用的。


IntelliSense 會列出頁面上模型可用的屬性和方法。豐富 IntelliSense 環(huán)境可幫助選擇 CSS 類：

自定義標(biāo)記幫助程序元素字體

可以從 "工具" "選項(xiàng)" "環(huán)境" " >?Options?>?Environment?>?字體和顏色" 中自定義字體和著色：

實(shí)例演示如何在ASP.NET Core中創(chuàng)建標(biāo)記幫助程序

標(biāo)記幫助程序是實(shí)現(xiàn)?ITagHelper?接口的任何類。但是，在創(chuàng)作標(biāo)記幫助程序時(shí)，通常從?TagHelper?派生，這樣可以訪問?Process?方法。

1. 創(chuàng)建一個(gè)名為 AuthoringTagHelpers 的新 ASP.NET Core 項(xiàng)目。注：此項(xiàng)目不需要身份驗(yàn)證。


2. 創(chuàng)建一個(gè)名為“TagHelpers”的文件夾來保存標(biāo)記幫助程序。注：?TagHelpers?文件夾不是必需的，但它是合理的約定。

現(xiàn)在讓我們開始編寫一些簡單的標(biāo)記幫助程序。

EmailTagHelper?標(biāo)記幫助程序

如果你正在編寫博客引擎，并且需要它將營銷、支持和其他聯(lián)系人的電子郵件全部發(fā)送到同一個(gè)域，則可能需要這樣的一個(gè)標(biāo)記幫助程序。
如下所示，先上代碼：

using Microsoft.AspNetCore.Razor.TagHelpers;
using System.Threading.Tasks;

namespace AuthoringTagHelpers.TagHelpers
{
    public class EmailTagHelper : TagHelper
    {
        public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
        {
            output.TagName = "a";    // Replaces  with  tag
            var address = MailTo + "@" + EmailDomain;
        	output.Attributes.SetAttribute("href", "mailto:" + address);
        	output.Content.SetContent(address);
            return Task.CompletedTask;
        }
    }
}

說明：

1. 標(biāo)記幫助程序使用面向根類名稱的元素的命名約定（減去類名稱的 TagHelper 部分）。?在此示例中，?EmailTagHelper的根名稱為_email_，因此??標(biāo)記將針對。

2. EmailTagHelper?類從?TagHelper?派生。?TagHelper?類提供編寫標(biāo)記幫助程序的方法和屬性。

3. 重寫的?ProcessAsync?方法控制標(biāo)記幫助程序在執(zhí)行時(shí)的操作。?TagHelper?類還提供具有相同參數(shù)的同步版本 (Process)。

4. 類名稱的后綴是 TagHelper，這不是必需的，但被認(rèn)為是約定的最佳做法。?可將類聲明為：public class Email : TagHelper

5. 標(biāo)記幫助程序采用 Pascal 大小寫格式的類和屬性名將轉(zhuǎn)換為各自相應(yīng)的短橫線格式。?因此，要使用?MailTo?屬性，請使用??等效項(xiàng)。

6. 最后一行為EmailTagHelper標(biāo)記幫助程序設(shè)置已完成的內(nèi)容。

7. SetAttribute?是添加屬性的語法，只要屬性集合中當(dāng)前不存在?href?屬性，該方法就適用于此屬性。

接下來然我們在Razor頁面上應(yīng)用此標(biāo)記幫助程序吧。
使用以下更改更新 Views/Home/Contact.cshtml 文件中的標(biāo)記:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers
@{
    ViewData["Title"] = "Contact Copy";
}
@ViewData["Title"].

@ViewData["Message"]



    One Microsoft Way Copy Version 

    Redmond, WA 98052-6399

    "Phone">P:
    425.555.0100



    Support:"Support">

    Marketing:"Marketing">

說明：

1. 開頭的?@addTagHelper?是添加對應(yīng)的標(biāo)記幫助程序引用，文章開頭已經(jīng)進(jìn)行了相關(guān)闡述

2. 第18，19行代碼

   標(biāo)記引用了我們上面編寫的? ?EmailTagHelper?標(biāo)記幫助程序。

3. mail-to?屬性是標(biāo)記幫助程序采用 Pascal 大小寫格式的類和屬性名將轉(zhuǎn)換為各自相應(yīng)的短橫線格式。因此，要使用 MailTo 屬性，必須使用 ?的等效項(xiàng)。

這時(shí)候運(yùn)行下程序，可以看到生成對應(yīng)的html標(biāo)簽了：

"mailto:[email protected]">[email protected]
"mailto:[email protected]">[email protected]

在標(biāo)記幫助程序中使用實(shí)體模型

1. 添加“Models”文件夾**。


2. 將以下?WebsiteContext?類添加到“模型”文件夾：

using System;

namespace AuthoringTagHelpers.Models
{
    public class WebsiteContext
    {
        public Version Version { get; set; }
        public int CopyrightYear { get; set; }
        public bool Approved { get; set; }
        public int TagsToShow { get; set; }
    }
}

3. 將以下?WebsiteInformationTagHelper?類添加到“TagHelpers”文件夾。

using System;
using AuthoringTagHelpers.Models;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace AuthoringTagHelpers.TagHelpers
{
    public class WebsiteInformationTagHelper : TagHelper
    {
        public WebsiteContext Info { get; set; }

      public override void Process(TagHelperContext context, TagHelperOutput output)
      {
         output.TagName = "section";
         output.Content.SetHtmlContent(
$@"
Version: {Info.Version}

Copyright Year: {Info.CopyrightYear}

Approved: {Info.Approved}

Number of tags to show: {Info.TagsToShow}
");
         output.TagMode = TagMode.StartTagAndEndTag;
      }
   }
}

4. 將以下標(biāo)記添加到 About.cshtml 視圖**。?突出顯示的標(biāo)記顯示 Web 站點(diǎn)信息。

@using AuthoringTagHelpers.Models
@{
    ViewData["Title"] = "About";
    WebsiteContext webContext = new WebsiteContext {
                                    Version = new Version(1, 3),
                                    CopyrightYear = 1638,
                                    Approved = true,
                                    TagsToShow = 131 };
}
@ViewData["Title"].

@ViewData["Message"]


Use this area to provide additional information.


 Is this bold?

 web site info 

"webContext" />

說明：
在下面的Razor顯示的標(biāo)記中：
?
Razor知道 info 屬性是一個(gè)類，而不是字符串，并且您想要編寫 c # 代碼。?編寫任何非字符串標(biāo)記幫助程序?qū)傩詴r(shí)，都不應(yīng)使用 @ 字符。

5. 運(yùn)行應(yīng)用，并導(dǎo)航到“關(guān)于”視圖即可查看 Web 站點(diǎn)信息。

總結(jié)

本文首先帶著大家回顧了一下標(biāo)記幫助程序的一些概念，接著給大家介紹了標(biāo)記幫助程序作用域的注意事項(xiàng)來為接下來的實(shí)例演練做準(zhǔn)備。然后給大家介紹了標(biāo)記幫助程序強(qiáng)大的?Intellisense?支持，讓我們在開發(fā)中事半功倍，如虎添翼！最后就是通過實(shí)例代碼來做兩個(gè)標(biāo)記幫助程序的小例子加深我們的理解。希望對大家有所幫助！
接下來我會介紹下微軟官方提供的一些常用標(biāo)記幫助程序，有興趣的朋友可以關(guān)注下。


參考文檔：

1. https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/intro?view=aspnetcore-3.1

2. https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/authoring?view=aspnetcore-3.1