動態轉譯的 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 = ...;
}

如需傳遞參數值的詳細資訊，請參閱本文稍後的傳遞參數一節。

使用 Instance 屬性來存取動態建立的元件執行個體：

<DynamicComponent Type="typeof({COMPONENT})" @ref="dc" />

<button @onclick="Refresh">Refresh</button>

@code {
    private DynamicComponent? dc;

    private Task Refresh()
    {
        return (dc?.Instance as IRefreshable)?.Refresh();
    }
}

在前述範例中:

• {COMPONENT} 預留位置是動態建立的元件類型。
• IRefreshable 是開發人員為動態元件執行個體提供的範例介面。

範例

在下列範例中，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)
  • 本文稍早的 範例一節中顯示的元件：
    • 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 值是由父代回呼方法 (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 的新參數都是重大變更，因為它們會開始遮蔽碰巧有相同名稱的子系元件參數。 呼叫端不可能一律知道固定一組的參數名稱，以傳遞至所有可能的動態子系。

商標

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