動態轉譯的 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 元件會根據使用者從四個可能值的下拉式清單中選取的項目來轉譯元件。

使用者航太承運業者選取	要轉譯的共用 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; }
}

在以下範例中：

• 只有靠窗座位的 RocketLabWithWindowSeat 元件參數 (WindowSeat) 會接收 Window Seat 核取方塊的值。
• 元件名稱會使用 nameof 運算子作為字典索引鍵，其會以常數字串的形式傳回元件名稱。
• 動態轉譯的元件是共用元件：
  • 本文章節所示：RocketLabWithWindowSeat (RocketLabWithWindowSeat.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 值是由父代回呼方法 (ShowDTMessage) 的 EventCallbackFactory.Create 所建立。 請注意，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 的註冊商標。 gin Galactic 是 Galactic Enterprises, LLC 的註冊商標。

其他資源

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