在 ASP.NET Core Blazor 应用中控制 <head> 内容

注意

此版本不是本文的最新版本。 对于当前版本,请参阅此文的 .NET 8 版本

警告

此版本的 ASP.NET Core 不再受支持。 有关详细信息,请参阅 .NET 和 .NET Core 支持策略。 对于当前版本,请参阅此文的 .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"

<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) 来控制包含 PageTitleHeadContent 组件的 <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 组件呈现 PageTitleHeadContent 组件提供的内容。

在从项目模板创建的 Blazor Web App 中,App.razor 中的 HeadOutlet 组件会呈现 <head> 内容:

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

在从 Blazor Server 项目模板创建的 Blazor Server 应用中,组件标记帮助程序呈现 Pages/_Host.cshtmlHeadOutlet 组件的 <head> 内容:

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

在从 Blazor Server 项目模板创建的 Blazor Server 应用中,组件标记帮助程序呈现 Pages/_Layout.cshtmlHeadOutlet 组件的 <head> 内容:

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

在从 Blazor WebAssembly 项目模板创建的应用中,HeadOutlet 组件被添加到客户端 Program 文件中 WebAssemblyHostBuilderRootComponents 集合:

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

指定 ::after 伪选择器后,根组件的内容将追加到现有标头内容,而不是替换内容。 这使应用可以在 wwwroot/index.html 中保留静态标头内容,而无需重复应用的 Razor 组件中的内容。

在 Blazor Web App 中设置默认页标题

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 文档: