ASP.NET Core 中的组件标记帮助程序

组件标记帮助程序在 Razor Pages 页面或 MVC 视图中呈现 Razor 组件。

先决条件

按照集成 ASP.NET Core Razor 组件到 ASP.NET Core 应用文章的页面或视图部分中的“使用不可路由组件”部分中的指导进行操作。

组件标记帮助程序

若要从页面或视图呈现组件，请使用组件标记帮助程序（<component> 标记）。

RenderMode 配置组件是否：

• 在页面中预呈现。
• 在页面上呈现为静态 HTML，或者包含从用户代理启动 Blazor 应用所需的信息。

下表显示了 Blazor WebAssembly 应用呈现模式。

呈现模式	描述
WebAssembly	呈现 Blazor WebAssembly 应用程序的标记，以便在浏览器中进行加载时包含交互式组件。 不预呈现组件。 通过此选项，可以在不同的页面轻松呈现各种 Blazor WebAssembly 组件。
WebAssemblyPrerendered	在静态 HTML 中预呈现组件，并包含 Blazor WebAssembly 应用的标记，以便稍后在浏览器中进行加载时使组件成为交互式组件。

下表显示了呈现模式。

呈现模式	说明
ServerPrerendered	在静态 HTML 中呈现组件，并包含服务器端 Blazor 应用的标记。 用户代理启动时，此标记用于启动 Blazor 应用。
Server	呈现服务器端 Blazor 应用的标记。 不包括组件的输出。 用户代理启动时，此标记用于启动 Blazor 应用。
Static	将组件呈现为静态 HTML。

其他特征包括：

• 允许多个组件标记帮助程序呈现多个 Razor 组件。
• 应用启动后，无法动态呈现组件。
• 尽管页面和视图可以使用组件，但反过来则不行。 组件无法使用特定于视图和页面的功能，例如分部视图和部分。 若要在组件中使用分部视图中的逻辑，请将分部视图逻辑分解到组件中。
• 不支持从静态 HTML 页面呈现服务器组件。

以下组件标记帮助程序使用 ServerPrerendered 在服务器端 Blazor 应用的页面或视图中呈现 EmbeddedCounter 组件：

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

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

上述示例假定 EmbeddedCounter 组件位于应用的 Components 文件夹中。 占位符 {APP ASSEMBLY} 是应用的程序集名称（例如 @using BlazorSample.Components）。

组件标记帮助程序还可以将参数传递给组件。 以下面设置复选框标签颜色和大小的 ColorfulCheckbox 组件为例。

Components/ColorfulCheckbox.razor：

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

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

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string? Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

Size (int) 和 Color (string) 组件参数可由组件标记帮助程序设置：

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

上述示例假定 ColorfulCheckbox 组件位于 Components 文件夹中。 占位符 {APP ASSEMBLY} 是应用的程序集名称（例如 @using BlazorSample.Components）。

以下 HTML 在页面或视图中呈现：

<label style="font-size:24px;color:blue">
    <input id="survey" name="blazor" type="checkbox">
    Enjoying Blazor?
</label>

传递带引号的字符串需要一个显式 Razor 表达式，如前面示例中的 param-Color 所示。 Razor 针对 string 类型值的分析行为不适用于 param-* 属性，因为该属性是 object 类型。

支持所有类型的参数，但以下参数除外：

• 泛型参数。
• 不可序列化的参数。
• 集合参数中的继承。
• 在 Blazor WebAssembly 应用之外或在延迟加载的程序集中定义类型的参数。
• 用于接收子内容的 RenderFragment 委托（例如 param-ChildContent="..."）。 对于这种情况，我们建议创建一个 Razor 组件 (.razor)，该组件使用要传递的子内容引用要呈现的组件，然后使用组件标记帮助程序从页面或视图调用 Razor 组件。

参数类型必须是 JSON 可序列化的，这通常意味着类型必须具有默认的构造函数和可设置的属性。 例如，你可以在前面的示例中为 Size 和 Color 指定一个值，因为 Size 和 Color 的类型是基元类型（int 和 string），这是 JSON 序列化程序支持的类型。

以下示例将一个类对象传递给组件：

MyClass.cs：

public class MyClass
{
    public MyClass()
    {
    }

    public int MyInt { get; set; } = 999;
    public string MyString { get; set; } = "Initial value";
}

类必须具有一个无参数的公共构造函数。

Components/ParameterComponent.razor：

<h2>ParameterComponent</h2>

<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>

@code
{
    [Parameter]
    public MyClass? MyObject { get; set; }
}

Pages/MyPage.cshtml：

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Components

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(ParameterComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

上述示例假定 ParameterComponent 组件位于应用的 Components 文件夹中。 占位符 {APP ASSEMBLY} 是应用的程序集名称（例如 @using BlazorSample 和 @using BlazorSample.Components）。 MyClass 在应用的命名空间中。

其他资源

• ASP.NET Core 中的持久化组件状态标记帮助程序
• 预呈现 ASP.NET Core Razor 组件
• ComponentTagHelper
• ASP.NET Core 中的标记帮助程序
• ASP.NET Core Razor 组件