ASP.NET Core Razor 组件

本文介绍如何在 Blazor 应用中创建和使用 Razor 组件，包括有关 Razor 语法、组件命名、命名空间和组件参数的指导。

Razor 组件

Blazor 应用是使用 Razor 组件（非正式地称为 Blazor 组件或组件）构建的。 组件是用户界面 (UI) 的自包含部分，具有用于启用动态行为的处理逻辑。 组件可以嵌套、重用、在项目间共享，并可在 MVC 和 Razor Pages 应用中使用。

组件呈现为浏览器文档对象模型 (DOM) 的内存中表现形式，它被称为“呈现树”，用于以灵活高效的方式更新 UI。

尽管“Razor 组件”与其他 ASP.NET Core 内容呈现技术共享某种命名，但 Razor 组件必须与 ASP.NET Core 中的以下不同功能区分开来：

• Razor 视图，它们是 MVC 应用的基于 Razor 的标记页面。
• 视图组件，用于在 Razor Pages 和 MVC 应用中呈现内容块而不是整个响应。

组件类

组件是使用 C# 和 HTML 标记的组合在 Razor 组件文件（文件扩展名为 .razor）中实现的。

默认情况下，ComponentBase 是 Razor 组件文件描述的组件的基类。 ComponentBase 实现组件的最低抽象，IComponent 接口。 ComponentBase 定义基本功能的组件属性和方法，例如，处理一组内置组件生命周期事件。

dotnet/aspnetcore引用源中的 ComponentBase：引用源包含有关内置生命周期事件的其他注释。 但是请记住，组件功能的内部实现随时可能会更改，但不会发出通知。

说明

指向 .NET 参考源的文档链接通常会加载存储库的默认分支，该分支表示针对下一个 .NET 版本的当前开发。 若要为特定版本选择标记，请使用“切换分支或标记”下拉列表。 有关详细信息，请参阅如何选择 ASP.NET Core 源代码的版本标记 (dotnet/AspNetCore.Docs #26205)。

开发人员通常从 Razor 组件文件 (.razor) 创建 Razor 组件，或将组件构建于 ComponentBase 之上，但组件也可以通过实现 IComponent 来生成。 实现 IComponent 的开发人员所构建的组件可以对呈现采用低级别控制，代价是需要使用事件和生命周期方法手动触发呈现，且这些事件和方法必须由开发人员创建和维护。

Razor 语法

组件使用 Razor 语法。 组件广泛使用了两个 Razor 功能，即指令和指令特性。 这两个功能是前缀为 @ 的保留关键字，出现在 Razor 标记中：

• 指令：更改组件标记的分析或运行方式。 例如，@page 指令使用路由模板指定可路由组件，可以由用户请求在浏览器中按特定 URL 直接访问。

  按照约定，组件定义（.razor 文件）顶部的组件指令按一致顺序排列。 对于重复指令，指令按命名空间或类型按字母顺序放置，但具有特殊二级排序的 @using 指令除外。

  Blazor 示例应用和文档采用以下顺序。 Blazor 项目模板提供的组件可能与以下顺序不同，并使用不同的格式。 例如，Blazor 框架 Identity 组件包括指令块 @using 和指令块 @inject 之间的空白行。 你可以在自己的应用中自由使用自定义排序方案和格式。

  文档和示例应用 Razor 指令顺序：

  • @page
  • @rendermode（.NET 8 或更高版本）
  • @using
    • System 命名空间（字母顺序）
    • Microsoft 命名空间（字母顺序）
    • 第三方 API 命名空间（字母顺序）
    • 应用命名空间（字母顺序）
  • 其他指令（字母顺序）

  指令之间没有出现空白行。 指令与 Razor 标记的第一行之间会出现一个空白行。

  示例：

  @page "/doctor-who-episodes/{season:int}"
  @rendermode InteractiveWebAssembly
  @using System.Globalization
  @using System.Text.Json
  @using Microsoft.AspNetCore.Localization
  @using Mandrill
  @using BlazorSample.Components.Layout
  @attribute [Authorize]
  @implements IAsyncDisposable
  @inject IJSRuntime JS
  @inject ILogger<DoctorWhoEpisodes> Logger
  
  <PageTitle>Doctor Who Episode List</PageTitle>
  
  ...
  

• 指令特性：更改组件元素的分析方式或运行方式。

  示例：

  <input @bind="episodeId" />
  

  对于非显式Razor表达式 (@bind="@episodeId")，可以使用 at 符号 (@) 为指令属性值添加前缀，但不建议使用，并且文档不会采用示例中的方法。

本文和 Blazor 文档集的其他文章中进一步说明了在组件中使用的指令和指令特性。 有关 Razor 语法的一般信息，请参阅 ASP.NET Core 的 Razor 语法参考。

组件名称、类名和命名空间

组件的名称必须以大写字符开头：

✔️支持：ProductDetail.razor

❌不支持：productDetail.razor

整个 Blazor 文档中使用的常见 Blazor 命名约定包括：

• 文件路径和文件名使用 †Pascal 大小写，且在显示组件代码示例之前出现。 如果路径存在，则表示典型的文件夹位置。 例如，Components/Pages/ProductDetail.razor 表示 ProductDetail 组件具有文件名 ProductDetail.razor，并位于应用的 Components 文件夹的 Pages 文件夹中。
• 可路由组件的组件文件路径与其 ‡kebab 大小写形式的 URL 匹配，组件路由模板中各单词之间会显示连字符。 例如，在浏览器中，通过相对 URL /product-detail 请求具有路由模板 /product-detail (@page "/product-detail") 的 ProductDetail 组件。

†Pascal 大小写（大写 camel 形式）是不带空格和标点符号的命名约定，其中每个单词的首字母大写（包括第一个单词）。
‡Kebab 大小写是一种命名约定，不使用空格和标点符号，它使用小写字母，且单词之间有短划线。

组件是普通 C# 类，可以放置在项目中的任何位置。 生成网页的组件通常位于 Components/Pages 文件夹中。 非页面组件通常放置在 Components 文件夹或添加到项目的自定义文件夹中。

通常，组件的命名空间是从应用的根命名空间和该组件在应用内的位置（文件夹）派生而来的。 如果应用的根命名空间是 BlazorSample，并且 Counter 组件位于 Components/Pages 文件夹中：

• Counter 组件的命名空间为 BlazorSample.Components.Pages。
• 组件的完全限定类型名称为 BlazorSample.Components.Pages.Counter。

对于保存组件的自定义文件夹，将 @using 指令添加到父组件或应用的 _Imports.razor 文件。 下面的示例提供 AdminComponents 文件夹中的组件：

@using BlazorSample.AdminComponents

说明

_Imports.razor 文件中的 @using 指令仅适用于 Razor 文件 (.razor)，而不适用于 C# 文件 (.cs)。

不支持使用别名的 using 语句。 在以下示例中，GridRendering 组件的公共 WeatherForecast 类作为应用其他位置的组件中的 WeatherForecast 提供：

@using WeatherForecast = Components.Pages.GridRendering.WeatherForecast

还可以使用其完全限定的名称来引用组件，这时不需要 @using 指令。 以下示例直接引用应用的 AdminComponents/Pages 文件夹中的 ProductDetail 组件：

<BlazorSample.AdminComponents.Pages.ProductDetail />

使用 Razor 创建的组件的命名空间基于以下内容（按优先级顺序）：

• Razor 文件标记中的 @namespace 指令（例如 @namespace BlazorSample.CustomNamespace）。
• 项目文件中项目的 RootNamespace（例如 <RootNamespace>BlazorSample</RootNamespace>）。
• 项目命名空间和从项目根目录到组件的路径。 例如，框架将具有项目命名空间 BlazorSample 的 {PROJECT NAMESPACE}/Components/Pages/Home.razor 解析到 Home 组件的命名空间 BlazorSample.Components.Pages。 {PROJECT NAMESPACE} 为项目命名空间。 组件遵循 C# 名称绑定规则。 对于本示例中的 Home 组件，范围内的组件是所有组件：
  • 在同一文件夹 Components/Pages 中。
  • 未显式指定其他命名空间的项目根中的组件。

不支持以下项目：

• global:: 限定。
• 部分限定的名称。 例如，无法将 @using BlazorSample.Components 添加到组件中，然后使用 <Layout.NavMenu></Layout.NavMenu> 在应用的 Components/Layout 文件夹中引用 NavMenu 组件 (Components/Layout/NavMenu.razor)。

分部类支持

组件以 C# 分部类的形式生成，使用以下任一方法进行创作：

• 单个文件包含在一个或多个 @code 块、HTML 标记和 Razor 标记中定义的 C# 代码。 Blazor 项目模板使用此单文件方法来定义其组件。
• HTML 和 Razor 标记位于 Razor 文件 (.razor) 中。 C# 代码位于定义为分部类的代码隐藏文件 (.cs) 中。

说明

定义特定于组件的样式的组件样式表是单独的文件 (.css)。 Blazor CSS 隔离稍后在 ASP.NET Core Blazor CSS 隔离 中进行介绍。

下面的示例显示了从 Blazor 项目模板生成的应用中具有 @code 块的默认 Counter 组件。 标记和 C# 代码位于同一个文件中。 这是在创作组件时采用的最常见方法。

Counter.razor：

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

以下 Counter 组件使用带有分部类的代码隐藏文件从 C# 代码中拆分呈现 HTML 和 Razor 标记。 一些组织和开发人员倾向于从 C# 代码拆分标记，借此组织其组件代码来适应他们偏好的工作方式。 例如，组织的 UI 专家可以独自处理呈现层，而不必依赖处理组件的 C# 逻辑的另一位开发人员。 使用自动生成的代码或源生成器时，此方法也很有用。 有关详细信息，请参阅分部类和方法（C# 编程指南）。

CounterPartialClass.razor：

@page "/counter-partial-class"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

CounterPartialClass.razor.cs：

namespace BlazorSample.Components.Pages;

public partial class CounterPartialClass
{
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

_Imports.razor 文件中的 @using 指令仅适用于 Razor 文件 (.razor)，而不适用于 C# 文件 (.cs)。 根据需要将命名空间添加到分部类文件中。

组件使用的典型命名空间：

using System.Net.Http;
using System.Net.Http.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Components.Authorization;
using Microsoft.AspNetCore.Components.Forms;
using Microsoft.AspNetCore.Components.Routing;
using Microsoft.AspNetCore.Components.Sections
using Microsoft.AspNetCore.Components.Web;
using static Microsoft.AspNetCore.Components.Web.RenderMode;
using Microsoft.AspNetCore.Components.Web.Virtualization;
using Microsoft.JSInterop;

典型命名空间还包含应用的命名空间以及与应用的 Components 文件夹对应的命名空间：

using BlazorSample;
using BlazorSample.Components;

还可以包含其他文件夹，例如 Layout 文件夹：

using BlazorSample.Components.Layout;

指定基类

@inherits 指令用于指定组件的基类。 与使用分部类不同，它仅从 C# 逻辑拆分标记，使用基类可以继承 C# 代码，以便在共用基类的属性和方法的一组组件之间使用。 使用基类可减少应用中的代码冗余，在将基代码从类库提供给多个应用时非常有用。 有关详细信息，请参阅 C# 和 .NET 中的继承。

在下面的示例中，BlazorRocksBase1 基类派生自 ComponentBase。

BlazorRocks1.razor：

@page "/blazor-rocks-1"
@inherits BlazorRocksBase1

<PageTitle>Blazor Rocks!</PageTitle>

<h1>Blazor Rocks! Example 1</h1>

<p>
    @BlazorRocksText
</p>

BlazorRocksBase1.cs：

using Microsoft.AspNetCore.Components;

namespace BlazorSample;

public class BlazorRocksBase1 : ComponentBase
{
    public string BlazorRocksText { get; set; } =
        "Blazor rocks the browser!";
}

路由

可以通过使用 @page 指令为应用中的每个可访问组件提供路由模板来实现 Blazor 中的路由。 编译具有 @page 指令的 Razor 文件时，将为生成的类提供指定路由模板的 RouteAttribute。 在运行时，路由器将使用 RouteAttribute 搜索组件类，并呈现具有与请求的 URL 匹配的路由模板的任何组件。

以下 HelloWorld 组件使用 /hello-world的路由模板，并且组件的呈现网页在相对 URL /hello-world 到达。

HelloWorld.razor：

@page "/hello-world"

<PageTitle>Hello World!</PageTitle>

<h1>Hello World!</h1>

前面的组件在浏览器中通过 /hello-world 进行加载，无论是否将组件添加到应用的 UI 导航。 （可选）组件可以添加到 NavMenu 组件，以便在应用基于 UI 的导航中显示组件链接。

对于前面的 HelloWorld 组件，可以将 NavLink 组件添加到 NavMenu 组件。 有关详细信息（包括对 NavLink 和 NavMenu 组件的描述），请参阅 ASP.NET Core Blazor 路由和导航。

标记

组件的 UI 使用由 Razor 标记、C# 和 HTML 组成的 Razor 语法进行定义。 在编译应用时，HTML 标记和 C# 呈现逻辑转换为组件类。 生成的类的名称与文件名匹配。

组件类的成员在一个或多个 @code 块中定义。 在 @code 块中，组件状态使用 C# 进行指定和处理：

• 属性和字段初始化表达式。
• 由父组件和路由参数传递的自变量的参数值。
• 用于用户事件处理、生命周期事件和自定义组件逻辑的方法。

组件成员使用以 @ 符号开头的 C# 表达式在呈现逻辑中进行使用。 例如，通过为字段名称添加 @ 前缀来呈现 C# 字段。 下面 Markup 示例计算并呈现：

• headingFontStyle，表示标题元素的 CSS 属性值 font-style。
• headingText，表示标题元素的内容。

Markup.razor：

@page "/markup"

<PageTitle>Markup</PageTitle>

<h1>Markup Example</h1>

<h2 style="font-style:@headingFontStyle">@headingText</h2>

@code {
    private string headingFontStyle = "italic";
    private string headingText = "Put on your new Blazor!";
}

说明

Blazor 文档中的示例会为私有成员指定 private 访问修饰符。 私有成员的范围限定为组件的类。 但是，C# 会在没有访问修饰符存在时采用 private 访问修饰符，因此在自己的代码中将成员显式标记为“private”是可选的。 有关访问修饰符的详细信息，请参阅访问修饰符（C# 编程指南）。

Blazor 框架在内部将组件作为呈现树进行处理，该树是组件的文档对象模型 (DOM) 和级联样式表对象模型 (CSSOM) 的组合。 最初呈现组件后，会重新生成组件的呈现树以响应事件。 Blazor 会将新呈现树与以前的呈现树进行比较，并将所有修改应用于浏览器的 DOM 以进行显示。 有关详细信息，请参阅 ASP.NET Core Razor 组件呈现。

C# 控件结构、指令和指令属性的 Razor 语法需要小写（示例：@if、@code、@bind）。 属性名称需要大写（示例：LayoutComponentBase.Body 的 @Body）。

异步方法 (async) 不支持返回 void

Blazor 框架不跟踪返回 void 的异步方法 (async)。 因此，如果 void 返回，则不会捕获异常。 始终从异步方法返回 Task。

嵌套组件

通过使用 HTML 语法声明组件，组件可以包含其他组件。 使用组件的标记类似于 HTML 标记，其中标记的名称是组件类型。

请考虑以下 Heading 组件，其他组件可以使用该组件显示标题。

Heading.razor：

<h1 style="font-style:@headingFontStyle">Heading Example</h1>

@code {
    private string headingFontStyle = "italic";
}

HeadingExample 组件中的以下标记会在 <Heading /> 标记出现的位置呈现前面的 Heading 组件。

HeadingExample.razor：

@page "/heading-example"

<PageTitle>Heading</PageTitle>

<h1>Heading Example</h1>

<Heading />

如果某个组件包含一个 HTML 元素，该元素的大写首字母与相同命名空间中的组件名称不匹配，则会发出警告，指示该元素名称异常。 为组件的命名空间添加 @using 指令使组件可用，这可解决此警告。 有关详细信息，请参阅组件名称、类名和命名空间部分。

此部分中显示的 Heading 组件示例没有 @page 指令，因此用户无法在浏览器中通过直接请求直接访问 Heading 组件。 但是，具有 @page 指令的任何组件都可以嵌套在另一个组件中。 如果通过在 Razor 文件顶部包含 @page "/heading" 可直接访问 Heading组件，则会在 /heading 和 /heading-example 处为浏览器请求呈现该组件。

组件参数

组件参数将数据传递给组件，使用组件类中包含 [Parameter] 特性的公共 C# 属性进行定义。 在下面的示例中，内置引用类型 (System.String) 和用户定义的引用类型 (PanelBody) 作为组件参数进行传递。

PanelBody.cs：

namespace BlazorSample;

public class PanelBody
{
    public string? Text { get; set; }
    public string? Style { get; set; }
}

ParameterChild.razor：

<div class="card w-25" style="margin-bottom:15px">
    <div class="card-header font-weight-bold">@Title</div>
    <div class="card-body" style="font-style:@Body.Style">
        @Body.Text
    </div>
</div>

@code {
    [Parameter]
    public string Title { get; set; } = "Set By Child";

    [Parameter]
    public PanelBody Body { get; set; } =
        new()
        {
            Text = "Set by child.",
            Style = "normal"
        };
}

警告

支持为组件参数提供初始值，但不会创建在首次呈现后向自身参数写入的组件。 有关详细信息，请参阅避免覆盖 ASP.NET Core Blazor 中的参数。

ParameterChild 组件的 Title 和 Body 组件参数通过自变量在呈现组件实例的 HTML 标记中进行设置。 以下 ParameterParent 组件会呈现两个 ParameterChild 组件：

• 第一个 ParameterChild 组件在呈现时不提供参数自变量。
• 第二个 ParameterChild 组件从 ParameterParent 组件接收 Title 和 Body 的值，后者使用显式 C# 表达式设置 PanelBody 的属性值。

Parameter1.razor：

@page "/parameter-1"

<PageTitle>Parameter 1</PageTitle>

<h1>Parameter Example 1</h1>

<h1>Child component (without attribute values)</h1>

<ParameterChild />

<h1>Child component (with attribute values)</h1>

<ParameterChild Title="Set by Parent"
                Body="@(new PanelBody() { Text = "Set by parent.", Style = "italic" })" />

当 ParameterParent 组件未提供组件参数值时，来自 ParameterParent 组件的以下呈现 HTML 标记会显示 ParameterChild 组件默认值。 当 ParameterParent 组件提供组件参数值时，它们会替换 ParameterChild 组件的默认值。

说明

为清楚起见，呈现 CSS 样式类未显示在以下呈现 HTML 标记中。

<h1>Child component (without attribute values)</h1>

<div>
    <div>Set By Child</div>
    <div>Set by child.</div>
</div>

<h1>Child component (with attribute values)</h1>

<div>
    <div>Set by Parent</div>
    <div>Set by parent.</div>
</div>

将方法的 C# 字段、属性或结果作为 HTML 特性值分配给组件参数。 特性的值通常可以是与参数类型匹配的任何 C# 表达式。 特性的值可以选择以 Razor 保留 @ 符号开头，但不是必需的。

如果组件参数的类型为字符串，则默认情况下会将特性值视为 C# 字符串字面量。 如果要改为指定 C# 表达式，请使用 @ 前缀。

以下 ParameterParent2 组件显示前面 ParameterChild 组件的四个实例，并将其 Title 参数值设置为：

• title 字段的值。
• GetTitle C# 方法的结果。
• 带有ToLongDateString 的长格式当前本地日期，使用隐式 C# 表达式。
• panelData 对象的 Title 属性。

在大多数情况下，根据 HTML5 规范，参数属性值的引号是可选的。 例如，支持 Value=this，而不是 Value="this"。 但是，我们建议使用引号，因为它更易于记住，并且在基于 Web 的技术中被广泛采用。

在整个文档中，代码示例：

• 始终使用引号。 示例：Value="this"。
• 除非必要，否则不要将 @ 前缀与非文本一起使用。 示例：Count="ct"，其中 ct 是数字类型的变量。 Count="@ct" 是一种有效的风格方法，但文档和示例不采用约定。
• 对于 Razor 表达式之外的文本始终避免使用 @。 示例：IsFixed="true"。 这包括关键字（例如 this）和 null，但你可以根据需要选择使用它们。 例如，IsFixed="@true" 不常见，但受支持。

Parameter2.razor：

@page "/parameter-2"

<PageTitle>Parameter 2</PageTitle>

<h1>Parameter Example 2</h1>

<ParameterChild Title="@title" />

<ParameterChild Title="@GetTitle()" />

<ParameterChild Title="@DateTime.Now.ToLongDateString()" />

<ParameterChild Title="@panelData.Title" />

@code {
    private string title = "From Parent field";
    private PanelData panelData = new();

    private string GetTitle()
    {
        return "From Parent method";
    }

    private class PanelData
    {
        public string Title { get; set; } = "From Parent object";
    }
}

说明

将 C# 成员分配给组件参数时，不要使用 @ 为参数的 HTML 特性添加前缀。

正确（Title 是字符串参数， Count 是数字类型的参数）：

<ParameterChild Title="@title" Count="ct" />

<ParameterChild Title="@title" Count="@ct" />

不正确：

<ParameterChild @Title="@title" @Count="ct" />

<ParameterChild @Title="@title" @Count="@ct" />

与 Razor 页面 (.cshtml) 不同，在呈现组件时，Blazor 不能在 Razor 表达式中执行异步工作。 这是因为 Blazor 是为呈现交互式 UI 而设计的。 在交互式 UI 中，屏幕必须始终显示某些内容，因此阻止呈现流是没有意义的。 相反，异步工作是在一个异步生命周期事件期间执行的。 在每个异步生命周期事件之后，组件可能会再次呈现。 不支持以下 Razor 语法：

<ParameterChild Title="@await ..." />

生成应用时，前面示例中的代码会生成编译器错误：

“await”运算符只能用于异步方法中。 请考虑用“async”修饰符标记此方法，并将其返回类型更改为“Task”。

若要在前面的示例中异步获取 Title 参数的值，组件可以使用 OnInitializedAsync 生命周期事件，如以下示例所示：

<ParameterChild Title="@title" />

@code {
    private string? title;
    
    protected override async Task OnInitializedAsync()
    {
        title = await ...;
    }
}

有关详细信息，请参阅 ASP.NET Core Razor 组件生命周期。

不支持使用显式 Razor 表达式连接文本和表达式结果以赋值给参数。 下面的示例尝试将文本“Set by ”与对象属性值连接在一起。 尽管 Razor 页面 (.cshtml) 支持此语法，但对在组件中赋值给子级的 Title 参数无效。 不支持以下 Razor 语法：

<ParameterChild Title="Set by @(panelData.Title)" />

生成应用时，前面示例中的代码会生成编译器错误：

组件属性不支持复杂内容（混合 C# 和标记）。

若要支持组合值赋值，请使用方法、字段或属性。 下面的示例在 C# 方法 GetTitle 中将“Set by ”与对象属性值连接在一起：

Parameter3.razor：

@page "/parameter-3"

<PageTitle>Parameter 3</PageTitle>

<h1>Parameter Example 3</h1>

<ParameterChild Title="@GetTitle()" />

@code {
    private PanelData panelData = new();

    private string GetTitle() => $"Set by {panelData.Title}";

    private class PanelData
    {
        public string Title { get; set; } = "Parent";
    }
}

有关详细信息，请参阅 ASP.NET Core 的 Razor 语法参考。

警告

支持为组件参数提供初始值，但不会创建在首次呈现后向自身参数写入的组件。 有关详细信息，请参阅避免覆盖 ASP.NET Core Blazor 中的参数。

应将组件参数声明为自动属性，这意味着它们不应在其 get 或 set 访问器中包含自定义逻辑。 例如，下面的 StartData 属性是自动属性：

[Parameter]
public DateTime StartData { get; set; }

不要在 get 或 set 访问器中放置自定义逻辑，因为组件参数专门用作父组件向子组件传送信息的通道。 如果子组件属性的 set 访问器包含导致父组件重新呈现的逻辑，则会导致一个无限的呈现循环。

若要转换已接收的参数值，请执行以下操作：

• 将参数属性保留为自动属性，以表示所提供的原始数据。
• 创建另一个属性或方法，用于基于参数属性提供转换后的数据。

替代 OnParametersSetAsync 以在每次收到新数据时转换接收到的参数。

支持将初始值写入组件参数，因为初始值赋值不会干扰 Blazor 的自动组件呈现。 在组件中，使用 DateTime.Now 将当前本地 DateTime 赋予 StartData 是有效语法：

[Parameter]
public DateTime StartData { get; set; } = DateTime.Now;

进行 DateTime.Now 的初始赋值之后，请勿在开发人员代码中向 StartData 赋值。 有关详细信息，请参阅避免覆盖 ASP.NET Core Blazor 中的参数。

应用 [EditorRequired] 特性以指定所需的组件参数。 如果未提供参数值，编辑器或生成工具可能会向用户显示警告。 此特性仅在也用 [Parameter] 特性标记的属性上有效。 在设计时和生成应用时需强制使用 EditorRequiredAttribute。 在运行时则不强制使用该特性，因为它无法保证非 null 的参数值。

[Parameter]
[EditorRequired]
public string? Title { get; set; }

还支持单行特性列表：

[Parameter, EditorRequired]
public string? Title { get; set; }

不要对组件参数属性使用 required 修饰符 或 init 访问器。 组件通常使用反射实例化和分配参数值，从而绕过了 init 和 required 本应做出的保证。 请改为使用 [EditorRequired] 特性以指定所需的组件参数。

组件参数和 RenderFragment 类型支持 Tuples（API 文档）。 下面的组件参数示例在 Tuple 中传递三个值：

RenderTupleChild.razor：

<div class="card w-50" style="margin-bottom:15px">
    <div class="card-header font-weight-bold">Tuple Card</div>
    <div class="card-body">
        <ul>
            <li>Integer: @Data?.Item1</li>
            <li>String: @Data?.Item2</li>
            <li>Boolean: @Data?.Item3</li>
        </ul>
    </div>
</div>

@code {
    [Parameter]
    public (int, string, bool)? Data { get; set; }
}

RenderTupleParent.razor：

@page "/render-tuple-parent"

<PageTitle>Render Tuple Parent</PageTitle>

<h1>Render Tuple Parent Example</h1>

<RenderTupleChild Data="data" />

@code {
    private (int, string, bool) data = new(999, "I aim to misbehave.", true);
}

支持命名元组，如以下示例所示：

NamedTupleChild.razor：

<div class="card w-50" style="margin-bottom:15px">
    <div class="card-header font-weight-bold">Tuple Card</div>
    <div class="card-body">
        <ul>
            <li>Integer: @Data?.TheInteger</li>
            <li>String: @Data?.TheString</li>
            <li>Boolean: @Data?.TheBoolean</li>
        </ul>
    </div>
</div>

@code {
    [Parameter]
    public (int TheInteger, string TheString, bool TheBoolean)? Data { get; set; }
}

NamedTuples.razor：

@page "/named-tuples"

<PageTitle>Named Tuples</PageTitle>

<h1>Named Tuples Example</h1>

<NamedTupleChild Data="data" />

@code {
    private (int TheInteger, string TheString, bool TheBoolean) data = 
        new(999, "I aim to misbehave.", true);
}

引用 ©2005 环球影业：冲出宁静号（内森·菲利安）

路由参数

组件可以在 @page 指令的路由模板中指定路由参数。 Blazor 路由器使用路由参数来填充相应的组件参数。

RouteParameter1.razor：

@page "/route-parameter-1/{text}"

<PageTitle>Route Parameter 1</PageTitle>

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }
}

有关详细信息，请参阅 ASP.NET Core Blazor 路由和导航的“路由参数”部分。 另外还支持可选路由参数，它们在同一部分中有介绍。 有关捕获跨越多个文件夹边界的路径的 catch-all 路由参数 ({*pageRoute}) 的信息，请参阅 ASP.NET Core Blazor 路由和导航的“Catch-all 路由参数”部分。

子内容呈现片段

组件可以设置另一个组件的内容。 分配组件提供子组件的开始标记与结束标记之间的内容。

在下面的示例中，RenderFragmentChild 组件具有一个 ChildContent 组件参数，它将要呈现的 UI 段表示为 RenderFragment。 ChildContent 在组件 Razor 标记中的位置是在最终 HTML 输出中呈现内容的位置。

RenderFragmentChild.razor：

<div class="card w-25" style="margin-bottom:15px">
    <div class="card-header font-weight-bold">Child content</div>
    <div class="card-body">@ChildContent</div>
</div>

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

重要事项

必须按约定将接收 RenderFragment 内容的属性命名为 ChildContent。

RenderFragment 不支持事件回叫。

以下组件通过将内容置于子组件的开始标记和结束标记内，来提供用于呈现 RenderFragmentChild 的内容。

RenderFragments.razor：

@page "/render-fragments"

<PageTitle>Render Fragments</PageTitle>

<h1>Render Fragments Example</h1>

<RenderFragmentChild>
    Content of the child component is supplied
    by the parent component.
</RenderFragmentChild>

由于 Blazor 呈现子内容的方式，如果在 RenderFragmentChild 组件的内容中使用递增循环变量，则在 for 循环内呈现组件需要本地索引变量。 下面的示例可以添加到前面的父组件：

<h1>Three children with an index variable</h1>

@for (int c = 0; c < 3; c++)
{
    var current = c;

    <RenderFragmentChild>
        Count: @current
    </RenderFragmentChild>
}

或者，将 foreach 循环与 Enumerable.Range 结合使用，而不是使用 for 循环。 下面的示例可以添加到前面的父组件：

<h1>Second example of three children with an index variable</h1>

@foreach (var c in Enumerable.Range(0,3))
{
    <RenderFragmentChild>
        Count: @c
    </RenderFragmentChild>
}

呈现片段用于在整个 Blazor 应用中呈现子内容，在下面的文章和文章部分中有示例介绍：

• Blazor 布局
• 跨组件层次结构传递数据
• 模板化组件
• 全局异常处理

说明

Blazor 框架的内置 Razor 组件使用相同的 ChildContent 组件参数约定来设置其内容。 可以通过在 API 文档（使用搜索词“ChildContent”筛选 API）中搜索组件参数属性名称 ChildContent 来查看设置子内容的组件。

可重用呈现逻辑的呈现片段

你可以分解出子组件，纯粹作为重复使用呈现逻辑的方法。 在任何组件的 @code 块中，根据需要定义 RenderFragment 并呈现任意位置的片段：

@RenderWelcomeInfo

<p>Render the welcome info a second time:</p>

@RenderWelcomeInfo

@code {
    private RenderFragment RenderWelcomeInfo =  @<p>Welcome to your new app!</p>;
}

有关详细信息，请参阅重复使用呈现逻辑。

捕获对组件的引用

组件引用提供了一种引用组件实例以便发出命令的方法。 若要捕获组件引用，请执行以下操作：

• 向子组件添加 @ref 特性。
• 定义与子组件类型相同的字段。

呈现组件时，将用组件实例填充字段。 然后，可以在实例上调用 .NET 方法。

请考虑以下 ReferenceChild 组件，它会在调用其 ChildMethod 时记录消息。

ReferenceChild.razor：

@inject ILogger<ReferenceChild> Logger

@if (value > 0)
{
    <p>
        <code>value</code>: @value
    </p>
}

@code {
    private int value;

    public void ChildMethod(int value)
    {
        Logger.LogInformation("Received {Value} in ChildMethod", value);

        this.value = value;
        StateHasChanged();
    }
}

组件引用仅在呈现组件后才进行填充，其输出包含 ReferenceChild 的元素。 在呈现组件之前，没有任何可引用的内容。 请勿尝试直接将引用的组件方法调用事件处理程序（例如 @onclick="childComponent!.ChildMethod(5)"），因为在分配单击事件时可能不会分配引用变量。

若要在组件完成呈现后操作组件引用，请使用 OnAfterRender 或 OnAfterRenderAsync 方法。

以下示例使用了前面的 ReferenceChild 组件。

ReferenceParent.razor：

@page "/reference-parent"

<div>
    <button @onclick="@(() => childComponent1!.ChildMethod(5))">
        Call <code>ReferenceChild.ChildMethod</code> (first instance) 
        with an argument of 5
    </button>

    <ReferenceChild @ref="childComponent1" />
</div>

<div>
    <button @onclick="CallChildMethod">
        Call <code>ReferenceChild.ChildMethod</code> (second instance) 
        with an argument of 5
    </button>

    <ReferenceChild @ref="childComponent2" />
</div>

@code {
    private ReferenceChild? childComponent1;
    private ReferenceChild? childComponent2;

    private void CallChildMethod()
    {
        childComponent2!.ChildMethod(5);
    }
}

尽管捕获组件引用使用与捕获元素引用类似的语法，但捕获组件引用不是 JavaScript 互操作功能。 组件引用不会传递给 JavaScript 代码。 组件引用只在 .NET 代码中使用。

重要事项

不要使用组件引用来改变子组件的状态。 请改用常规声明性组件参数将数据传递给子组件。 使用组件参数使子组件在正确的时间自动重新呈现。 有关详细信息，请参阅组件参数部分和 ASP.NET Core Blazor 数据绑定一文。

应用属性

可以通过 @attribute 指令将特性应用于组件。 下面的示例将 [Authorize] 特性应用于组件的类：

@page "/"
@attribute [Authorize]

条件 HTML 元素属性

HTML 元素特性属性基于 .NET 值有条件地设置。 如果值为 false 或 null，则属性未设置。 如果值为 true，则属性已设置。

在下面的示例中，IsCompleted 确定是否设置了 <input> 元素的 checked 属性。

ConditionalAttribute.razor：

@page "/conditional-attribute"

<PageTitle>Conditional Attribute</PageTitle>

<h1>Conditional Attribute Example</h1>

<label>
    <input type="checkbox" checked="@IsCompleted" />
    Is Completed?
</label>

<button @onclick="@(() => IsCompleted = !IsCompleted)">
    Change IsCompleted
</button>

@code {
    [Parameter]
    public bool IsCompleted { get; set; }
}

有关详细信息，请参阅 ASP.NET Core 的 Razor 语法参考。

警告

当 .NET 类型为 bool 时，某些 HTML 特性（如 aria-pressed）无法正常运行。 在这些情况下，请使用 string 类型，而不是 bool。

原始 HTML

通常使用 DOM 文本节点呈现字符串，这意味着将忽略它们可能包含的任何标记，并将其视为文字文本。 若要呈现原始 HTML，请将 HTML 内容包装在 MarkupString 值中。 将该值分析为 HTML 或 SVG，并插入到 DOM 中。

警告

呈现从任何不受信任的源构造的原始 HTML 存在安全风险，应始终避免。

下面的示例演示如何使用 MarkupString 类型向组件的呈现输出添加静态 HTML 内容块。

MarkupStrings.razor：

@page "/markup-strings"

<PageTitle>Markup Strings</PageTitle>

<h1>Markup Strings Example</h1>

@((MarkupString)myMarkup)

@code {
    private string myMarkup =
        "<p class=\"text-danger\">This is a dangerous <em>markup string</em>.</p>";
}

Razor 模板

可以使用 Razor 模板语法定义呈现片段，从而定义 UI 片段。 Razor 模板使用以下格式：

@<{HTML tag}>...</{HTML tag}>

下面的示例演示如何在组件中指定 RenderFragment 和 RenderFragment<TValue> 值并直接呈现模板。 还可以将呈现片段作为参数传递给模板化组件。

RazorTemplate.razor：

@page "/razor-template"

<PageTitle>Razor Template</PageTitle>

<h1>Razor Template Example</h1>

@timeTemplate

@petTemplate(new Pet { Name = "Nutty Rex" })

@code {
    private RenderFragment timeTemplate = @<p>The time is @DateTime.Now.</p>;
    private RenderFragment<Pet> petTemplate = (pet) => @<p>Pet: @pet.Name</p>;

    private class Pet
    {
        public string? Name { get; set; }
    }
}

以上代码的呈现输出：

<p>The time is 4/19/2021 8:54:46 AM.</p>
<p>Pet: Nutty Rex</p>

静态资产

Blazor 遵循 ASP.NET Core 应用对于静态资产的约定。 静态资产位于项目的 web root (wwwroot) 文件夹中或是 wwwroot 文件夹下的文件夹中。

使用基相对路径 (/) 来引用静态资产的 Web 根。 在下面的示例中，logo.png 实际位于 {PROJECT ROOT}/wwwroot/images 文件夹中。 {PROJECT ROOT} 是应用的项目根。

<img alt="Company logo" src="/images/logo.png" />

组件不支持波浪符斜杠表示法 (~/)。

有关设置应用基本路径的信息，请参阅托管和部署 ASP.NET Core Blazor。

组件中不支持标记帮助程序

组件中不支持 Tag Helpers。 若要在 Blazor 中提供类似标记帮助程序的功能，请创建一个具有与标记帮助程序相同功能的组件，并改为使用该组件。

可缩放的向量图形 (SVG) 图像

由于 Blazor 呈现 HTML，因此通过 <img> 标记支持浏览器支持的图像，包括可缩放的矢量图形 (SVG) 图像 (.svg)：

<img alt="Example image" src="image.svg" />

同样，样式表文件 (.css) 的 CSS 规则支持 SVG 图像：

.element-class {
    background-image: url("image.svg");
}

Blazor 支持 <foreignObject> 元素在 SVG 中显示任意 HTML。 标记可表示任意 HTML、RenderFragment 或 Razor 组件。

下面的示例展示了如何：

• string (@message) 的显示情况。
• 具有 <input> 元素和 value 字段的双向绑定。
• Robot 组件。

<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
    <rect x="0" y="0" rx="10" ry="10" width="200" height="200" stroke="black" 
        fill="none" />
    <foreignObject x="20" y="20" width="160" height="160">
        <p>@message</p>
    </foreignObject>
</svg>

<svg xmlns="http://www.w3.org/2000/svg">
    <foreignObject width="200" height="200">
        <label>
            Two-way binding:
            <input @bind="value" @bind:event="oninput" />
        </label>
    </foreignObject>
</svg>

<svg xmlns="http://www.w3.org/2000/svg">
    <foreignObject>
        <Robot />
    </foreignObject>
</svg>

@code {
    private string message = "Lorem ipsum dolor sit amet, consectetur adipiscing " +
        "elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";

    private string? value;
}

空白的呈现行为

除非将 @preservewhitespace 指令与值 true 一起使用，否则在以下情况下默认删除额外的空白：

• 元素中的前导或尾随空白。
• RenderFragment/RenderFragment<TValue> 参数中的前导或尾随（例如，传递到另一个组件的子内容）。
• 在 C# 代码块（例如 @if 和 @foreach）之前或之后。

但是，在使用 CSS 规则（例如 white-space: pre）时，删除空白可能会影响呈现输出。 若要禁用此性能优化并保留空白，请执行以下任一操作：

• 将 @preservewhitespace true 指令添加到 Razor 文件 (.razor) 的顶部，从而将首选项应用于特定组件。
• 将 @preservewhitespace true 指令添加到 _Imports.razor 文件中，从而将首选项应用于子目录或整个项目。

在大多数情况下，不需要执行任何操作，因为应用程序通常会继续正常运行（但速度会更快）。 如果去除空白会导致特定组件出现呈现问题，请在该组件中使用 @preservewhitespace true 来禁用此优化。

根组件

根 Razor 组件（根组件）是加载应用创建的任何组件层次结构的第一个组件。

在从 Blazor Web App 项目模板创建的应用中，App 组件 (App.razor) 由向服务器侧 Program 文件调用 MapRazorComponents<TRootComponent> 声明的类型参数指定为默认根组件。 以下示例演示如何使用 App 组件作为根组件，这是从 Blazor 项目模板创建的应用的默认组件：

app.MapRazorComponents<App>();

注意

不支持让根组件具有交互性（例如 App 组件）。

在从 Blazor WebAssembly 项目模板创建的应用中，将 App 组件 (App.razor) 指定为 Program 文件中的默认根组件：

builder.RootComponents.Add<App>("#app");

在前面的代码中，CSS 选择器 #app 指示为 wwwroot/index.html 中的 <div> 指定了 App 组件，其中 id 为 app：

<div id="app">...</app>

MVC 和 Razor Pages 应用还可以使用组件标记帮助程序来注册静态呈现的 Blazor WebAssembly 根组件：

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

静态呈现的组件只能添加到应用。 之后无法移除或更新它们。

有关更多信息，请参见以下资源：

• ASP.NET Core 中的组件标记帮助程序
• 将 ASP.NET Core Razor 组件集成到 ASP.NET Core 应用中