在 ASP.NET Core Blazor 應用程式中控制 <head> 內容

  • 發行項

注意

這不是這篇文章的最新版本。 如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前版本，請參閱本文的 .NET 8 版本。

Razor 元件可以修改頁面的 HTML <head> 元素內容，包括設定頁面的標題 (<title> 元素) 和修改中繼資料 (<meta> 元素)。

控制 Razor 元件中的 <head> 內容

使用 PageTitle 元件指定頁面的標題，以將 HTML <title> 元素轉譯為 HeadOutlet 元件。

使用 HeadContent 元件指定 <head> 元素內容，前者會為 HeadOutlet 元件提供內容。

下列範例會使用 Razor 來設定頁面的標題和描述。

ControlHeadContent.razor：

@page "/control-head-content"

<PageTitle>@title</PageTitle>

<h1>Control <head> Content Example</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "This description is set by the component.";
    private string title = "Control <head> Content";
}

@page "/control-head-content"

<h1>Control <head> content</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<PageTitle>@title</PageTitle>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "Description set by component";
    private string title = "Title set by component";
}

@page "/control-head-content"

<h1>Control <head> content</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<PageTitle>@title</PageTitle>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "Description set by component";
    private string title = "Title set by component";
}

在預先轉譯期間控制 <head> 內容

本節適用於預先轉譯的 Blazor WebAssembly 的應用程式和 Blazor Server 應用程式。

預先轉譯 Razor 元件時，必須使用版面配置頁面 (_Layout.cshtml)，透過 PageTitle 和 HeadContent 元件控制 <head> 內容。 之所以有這樣的需求，在於控制 <head> 內容的元件必須在帶有 HeadOutlet 元件之配置之前進行轉譯。 控制頁首內容需要此轉譯順序。

如果共用 _Layout.cshtml 檔案沒有 HeadOutlet 元件的元件標籤協助程式，請將其新增至 <head> 元素。

將元件內嵌至頁面或檢視的 Blazor Server 應用程式或 Razor Pages/MVC 應用程式的必要共用 _Layout.cshtml 檔案：

<component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

在預先轉譯裝載 Blazor WebAssembly 應用程式的必要共用 _Layout.cshtml 檔案中：

<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

透過配置設定元件的頁面標題

在配置元件中設定頁面標題：

@inherits LayoutComponentBase

<PageTitle>Page Title</PageTitle>

<div class="page">
    ...  
</div>

HeadOutlet 元件

HeadOutlet 元件會轉譯 PageTitle 和 HeadContent 元件提供的內容。

在從專案範本建立的 Blazor Web 應用程式中，App.razor 中的 HeadOutlet 元件會轉譯 <head> 內容：

<head>
    ...
    <HeadOutlet />
</head>

在從 Blazor Server 專案範本建立的 Blazor Server 應用程式中，元件標籤協助程式會在 Pages/_Host.cshtml 中轉譯 HeadOutlet 元件的 <head> 內容：

<head>
    ...
    <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
</head>

在從 Blazor Server 專案範本建立的 Blazor Server 應用程式中，元件標籤協助程式會在 Pages/_Layout.cshtml 中轉譯 HeadOutlet 元件的 <head> 內容：

<head>
    ...
    <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
</head>

在從 Blazor WebAssembly 專案範本建立的應用程式中，將 HeadOutlet 元件會新增至用戶端 Program 檔案中 WebAssemblyHostBuilder 的 RootComponents 集合：

builder.RootComponents.Add<HeadOutlet>("head::after");

指定 ::after 虛擬選取器時，根元件的內容會附加至現有的頁首內容，而不是取代內容。 這可讓應用程式在 wwwroot/index.html 中保留靜態頁首內容，而不需要重複應用程式 Razor 元件中的內容。

在 Blazor Web 應用程式中設定預設頁面標題

在 App 元件中設定頁面標題 (App.razor)：

<head>
    ...
    <HeadOutlet />
    <PageTitle>Page Title</PageTitle>
</head>

在 Blazor WebAssembly 應用程式中找不到頁面標題

在從 Blazor WebAssembly 獨立應用程式項目範本建立的 Blazor 應用程式中，App 元件 (App.razor) 中的 NotFound 元件範本會將頁面標題設定為 Not found。

在從 Blazor 專案範本建立的 Blazor 應用程式中，App 元件 (App.razor) 中的 NotFound 元件範本會將網頁標題設定為 Not found。

App.razor：

<NotFound>
    <PageTitle>Not found</PageTitle>
    ...
</NotFound>

其他資源

Mozilla MDN Web Docs 文件：