在 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 应用中，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 文档：