ノードプレハブの使用¶

プレハブ (あらかじめ作成されたテンプレート) を使用して、アプリケーションを構造化し、一貫性のあるインターフェイスを作成します。プレハブを利用してアプリケーションの構成要素を作成し、アプリケーションのメンテナンスを容易にすることができます。

アプリケーションに何度も現れるそれぞれのアイテム用にプレハブを作成すると、アプリケーションの一部分を論理的に分離したり、アプリケーションがすでに実行中のときにコンテンツをノードツリーに追加したりできます。例えば、プレハブを使用して：

一貫した構造を持つコンテンツを作成します。例えば、プレハブを使用すると、常に同じ構造を持ちながら、外観を変えることができるボタンを作成できます。
プロジェクトをモジュール化し、メンテナンスを容易にしましょう。
Kanzi アプリケーションのロード時間と起動時間を制御します。
Kanzi アプリケーションのために異なるテーマを作成します。
Kanzi アプリケーションをローカライズします。

プレハブを使用する際は、次の点に注意してください。

ノードツリー内の他のノードと同様に、プレハブのインスタンスを複製することができます。
プレハブのインスタンスに追加したプロパティ値は、プレハブで設定されたプロパティ値を上書きします。
プレハブ内のアイテムを参照したい場合は、相対パスを使用します（例えば、メッセージトリガーやプロパティバインディングで）。プレハブ自体をメッセージやアニメーションのターゲットパスとして使用しないでください。

プレハブの中にプレハブをネストすることができます。

ノードプレハブとノードプレハブインスタンス¶

ノードプレハブは、ロードしたときにのみデバイス上のメモリを消費します。ノードプレハブをロードすると、そのプレハブは含まれるノードとプロパティの数に基づいてメモリを消費します。ノードプレハブをインスタンス化すると、Kanzi がノードを作成し、それらのノードにプロパティを割り当てます。プレハブインスタンスが消費するメモリ量は、インスタンスの数に単一のプレハブインスタンスのメモリ要件を掛けることで計算できます。

ノードをノードツリーにアタッチすると、ノードによって使用されるリソースがリソースマネージャーから検索され、要求されます。リソースマネージャーは、リソースがすでにロードされている場合、それらをロードするか、既存のリソースを返します。

ノードプレハブインスタンスをデタッチする際、Kanzi はデタッチしたノードで使用されているリソースを解放しません。これはパフォーマンスの最適化であり、プレハブの親ノードを変更したり、ノードツリー内でプレハブを移動したりする際に、プレハブが使用するリソースを再度ロードする必要がないようにします。使用されなくなったすべてのリソースを解放したい場合は、ResourceManager::purge を呼び出してください。

Kanzi は、ノードツリーに配置するすべてのノードが使用されることを前提としています。Kanzi は、ノードツリーに配置されたすべてのコンテンツが即座に使用可能であるケースを最適化します。使用されないノードがある場合は、それをノードツリーから削除してください。

Prefab Placeholder ノードと Prefab View ノード¶

プロジェクト内でノードプレハブをインスタンス化するために、Prefab Placeholder ノードと Prefab View ノードの両方を使用できます。これらのノードの違いは次のとおりです。

Prefab Placeholder ノードを持つノードプレハブをインスタンス化すると、Kanzi は Prefab Template プロパティの値を一度読み取り、そのプロパティが指すプレハブで Prefab Placeholder ノードを置き換えます。

例えば、Prefab Placeholder 2D ノードを使用してノードプレハブをインスタンス化し、その中に Button 2D ノードが含まれている場合、Kanzi がノードプレハブをインスタンス化すると、Prefab Placeholder 2D ノードが Button 2D プレハブのルートノードに置き換えられます。
Prefab View ノードを持つノードプレハブをインスタンス化すると、Kanzi は Prefab Template プロパティの値を監視し、そのプロパティが指すプレハブを Prefab View ノードの子ノードとして追加します。これにより、Prefab View がインスタンス化するプレハブを変更し、リソースをロードしているときにアプリケーションの応答性を保つことができます。ノードプレハブリソースを非同期でロードするを参照してください。

例えば、Prefab View 2D ノードを使用してノードプレハブをインスタンス化し、その中に Button 2D ノードが含まれている場合、Kanzi がプレハブをインスタンス化すると、Button 2D ノードのルートノードを Prefab View 2D ノードの子ノードとして追加します。

Prefab Placeholder ノードを使用する場合と Prefab View ノードを使用する場合¶

アプリケーションの実行中に変更不要なノードプレハブをインスタンス化するには、Prefab Placeholder ノードを使用します。

プレハブを動的に変更したい場合や、プレハブが使用するリソースを非同期でロードしたい場合は、プレハブをインスタンス化するために Prefab View を使用してください。例えば、アプリケーションにテーマを適用し、異なるテーマに対して異なるプレハブを使用したい場合は、それらのプレハブをインスタンス化するために Prefab View ノードを使用してください。

Kanzi は Prefab Placeholder の Prefab Template プロパティの値を一度読み取りますが、Prefab View ノードは Prefab Template プロパティの値の変化を監視します。Prefab View の Prefab Template プロパティの値が変化すると、Kanzi はその子ノードを新しい子ノードに置き換えます。

ノードプレハブの作成と使用¶

ノードプレハブを作成して使用するには：

Prefabs でをクリックし、作成したいプレハブを選択します。

例えば、Button 2D プレハブを作成し、そこに Image と Text Block 2D ノードを追加します。
アプリケーションでプレハブをインスタンス化するには:
- Prefabs から作成したプレハブを Node Tree にドラッグし、そのプレハブを使用したいノードにドロップします。
  
  Kanzi Studio は、プロジェクト内でプレハブをインスタンス化する Prefab Placeholder ノードを作成します。
  
  異なるプレハブをインスタンス化するには、Node Tree で変更したいプレハブを選択し、Properties で Prefab Template プロパティをインスタンス化したいプレハブに設定します。
- Node Tree Alt を押しながら右クリックで、プレハブをインスタンス化したいノードを選択し、Prefab View を選択して、Properties で Prefab Template プロパティをインスタンス化したいプレハブに設定します。

ノードプレハブのインスタンスをカスタマイズする¶

ノードプレハブは、それぞれが独自のプロパティを持つノードのツリーを含むことができます。プロジェクト内でプレハブまたはそのインスタンスのいずれかのノードを編集すると、そのプレハブのすべてのインスタンスでそれらのノードが変更されます。プレハブのプロパティ値をオーバーライドすることで、プレハブの各インスタンスに独自のプロパティ値を持たせることができます。例えば、住所録エントリのプレハブを作成する際には、各住所録エントリに異なる名前、番号、写真を表示したいと考えます。

ノードプレハブのインスタンスをカスタマイズするには:

Prefabs で、プレハブのインスタンスでカスタマイズしたいプレハブ内のノードを選択します。

例えば、プレハブの各インスタンスに異なるテクスチャを使用するには、Image ノードを選択します。
Properties で、カスタマイズしたいプロパティの隣にあるをクリックします。

Kanzi Studio は、そのプロパティからカスタムプロパティを作成し、それをそのプレハブのルートノードに追加し、そのプレハブのルートノード内のプロパティに ##Template バインディングを作成します。

プレハブルートのバインディングを参照してください。

例えば、そのプレハブの異なるインスタンスで表示したいテクスチャをカスタマイズするには、Image プロパティの横にあるをクリックします。Kanzi Studio はカスタム Image プロパティを作成し、それをそのノードプレハブのルートノードに追加し、Image ノードにそのノードプレハブのルートノード内のカスタム Image プロパティへの ##Template バインディングを作成します。
Node Tree で、カスタマイズしたいプレハブインスタンスのルートノードを選択します。
Properties で、カスタマイズしたプロパティの隣にあるをクリックし、プロパティの値を設定します。

このプレハブのインスタンスのみが、設定した値を使用します。

ノードプレハブの編集¶

ノードプレハブを編集するには、Prefabs でプレハブをダブルクリックします。Kanzi Studio は、Preview ウィンドウタブにプレハブのみを表示します。これで、Preview ツールを使用してプレハブを編集し、プレハブをインスタンス化せずに編集結果を確認できます。

ノードをプレハブに変換する¶

プロジェクトのノードツリーの任意の部分をプレハブに変換するには、Node Tree からプレハブに変換したい部分のルートを Prefabs にドラッグします。

ノードを Prefabs ウィンドウにドロップすると、Kanzi Studio はそのノードからプレハブテンプレートを作成し、元のノードをプレハブのインスタンスに置き換えます。

../../_images/creating-a-prefab---prefab-in-the-prefabs.png

ノードプレハブリソースを非同期でロードする¶

プレハブリソースを非同期でロードすると、Kanzi は別のスレッドを使用してリソースをロードします。リソースのロードが完了すると、Kanzi はメインスレッドを使用してリソースをデプロイします。これにより、アプリケーションはリソースのロード中も応答性を維持します。複数のプレハブからリソースを非同期でロードする方法については、チュートリアル: リソースを非同期でロードおよびデプロイするを参照してください。

リソースプロファイリングを使用して、Kanzi アプリケーションでリソースとプレハブをロードおよびデプロイするのにかかる時間をランタイム中に測定します。

リソースプロファイリングデータは、どのリソースを非同期でロードするかを見つけるのに役立ちます。

リソースの読み込みとデプロイ時間の測定を参照してください。

ノードプレハブリソースを非同期でロードするには:

ノードプレハブのリソースを Kanzi がロードしている間に表示したいコンテンツを作成します。

例えば、非同期でリソースをロードするプレハブのコンテンツに置き換えるローディング画面を作成するには、Asset Packages > Factory Content から Processing Indicator をドラッグし、Prefabs ウィンドウにドロップします。
非同期でロードしたいリソースを持つノードプレハブを作成します。

例えば、Prefabs で Stack Layout 2D を作成し、異なる画像を指す複数の Image ノードを追加します。
Node Tree で、プレハブのリソースを非同期でロードしたい場所に Prefab View ノードを作成します。Properties で、前のステップで作成したプレハブのリソースを Kanzi がロードしている間に表示したいコンテンツを Prefab Template プロパティに設定します。

例えば、Prefab Template プロパティを Processing Indicator プレハブに設定します。
Node Tree で、Prefab View ノードを選択します。Node Components で、Alt を押しながら右クリック Triggers を行い、プレハブのリソースのロードを開始するために使用したいトリガーを選択します。

例えば、Kanzi が Prefab View ノードをスクリーングラフにアタッチしたときにリソースのロードを開始するために、On Attached トリガーを追加します。
Node Components で、前のステップで追加したトリガーで Alt を押しながら右クリックを行い、Dispatch Message Action > Prefab View > Start Asynchronous Load を選択します。
Start Asynchronous Load アクションで、Prefab Template プロパティを、リソースを非同期でロードしたいプレハブ、またはそのプレハブを指すリソース ID に設定します。
Kanzi がリソースの読み込みを完了したときに何が起こるかを定義するには：
1. Node Tree で、Prefab View ノードを選択します。Node Components で、Alt を押しながら右クリック Triggers を行い、Message Trigger > Prefab View > Asynchronous Load Completed を選択します。
2. Node Components > Triggers で、Asynchronous Load Completed トリガーで Alt を押しながら右クリックを行い、アクションを選択します。
  
  例えば、Dispatch Message Action > Activity Host > Activate Activity アクションを選択し、以下を設定します。
  - Target Item を、アクティブにしたいアクティビティを含む Activity Host ノードに設定
  - Activity Activation Path を、Kanzi がリソースのロードを完了したときにアクティブにしたいアクティビティに設定
File > Export > Export as KZB Player for Windows を選択し、<ProjectName>/Tool_project/Application Player ディレクトリ内のアプリケーションの exe ファイルを開きます。

Kanzi Studio の Preview は起動時にプロジェクト内のすべてのリソースをロードするため、リソースの非同期ロードの効果を確認するには、次のいずれかを行います。
- プロジェクトを kzb プレイヤーとしてエクスポートする
- プロジェクトの kzb ファイルをエクスポートし、プロジェクトの Visual Studio ソリューションからアプリケーションを実行する

ノードプレハブのルートノードを置き換える¶

プレハブのルートノードを置き換えるのは、プレハブの親ノードとして使用されるノードを追加または変更したい場合です。例えば、最初に Grid Layout 3D をルートとして持つプレハブを作成したが、今はその Grid Layout 3D を Stack Layout 3D に配置したい場合、そのプレハブのルートノードを置き換える必要があります。

ノードプレハブのルートを置き換えるには:

Prefabs Alt を押しながら右クリックで置き換えたいプレハブのルートを選択し、Empty Node From Items を選択します。

Kanzi Studio は現在のプレハブのルートを Empty Node ノードに置き換え、そのエンプティノード内にプレハブ全体を配置します。3D プレハブの場合、Kanzi Studio は Empty Node 3D ノードを作成し、2D プレハブの場合は Empty Node 2D ノードを作成します。
Prefabs で、プレハブの新しいルートノードとして使用したいノードを作成します。

例えば、Stack Layout 3D を作成します。
古いプレハブを Empty Node ノードのルートから、前のステップで作成した新しいルートノードにドラッグアンドドロップします。

APIで Prefab View 3D ノードを使用する¶

Prefab view 3D ノードを使用するには、3Dコンテンツを含むプレハブを作成し、setPrefab() を使用して設定します。

// Create a Prefab view 3D and add it to the scene.
PrefabView3DSharedPtr prefabView3D = PrefabView3D::create(domain, "Prefab view");
scene->addChild(prefabView3D);

// Acquire prefab from resource manager.
PrefabTemplateSharedPtr prefabTemplate = resourceManager->acquireResource<PrefabTemplate>("kzb://my_project/Prefabs/My3DPrefab");

// Use the prefab in the PrefabView3D node.
prefabView3D->setPrefab(prefabTemplate);

詳細については、PrefabView3D クラスを参照してください。

APIで Prefab View 2D ノードを使用する¶

Prefab View 2D ノードを使用するには、2Dコンテンツを持つプレハブを作成し、setPrefab() を使用して設定します。

// Create a Prefab view 2D and add it to the viewport.
PrefabView2DSharedPtr prefabView2D = PrefabView2D::create(domain, "Prefab view");
viewportNode->addChild(prefabView2D);

// Acquire prefab from resource manager.
PrefabTemplateSharedPtr prefabTemplate = resourceManager->acquireResource<PrefabTemplate>("kzb://my_project/Prefabs/My2DPrefab");

// Use the prefab in the PrefabView2D node.
prefabView2D->setPrefab(prefabTemplate);

詳細については、PrefabView2D クラスを参照してください。

Prefab View プロパティタイプ¶

Prefab View ノードで利用可能なプロパティタイプのリストについては、Prefab View 2D および Prefab View 3D を参照してください。

Prefab Placeholder プロパティタイプとメッセージ¶

Prefab Placeholder ノードの利用可能なプロパティタイプとメッセージのリストについては、Prefab Placeholder 2D および Prefab Placeholder 3D を参照してください。