ASP.NET Core 中的元件標記協助程式

元件標記協助程式會在 Razor 頁面或 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 所示。 針對 string 類型值的 Razor 剖析行為不會套用至 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 元件