ASP.NET Core 中的錨點標籤協助程式

Peter KellnerScott Addie 撰寫

錨點標籤協助程式藉由新增新的屬性,來增強標準 HTML 錨點 (<a ... ></a>) 標籤。 依照慣例,屬性名稱的開頭會加上 asp-。 所轉譯錨點元素的 href 屬性值取決於 asp- 屬性的值。

如需標籤協助程式的概觀,請參閱 ASP.NET Core 中的標籤協助程式

檢視或下載範例程式碼 \(英文\) (如何下載)

這整份文件的範例皆使用 SpeakerController

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;

public class SpeakerController : Controller
{
    private List<Speaker> Speakers =
        new List<Speaker>
        {
            new Speaker {SpeakerId = 10},
            new Speaker {SpeakerId = 11},
            new Speaker {SpeakerId = 12}
        };

    [Route("Speaker/{id:int}")]
    public IActionResult Detail(int id) =>
        View(Speakers.FirstOrDefault(a => a.SpeakerId == id));

    [Route("/Speaker/Evaluations", 
           Name = "speakerevals")]
    public IActionResult Evaluations() => View();

    [Route("/Speaker/EvaluationsCurrent",
           Name = "speakerevalscurrent")]
    public IActionResult Evaluations(
        int speakerId,
        bool currentYear) => View();

    public IActionResult Index() => View(Speakers);
}

public class Speaker
{
    public int SpeakerId { get; set; }
}

錨點標籤協助程式屬性

asp-controller

asp-controller 屬性指派用於產生 URL 的控制器。 下列標記列出所有喇叭:

<a asp-controller="Speaker"
   asp-action="Index">All Speakers</a>

產生的 HTML:

<a href="/Speaker">All Speakers</a>

若僅指定 asp-controller 屬性而未指定 asp-action,則預設的 asp-action 值即為與目前所執行之檢視相關的控制器動作。 若在上述的標記中省略 asp-action,且在 Home控制器索引 檢視 (/Home) 使用錨點標籤協助程式,則產生的 HTML 即為:

<a href="/Home">All Speakers</a>

asp-action

asp-action 屬性值代表所產生 href 屬性中包含的控制器動作名稱。 下列標記會將產生的 href 屬性值設為喇叭評估頁面:

<a asp-controller="Speaker"
   asp-action="Evaluations">Speaker Evaluations</a>

產生的 HTML:

<a href="/Speaker/Evaluations">Speaker Evaluations</a>

若未指定任何 asp-controller 屬性,則會使用呼叫執行目前檢視之檢視的預設控制器。

asp-action 屬性值為 Index,就不會將任何動作附加至 URL,而導致引動預設的 Index 動作。 指定的動作 (或預設的動作) 必須存在於 asp-controller 所參考的控制器中。

asp-route-{value}

asp-route-{value} 屬性可使用萬用字元路由首碼。 任何佔用 {value} 預留位置的值都會解譯為潛在的路由參數。 如果找不到預設路由,則會將此路由首碼附加至產生的 href 屬性,作為要求參數與值。 否則會在路由範本中加以取代。

請考慮下列控制器動作:

private List<Speaker> Speakers =
    new List<Speaker>
    {
        new Speaker {SpeakerId = 10},
        new Speaker {SpeakerId = 11},
        new Speaker {SpeakerId = 12}
    };

[Route("Speaker/{id:int}")]
public IActionResult Detail(int id) =>
    View(Speakers.FirstOrDefault(a => a.SpeakerId == id));

使用 Startup.Configure 中定義的預設路由範本:

app.UseMvc(routes =>
{
    // need route and attribute on controller: [Area("Blogs")]
    routes.MapRoute(name: "mvcAreaRoute",
                    template: "{area:exists}/{controller=Home}/{action=Index}");

    // default route for non-areas
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

MVC 檢視會使用動作提供的模型,如下所示:

@model Speaker
<!DOCTYPE html>
<html>
<body>
    <a asp-controller="Speaker"
       asp-action="Detail" 
       asp-route-id="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
</body>
</html>

預設路由的 {id?} 預留位置相符。 產生的 HTML:

<a href="/Speaker/Detail/12">SpeakerId: 12</a>

假設路由首碼不屬於相符路由範本的一部份,如同下列 MVC 檢視:

@model Speaker
<!DOCTYPE html>
<html>
<body>
    <a asp-controller="Speaker"
       asp-action="Detail"
       asp-route-speakerid="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
<body>
</html>

因為在相符路由中找不到 speakerid,所以產生了下列 HTML:

<a href="/Speaker/Detail?speakerid=12">SpeakerId: 12</a>

如果未指定 asp-controllerasp-action,則會遵循與 asp-route 屬性中相同的預設處理。

asp-route

asp-route 屬性用於建立直接連結至具名路由的 URL。 使用路由屬性,路由可以如 SpeakerController 中所示命名並用於其 Evaluations 動作:

[Route("/Speaker/Evaluations", 
       Name = "speakerevals")]

在下列標記中,asp-route 屬性參考了具名路由:

<a asp-route="speakerevals">Speaker Evaluations</a>

錨點標記協助程式會使用 URL /Speaker/Evaluations,直接對該控制器動作產生路由。 產生的 HTML:

<a href="/Speaker/Evaluations">Speaker Evaluations</a>

如果除了 asp-route,還指定了 asp-controllerasp-action,產生的路由可能不如預期。 為避免路由衝突,請勿將 asp-routeasp-controllerasp-action 屬性搭配使用。

asp-all-route-data

asp-all-route-data 屬性支援建立機碼值組的字典。 機碼為參數名稱,值則為參數值。

在下列範例中,字典會經過初始化並傳遞至 Razor 檢視。 或者,您也可以使用自己的模型來傳遞資料。

@{
var parms = new Dictionary<string, string>
            {
                { "speakerId", "11" },
                { "currentYear", "true" }
            };
}

<a asp-route="speakerevalscurrent"
   asp-all-route-data="parms">Speaker Evaluations</a>

上述程式碼會產生下列 HTML:

<a href="/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true">Speaker Evaluations</a>

asp-all-route-data 字典已經過扁平化,以產生符合多載 Evaluations 動作之需求的查詢字串。

public IActionResult Evaluations() => View();

[Route("/Speaker/EvaluationsCurrent",
       Name = "speakerevalscurrent")]
public IActionResult Evaluations(

若字典中有任何機碼符合路由參數,這些值在路由中會受到適當地取代。 其他不相符的值則產生作為要求參數。

asp-fragment

asp-fragment 屬性定義要附加至 URL 的 URL 片段。 錨點標籤協助程式會新增雜湊字元 (#)。 請考慮下列標記:

<a asp-controller="Speaker"
   asp-action="Evaluations"
   asp-fragment="SpeakerEvaluations">Speaker Evaluations</a>

產生的 HTML:

<a href="/Speaker/Evaluations#SpeakerEvaluations">Speaker Evaluations</a>

雜湊標籤在建置用戶端應用程式時很實用。 例如,您可以使用這些標籤在 JavaScript 中輕鬆標記和搜尋。

asp-area

asp-area 屬性設定區域名稱,用以設定合適的路由。 下列範例描述了 asp-area 屬性如何造成路由重新對應。

Razor Page 的使用方式

ASP.NET Core 2.1 或更新版本支援 Razor Page 區域。

請考慮下列目錄階層:

  • {專案名稱}
    • wwwroot
    • 區域
      • 工作階段
        • 頁面
          • _ViewStart.cshtml
          • Index.cshtml
          • Index.cshtml.cs
    • 頁面

參考 工作階段 區域 索引Razor Page 的標記如下:

<a asp-area="Sessions"
   asp-page="/Index">View Sessions</a>

產生的 HTML:

<a href="/Sessions">View Sessions</a>

提示

若要支援 Razor Page 應用程式中的區域,請在 Startup.ConfigureServices 中執行下列其中一個動作:

MVC 中的使用方式

請考慮下列目錄階層:

  • {專案名稱}
    • wwwroot
    • 區域
      • 部落格
        • 控制器
          • HomeController.cs
        • 檢視
          • Home
            • AboutBlog.cshtml
            • Index.cshtml
          • _ViewStart.cshtml
    • 控制器

asp-area 設定為 "Blogs" 會在 此錨點標籤之相關控制器和檢視的路由前面加上目錄 Areas/Blogs。 要參考 AboutBlog 檢視的標記如下:

<a asp-area="Blogs"
   asp-controller="Home"
   asp-action="AboutBlog">About Blog</a>

產生的 HTML:

<a href="/Blogs/Home/AboutBlog">About Blog</a>

提示

若要在 MVC 應用程式中支援區域,路由範本必須包含區域參考 (若其存在)。 該範本將以 Startup.Configureroutes.MapRoute 方法呼叫的第二個參數表示:

app.UseMvc(routes =>
{
    // need route and attribute on controller: [Area("Blogs")]
    routes.MapRoute(name: "mvcAreaRoute",
                    template: "{area:exists}/{controller=Home}/{action=Index}");

    // default route for non-areas
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

asp-protocol

asp-protocol 屬性用於在您的 URL 中指定通訊協定 (例如 https)。 例如:

<a asp-protocol="https"
   asp-controller="Home"
   asp-action="About">About</a>

產生的 HTML:

<a href="https://localhost/Home/About">About</a>

此範本中的主機名稱為 localhost。 錨點標籤協助程式使用網站的公用網域來產生 URL。

asp-host

asp-host 屬性用於在您的 URL 中指定主機名稱。 例如:

<a asp-protocol="https"
   asp-host="microsoft.com"
   asp-controller="Home"
   asp-action="About">About</a>

產生的 HTML:

<a href="https://microsoft.com/Home/About">About</a>

asp-page

asp-page 屬性與 Razor Page 搭配使用。 您可用其將錨點標籤的 href 屬性值設定為特定頁面。 在頁面名稱前面加上 / 會從應用程式的根目錄建立相符頁面的 URL:

使用範例程式碼時,下列標記會建立出席者 Razor Page 的連結:

<a asp-page="/Attendee">All Attendees</a>

產生的 HTML:

<a href="/Attendee">All Attendees</a>

asp-page 屬性與 asp-routeasp-controller 以及 asp-action 屬性互斥。 但是,asp-page 可以搭配 asp-route-{value} 使用來控制路由,如下列標記所示:

<a asp-page="/Attendee"
   asp-route-attendeeid="10">View Attendee</a>

產生的 HTML:

<a href="/Attendee?attendeeid=10">View Attendee</a>

如果參考的頁面不存在,則會使用 來自要求的環境值 來產生目前頁面的連結。 除了偵錯記錄層級之外,不會指出任何警告。

asp-page-handler

asp-page-handler 屬性與 Razor Page 搭配使用。 其用途為建立特定頁面處理常式的連結。

請考慮下列頁面處理常式:

public void OnGetProfile(int attendeeId)
{
    ViewData["AttendeeId"] = attendeeId;

    // code omitted for brevity
}

頁面模型的相關標記會連結到 OnGetProfile 頁面處理常式。 請注意,asp-page-handler 屬性值中會省略頁面處理常式方法名稱的 On<Verb> 前置詞。 如果這是非同步方法,則 Async 後置詞也會一併省略。

<a asp-page="/Attendee"
   asp-page-handler="Profile"
   asp-route-attendeeid="12">Attendee Profile</a>

產生的 HTML:

<a href="/Attendee?attendeeid=12&handler=Profile">Attendee Profile</a>

其他資源