动态呈现的 ASP.NET Core Razor 组件

作者：Dave Brock

使用内置 DynamicComponent 组件按类型呈现组件。

动态组件

DynamicComponent 适用于呈现组件，而无需循环访问可能的类型或使用条件逻辑。 例如，DynamicComponent 可以基于用户从下拉列表中选择的内容来呈现组件。

如下示例中：

• componentType 指定类型。
• parameters 指定要传递给 componentType 组件的组件参数。

<DynamicComponent Type="componentType" Parameters="parameters" />

@code {
    private Type componentType = ...;
    private IDictionary<string, object> parameters = ...;
}

有关传递参数值的详细信息，请参阅本文后面的传递参数部分。

示例

在下面的示例中，Razor 组件基于用户在四个可能值的下拉列表中选择的内容来呈现组件。

用户 spaceflight 运营商选择	共享 Razor 组件以呈现
Rocket Lab®	RocketLab.razor
SpaceX®	SpaceX.razor
ULA®	UnitedLaunchAlliance.razor
Virgin Galactic®	VirginGalactic.razor

RocketLab.razor:

<h2>Rocket Lab®</h2>

<p>
    Rocket Lab is a registered trademark of 
    <a href="https://www.rocketlabusa.com/">Rocket Lab USA Inc.</a>
</p>

SpaceX.razor:

<h2>SpaceX®</h2>

<p>
    SpaceX is a registered trademark of 
    <a href="https://www.spacex.com/">Space Exploration Technologies Corp.</a>
</p>

UnitedLaunchAlliance.razor:

<h2>United Launch Alliance®</h2>

<p>
    United Launch Alliance and ULA are registered trademarks of
    <a href="https://www.ulalaunch.com/">United Launch Alliance, LLC</a>.
</p>

VirginGalactic.razor:

<h2>Virgin Galactic®</h2>

<p>
    Virgin Galactic is a registered trademark of 
    <a href="https://www.virgingalactic.com/">Galactic Enterprises, LLC</a>.
</p>

DynamicComponent1.razor:

@page "/dynamic-component-1"

<PageTitle>Dynamic Component 1</PageTitle>

<h1>Dynamic Component Example 1</h1>

<p>
    <label>
        Select your transport:
        <select @onchange="OnDropdownChange">
            <option value="">Select a value</option>
            @foreach (var entry in components.Keys)
            {
                <option value="@entry">@entry</option>
            }
        </select>
    </label>
</p>

@if (selectedType is not null)
{
    <div class="border border-primary my-1 p-1">
        <DynamicComponent Type="selectedType" />
    </div>
}

@code {
    private readonly Dictionary<string, Type> components = new()
    {
        ["Rocket Lab"] = typeof(RocketLab),
        ["SpaceX"] = typeof(SpaceX),
        ["ULA"] = typeof(UnitedLaunchAlliance),
        ["Virgin Galactic"] = typeof(VirginGalactic)
    };
    private Type? selectedType;

    private void OnDropdownChange(ChangeEventArgs e)
    {
        if ((e.Value is string dropdownValue) && 
            !String.IsNullOrWhiteSpace(dropdownValue))
        {
            selectedType = components[dropdownValue];
        }
        else
        {
            selectedType = null;
        }
    }
}

在上面的示例中：

• Dictionary<TKey,TValue> 用于管理要显示的组件。
• 名称充当字典键，并作为选择选项提供。
• 组件类型通过使用 typeof 运算符存储为字典值。

传递参数

如果动态呈现的组件具有组件参数，请将它们作为 IDictionary<string, object> 传入 DynamicComponent。 string 是参数的名称，object 是参数的值。

下面的示例配置组件元数据对象 (ComponentMetadata)，以根据类型名称向动态呈现的组件提供参数值。 该示例只是可以采用的几种方法之一。 还可以从 web API、数据库或方法提供参数数据。 唯一的要求是方法返回 IDictionary<string, object>。

ComponentMetadata.cs:

namespace BlazorSample;

public class ComponentMetadata
{
    public required Type Type { get; init; }
    public required string Name { get; init; }
    public Dictionary<string, object> Parameters { get; } = [];
}

以下 RocketLabWithWindowSeat 组件 (RocketLabWithWindowSeat.razor) 已对前面的示例进行了更新，其中包含名为 WindowSeat 的组件参数，用于指定乘客是否更喜欢航班上的靠窗座位：

RocketLabWithWindowSeat.razor:

<h2>Rocket Lab®</h2>

<p>
    User selected a window seat: @WindowSeat
</p>

<p>
    Rocket Lab is a trademark of 
    <a href="https://www.rocketlabusa.com/">Rocket Lab USA Inc.</a>
</p>

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

在以下示例中：

• 只有靠窗座位 (WindowSeat) 的 RocketLabWithWindowSeat 组件参数会接收 Window Seat 复选框的值。
• 使用 nameof 运算符将组件名称作为常量字符串返回，将组件名称用作字典值。
• 动态呈现的组件是共享组件：
  • 本部分内容：RocketLabWithWindowSeat (RocketLabWithWindowSeat.razor)
  • 本文前面的示例部分所示的组件：
    • SpaceX （SpaceX.razor）
    • UnitedLaunchAlliance （UnitedLaunchAlliance.razor）
    • VirginGalactic （VirginGalactic.razor）

DynamicComponent2.razor:

@page "/dynamic-component-2"

<PageTitle>Dynamic Component 2</PageTitle>

<h1>Dynamic Component Example 2</h1>

<p>
    <label>
        <input type="checkbox" @bind="windowSeat" 
            @bind:after="HandleWindowSeatChanged" />
        Window Seat (Rocket Lab only)
    </label>
</p>

<p>
    <label>
        Select your transport:
        <select @onchange="OnDropdownChange">
            <option value="">Select a value</option>
            @foreach (var c in components)
            {
                <option value="@c.Key">@c.Value.Name</option>
            }
        </select>
    </label>
</p>

@if (selectedComponent is not null)
{
    <div class="border border-primary my-1 p-1">
        <DynamicComponent Type="selectedComponent.Type"
            Parameters="selectedComponent.Parameters" />
    </div>
}

@code {
    private Dictionary<string, ComponentMetadata> components =
        new()
        {
            [nameof(RocketLabWithWindowSeat)] = new ComponentMetadata()
            {
                Type = typeof(RocketLabWithWindowSeat),
                Name = "Rocket Lab with Window Seat",
                Parameters = { [nameof(RocketLabWithWindowSeat.WindowSeat)] = false }
            },
            [nameof(VirginGalactic)] = new ComponentMetadata()
            {
                Type = typeof(VirginGalactic),
                Name = "Virgin Galactic"
            },
            [nameof(UnitedLaunchAlliance)] = new ComponentMetadata()
            {
                Type = typeof(UnitedLaunchAlliance),
                Name = "ULA"
            },
            [nameof(SpaceX)] = new ComponentMetadata()
            {
                Type = typeof(SpaceX),
                Name = "SpaceX"
            }
        };
    private ComponentMetadata? selectedComponent;
    private bool windowSeat;

    private void HandleWindowSeatChanged()
    {
        components[nameof(RocketLabWithWindowSeat)]
            .Parameters[nameof(RocketLabWithWindowSeat.WindowSeat)] = windowSeat;
    }

    private void OnDropdownChange(ChangeEventArgs e)
    {
        if ((e.Value is string dropdownValue) && !String.IsNullOrWhiteSpace(dropdownValue))
        {
            selectedComponent = components[dropdownValue];
        }
        else
        {
            selectedComponent = null;
        }
    }
}

事件回调 (EventCallback)

事件回调 (EventCallback) 可以传递给参数字典中的 DynamicComponent。

ComponentMetadata.cs:

namespace BlazorSample;

public class ComponentMetadata
{
    public required Type Type { get; init; }
    public required string Name { get; init; }
    public Dictionary<string, object> Parameters { get; } = [];
}

在每个动态呈现的组件中实现事件回调参数 (EventCallback)。

RocketLab2.razor:

<h2>Rocket Lab®</h2>

<p>
    Rocket Lab is a registered trademark of
    <a href="https://www.rocketlabusa.com/">Rocket Lab USA Inc.</a>
</p>

<button @onclick="OnClickCallback">
    Trigger a Parent component method
</button>

@code {
    [Parameter]
    public EventCallback<MouseEventArgs> OnClickCallback { get; set; }
}

SpaceX2.razor:

<h2>SpaceX®</h2>

<p>
    SpaceX is a registered trademark of
    <a href="https://www.spacex.com/">Space Exploration Technologies Corp.</a>
</p>

<button @onclick="OnClickCallback">
    Trigger a Parent component method
</button>

@code {
    [Parameter]
    public EventCallback<MouseEventArgs> OnClickCallback { get; set; }
}

UnitedLaunchAlliance2.razor:

<h2>United Launch Alliance®</h2>

<p>
    United Launch Alliance and ULA are registered trademarks of
    <a href="https://www.ulalaunch.com/">United Launch Alliance, LLC</a>.
</p>

<button @onclick="OnClickCallback">
    Trigger a Parent component method
</button>

@code {
    [Parameter]
    public EventCallback<MouseEventArgs> OnClickCallback { get; set; }
}

VirginGalactic2.razor:

<h2>Virgin Galactic®</h2>

<p>
    Virgin Galactic is a registered trademark of
    <a href="https://www.virgingalactic.com/">Galactic Enterprises, LLC</a>.
</p>

<button @onclick="OnClickCallback">
    Trigger a Parent component method
</button>

@code {
    [Parameter]
    public EventCallback<MouseEventArgs> OnClickCallback { get; set; }
}

在以下父组件示例中，ShowDTMessage 方法将一个包含当前时间的字符串分配给 message，并呈现 message 的值。

父组件在参数字典中传递回调方法 ShowDTMessage：

• string 键是回调方法的名称 OnClickCallback。
• object 值由 EventCallbackFactory.Create 为父回调方法 ShowDTMessage 创建。 请注意，C# 字段初始化中不支持 this 关键字，因此 C# 属性用于参数字典。

DynamicComponent3.razor:

@page "/dynamic-component-3"

<PageTitle>Dynamic Component 3</PageTitle>

<h1>Dynamic Component Example 3</h1>

<p>
    <label>
        Select your transport:
        <select @onchange="OnDropdownChange">
            <option value="">Select a value</option>
            @foreach (var c in Components)
            {
                <option value="@c.Key">@c.Value.Name</option>
            }
        </select>
    </label>
</p>

@if (selectedComponent is not null)
{
    <div class="border border-primary my-1 p-1">
        <DynamicComponent Type="selectedComponent.Type"
            Parameters="selectedComponent.Parameters" />
    </div>
}

<p>
    @message
</p>

@code {
    private ComponentMetadata? selectedComponent;
    private string? message;

    private Dictionary<string, ComponentMetadata> Components =>
        new()
        {
            [nameof(RocketLab2)] = new ComponentMetadata()
            {
                Type = typeof(RocketLab2),
                Name = "Rocket Lab",
                Parameters = { [nameof(RocketLab2.OnClickCallback)] =
                    EventCallback.Factory.Create<MouseEventArgs>(this, ShowDTMessage) }
            },
            [nameof(VirginGalactic2)] = new ComponentMetadata()
            {
                Type = typeof(VirginGalactic2),
                Name = "Virgin Galactic",
                Parameters = { [nameof(VirginGalactic2.OnClickCallback)] =
                    EventCallback.Factory.Create<MouseEventArgs>(this, ShowDTMessage) }
            },
            [nameof(UnitedLaunchAlliance2)] = new ComponentMetadata()
            {
                Type = typeof(UnitedLaunchAlliance2),
                Name = "ULA",
                Parameters = { [nameof(UnitedLaunchAlliance2.OnClickCallback)] =
                    EventCallback.Factory.Create<MouseEventArgs>(this, ShowDTMessage) }
            },
            [nameof(SpaceX2)] = new ComponentMetadata()
            {
                Type = typeof(SpaceX2),
                Name = "SpaceX",
                Parameters = { [nameof(SpaceX2.OnClickCallback)] =
                    EventCallback.Factory.Create<MouseEventArgs>(this, ShowDTMessage) }
            }
        };

    private void OnDropdownChange(ChangeEventArgs e)
    {
        if ((e.Value is string dropdownValue) && !String.IsNullOrWhiteSpace(dropdownValue))
        {
            selectedComponent = Components[dropdownValue];
        }
        else
        {
            selectedComponent = null;
        }
    }

    private void ShowDTMessage(MouseEventArgs e) =>
        message = $"The current DT is: {DateTime.Now}.";
}

避免 catch-all 参数

避免使用 catch-all 参数。 如果使用了 catch-all 参数，则 DynamicComponent 上的每个显式参数都会成为无法传递给动态子级的保留字。 传递给 DynamicComponent 的任何新参数都是中断性变更，因为它们会开始隐藏恰好同名的子组件参数。 调用方不太可能始终了解要传递给所有可能的动态子级的一组固定的参数名称。

访问动态创建的组件实例

使用 Instance 属性访问动态创建的组件实例。

创建一个接口来描述动态创建的组件实例，以及在动态加载组件时需要从父组件访问的任何方法和属性。 以下示例指定了用于在组件中实现的 Log 方法。

Interfaces/ILoggable.cs:

using Microsoft.AspNetCore.Components;

namespace BlazorSample.Interfaces;

public interface ILoggable : IComponent
{
    public void Log();
}

每个组件定义实现接口。 以下示例来自示例部分中修改的 Rocket Lab® 组件，该组件通过其 Log 方法记录字符串。

RocketLab3.razor:

@using BlazorSample.Interfaces
@implements ILoggable
@inject ILogger<RocketLab3> Logger
    
<h2>Rocket Lab®</h2>

<p>
    Rocket Lab is a registered trademark of 
    <a href="https://www.rocketlabusa.com/">Rocket Lab USA Inc.</a>
</p>

@code {
    public void Log() => Logger.LogInformation("Woot! I logged this call!");
}

其余三个共享组件（VirginGalactic3、UnitedLaunchAlliance3、SpaceX3）受到类似的处理：

• 以下指令将添加到组件中，其中 {COMPONENT TYPE} 占位符是组件类型：

  @using BlazorSample.Interfaces
  @implements ILoggable
  @inject ILogger<{COMPONENT TYPE}> Logger
  

• 每个组件实现一种 Log 方法。 调用 LogInformation 时，记录器编写的日志类别包括组件类型的完全限定名：

  @code {
      public void Log()
      {
          Logger.LogInformation("Woot! I logged this call!");
      }
  }
  

父组件将动态加载的组件实例转换为 ILoggable 来访问接口的成员。 在以下示例中，在 UI 中选择按钮时，将调用加载组件的 Log 方法：

...
@using BlazorSample.Interfaces

...

<DynamicComponent Type="..." @ref="dc" />

...

<button @onclick="LogFromLoadedComponent">Log from loaded component</button>

@code {
    private DynamicComponent? dc;

    ...

    private void LogFromLoadedComponent() => (dc?.Instance as ILoggable)?.Log();
}

有关上述示例的工作演示，请参阅 Blazor 示例应用中的 DynamicComponent4 组件。

商标

Rocket Lab 是 Rocket Lab USA Inc. 的注册商标。SpaceX 是 Space Exploration Technologies Corp. 的注册商标。United Launch Alliance 和 ULA 是 United Launch Alliance, LLC 的注册商标。 Virgin Galactic 是 Galactic Enterprises, LLC 的注册商标。

其他资源

• ASP.NET Core Blazor 事件处理
• DynamicComponent