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>

前の param-Color の例のように、引用符で囲まれた文字列を渡すには、明示的な Razor 式が必要です。 object 型である param-* 属性には、Razor の string 型の値の解析動作は該当しません。

次の場合を除き、すべての種類のパラメーターがサポートされています。

• ジェネリック パラメーター。
• シリアル化できないパラメーター。
• コレクション パラメーターの継承。
• 型が Blazor WebAssembly アプリの外部で定義されているか、遅延読み込みされたアセンブリ内にあるパラメーター。
• 子要素コンテンツの RenderFragment デリゲートを受信する場合 (たとえば、param-ChildContent="...")。 このシナリオでは、渡される子コンテンツを使用してレンダリングするコンポーネントを参照する Razor コンポーネント (.razor) を作成し、コンポーネント タグ ヘルパーのあるページまたはビューから Razor コンポーネントを呼び出すことをおすすめします。

パラメーターは、JSON のシリアル化可能な型である必要があります。これは通常、その型に既定のコンストラクターと設定できるプロパティがある必要があることを意味します。 たとえば、前の例の Size と Color には、Size と Color の型が JSON シリアライザーでサポートされているプリミティブ型 (int と string) であるため、値を指定することができます。

次の例では、クラス オブジェクトがコンポーネントに渡されます。

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 コンポーネント