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

發行項
11/30/2023

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

這整份文件的範例皆使用 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，且在「HomeController 的索引」檢視 (/HomeHome) 使用錨點標籤協助程式，則產生的 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-controller 或 asp-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-controller 或 asp-action，產生的路由可能不如預期。為避免路由衝突，請勿將 asp-route 與 asp-controller 及 asp-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 中執行下列其中一個動作:

將相容性版本設定為 2.1 或更新版本。

將 RazorPagesOptions.AllowAreas 屬性設定為 true:

services.AddMvc()
        .AddRazorPagesOptions(options => options.AllowAreas = true);

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.Configure 中 routes.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-route、asp-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>

共用方式為

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

錨點標籤協助程式屬性

asp-controller

asp-action

asp-route-{value}

asp-route

asp-all-route-data

asp-fragment

asp-area

Razor Page 的使用方式

MVC 中的使用方式

asp-protocol

asp-host

asp-page

asp-page-handler

其他資源

其他資源