MRTK3 - DataBindingについて(Early Preview)

Mixed Reality Toolkit3の新機能「DataBinding」

コンテンツに利用するデータとそれを適用するデータをキーで紐づけることでバインドし動的にコンテンツ変更を実現する。別記事のThemingもData Bindingの派生機能として提供されている。

Public Preview版のMRTK3の中でもEarly Previewの機能なので今後破壊的変更/廃止等が起きる可能性はあります。

必要なパッケージ

• com.microsoft.mrtk.data 1.0.0-pre.12

この機能を有効化するためには、[Project Settings]-[Player]-[Other Settings]-[Script Compilation]に以下のシンボル追加が必要です。

• MRTK_UX_DATABINDING_THEMING_ENABLED

Data Binding概要

WPF等いくつかのフレームワークでも採用されているデータバインディングの概念をMRTK3の部品として実現したものがData Bindingになります。以下のようなデータソースとオブジェクトをキーで紐づけることで動的にコンテンツを操作することが可能になります。

引用元: Microsoft,データ バインディングとフレームワークのテーマ — MRTK3, https://learn.microsoft.com/ja-jp/windows/mixed-reality/mrtk-unity/mrtk3-data/packages/data/overview, 2022/11/29

Data Sourceに関連するもの

動的に使用するデータをデータソースとして管理するための部品は以下のものが提供されています。

種類	説明
DataSourceBase	スクリプトで利用できるデータソースの基底クラス
DataSourceDictionary	スクリプトで利用できる辞書形式のデータソース
DataSourceJson	スクリプトで利用できるJson形式のデータソースの基底クラス
DataSourceGOBase	コンポーネントとして利用できるデータソースの基底クラス
DataSourceGODictionary	コンポーネントとして利用できる辞書形式のデータソース
DataSourceGOJson	コンポーネントとして利用できるJson形式のデータソースの基底クラス
DataSourceObjects	JSONやXMLで表現できるような構造化データを管理するデータソース
DataSourceReflection	リフレクションを使用してオブジェクトの構造を決定するデータソース
DataSourceThemeProvider	テーマの提供を簡素化するヘルパークラス
DataSourceDynamicList	ランダムに生成される大きなリストを生成するシンプルなデータソースです。テストなどで利用可能

Data Consumerに関連するもの

Data ConsumerはData Sourceの情報を実際のコンテンツに反映する際に利用する部品群です。例えば、データソース内のテキスト情報をコンテンツ内のTextコンポーネントに反映したい場合などはDataConsumerTextを利用します。DataConsumerTextは内部でコンテンツ内のTextコンポーネントのリストを保持しており、DataSourceの情報とText内に記述されているキー情報を照合して情報の置換えを行います。

種類	説明
DataConsumerAudioClip	配下のAudioClipをDataSourceのバインド先として管理するコンポーネント
DataConsumerBooleanEvents	バインドされた変数の更新に基づくUnityEventの呼び出しを可能にする。データソースのBoolean値でイベントを発生させたり、状態変更を検出。
DataConsumerCollection	配列要素の情報を管理するコンポーネント
DataConsumerCommandDispatcher	このコンシューマにバインドされたデータソースに連動したコマンドをディスパッチする。配列などの複数要素を持つデータソースに対して編集や削除といったアクションを組み入れたい場合に使用する。
DataConsumerGOBase	コンポーネントとして利用できるData Consumersの基底クラス
DataConsumerImageQuadFromUrl	URLの情報から画像をダウンロードしQuadに表示するためのコンポーネント
DataConsumerImageSpriteFromUrl	URLの情報から画像をダウンロードしSpriteに表示するためのコンポーネント
DataConsumerImageTextureFromUrl	URLの情報から画像をダウンロードしTextureに表示するためのコンポーネント
DataConsumerMaterial	配下のMaterialをDataSourceのバインド先として管理するコンポーネント
DataConsumerSprite	配下のSpriteをDataSourceのバインド先として管理するコンポーネント
DataConsumerSpriteLookup	配下のSpriteをDataSourceのバインドキーでフィルターして管理するコンポーネント
DataConsumerText	配下のText（TextMeshPro, UnityEngine.UI.Text）をDataSourceのバインド先として管理するコンポーネント
DataConsumerTextStyle	配下のText（TextMeshPro, UnityEngine.UI.Text）のスタイルをDataSourceのバインド先として管理するコンポーネント
DataConsumerThemeHelper	Themingで利用するスタイル適用などを支援するためのヘルパー

Data Bindingを便利に使うためのHelper

種類	説明
CollectionItemIdentifier	コレクションの中の一つの項目の値として機能するクラス
DataCollectionEventsGOBase	GameObjectの仮想基底クラスで、以下のようなサブクラスを作成することが可能です。Unity エディタインスペクタで「ドラッグ＆ドロップ可能」であり、他のゲームオブジェクトのコンポーネントとして追加することができるサブクラスを作成することができます。ゲームオブジェクトのコンポーネントとして追加することができます。
DataCollectionEventsHandler	DataCollectionEventsGOBaseのサブクラスで、すべてのイベントを公開。DataConsumerCollectionを組み合わせると、DataConsumerCollectionで表示している情報の状態によって発生するイベントを利用できます。これを利用するとデータの先頭に来ると「次へ」ボタンを表示したりといったことが可能になります。
DataKeyPathMapperDictionary	スクリプトとして利用できるデータバインディング時に使用するキーの別名を管理するためのクラスです
DataKeyPathMapperGODictionary	コンポーネントとして利用できるデータバインディング時に使用するキーの別名を管理するためのクラスです
DataNodeObject	IDataNode インターフェースを実装した汎用 DOM 形式のデータノード
DataObjectPool	オブジェクトの再利用に使用できるオブジェクトのデータプール。
DataParser	Data Consumer内のキー値を抽出するためのクラス
DataSourceProviderSingleton	Singltonのクラスを作成するためのヘルパークラス
ThemeSelector	Themingで使用。複数のテーマ設定を管理し切り替える機能を提供する
TruncateString	文字列の切り捨てのためのユーティリティ

サンプル１ - DataSourceGODictionaryを使った文字の置き換え

Unityプロジェクトを作成しMRTK3を導入する

基本的な手順は以下の記事を参考に設定してください。

https://zenn.dev/miyaura/articles/32dbaf7256fef4

https://zenn.dev/miyaura/articles/be65665439f0d4

Data Bingingに必要なパッケージを導入する

必要なパッケージは以下のものになりますので、Mixed Reality Feature Toolでインポートしてください。

https://learn.microsoft.com/ja-jp/windows/mixed-reality/develop/unity/welcome-to-mr-feature-tool

• com.microsoft.mrtk.data 1.0.0-pre.12

この機能を有効化するためには、[Project Settings]-[Player]-[Other Settings]-[Script Compilation]に以下のシンボル追加が必要です。

• MRTK_UX_DATABINDING_THEMING_ENABLED

Data Sourceを準備する

まず、辞書形式のデータを保持できる[DataSourceGODictionary]を準備します。
[Hierarchy]で空オブジェクトを作成し、[Inspector]で[DataSourceGODictionary]を追加します。

[DataSourceGODictionary]に以下の設定を行います。

• Data Source Type : data
• Key Path Values
  • key : UserName, value : TestUser
  • key : Message, value : Hello

Data Sourceを反映するテキストを準備する

次に実際にDataSourceの情報を使ってテキストを変更してみたいと思います。先ほど作ったGameObjectの配下に[Text - TextMesh Pro]を追加します。TextMesh ProのScaleを(0.01,0.01,0.01)に変更し、テキストを「{{ Message }}, {{ UserName }}」と入力します。
{{ [Key Path] }}でData Source内のキーを検索し、その値で置き換える動作になります。

Data Consumer を追加します。

最後にData Sourceに情報をオブジェクトに反映するために、Data Consumerを追加します。
Data Sourceと同じGameObjectに[Data consumer Text]を追加します。[Data consumer Text]は子要素のオブジェクトを対象にテキストとしてkeypathが定義されているかどうかを自動的に探索するようになっています。

この状態で実行すると[DataSourceGODictionary]の情報が反映されます。

サンプル2 - DataConsumerCollectionを使ったオブジェクトによるリスト表示

DataSourceCollectionをDataSourceとして活用するとあらかじめ作成したPrefabにDataSourceの情報を反映しながら要素数分オブジェクトを生成して表示することができます。リストとして表示するオブジェクトも先ほどのDataConsumerをりようして作成することでカード式のリストなども容易に作成することができます。

Unityプロジェクトを作成しMRTK3を導入する

基本的な手順は以下の記事を参考に設定してください。

Data Bingingに必要なパッケージを導入する

必要なパッケージは以下のものになりますので、Mixed Reality Feature Toolでインポートしてください。

https://learn.microsoft.com/ja-jp/windows/mixed-reality/develop/unity/welcome-to-mr-feature-tool

• com.microsoft.mrtk.data 1.0.0-pre.12

この機能を有効化するためには、[Project Settings]-[Player]-[Other Settings]-[Script Compilation]に以下のシンボル追加が必要です。

• MRTK_UX_DATABINDING_THEMING_ENABLED

Data Sourceを準備する

今回は配列情報を扱うためにJsonデータを利用するDataSourceGOJsonを使ってみたいと思います。このくらいは基底クラスとして機能しており以下の情報があります

• Webリクエストを発行しJsonデータを受信する
• JsonデータをDataSourceとして割り当てる。

Jsonデータをどのように取得するかはデータ次第となるため使いやすい形でカスタマイズできるようになっています。今回はURLがない場合Inspectorで設定したJsonテキストで処理するというものになります。

// Copyright (c) 2022 Takahiro Miyaura
// Released under the MIT license
// http://opensource.org/licenses/mit-license.php
using Microsoft.MixedReality.Toolkit.Data;

public class DatasourceDemoJson : DataSourceGOJson
{
    private readonly string json = "{\"title\": \"Deta Binding\",\"description\": \"Data Binding is amazing!\"}";
    public string URL;

    public void Start()
    {
        if (!string.IsNullOrEmpty(URL))
            StartCoroutine(StartJsonRequest(URL));
        else
            SetJson(json);
    }
}

上記のコンポーネントを作成し[Hierarchy]タブで空のGameObjectに追加します。追加したGameObjectに先ほど作ったDatasourceDemoJsonを追加します。パラメータは以下の通り設定します。

• Data Source Type : data
• URL : Jsonデータを取得するURL

用意したJsonは以下のようなものです。子要素は100個ほど用意しました。
１要素にタイトル、詳細、画像を情報として持っています。これをカード式のレイアウトをもつオブジェクトに張り付けていきます。

{
	"title": "MRTK3 Sample Json Data",
	"description": "MRTK3 sample for Data binding",
	"details": [
		{
			"title": "MRTK3 Sample Image00",
			"description": "This is Sample Info No.00",
			"imageUrl": "https://Hoge.mrtk/images/mrtk00.jpg"
		},
		{
			"title": "MRTK3 Sample Image01",
			"description": "This is Sample Info No.01",
			"imageUrl": "https://Hoge.mrtk/images/mrtk00.jpg"
		},...
	]
}

リストとして表示する子要素をPrefabで作成する。

次にJsonでリストデータを展開する際に表示する子要素となるオブジェクトをPrefabで作成します。今回用意したJsonデータは以下のキーとデータを保持します。これにあったPrefabを用意します。

• title : テキスト形式の文字列
• description : テキスト形式の文字列
• imageUrl : 画像イメージ

それぞれData Consumerを利用して作成します。テキスト系には[Data Consumer Text]、画像は[Data Consumer Image Quad From Url]を使用しました。[Data Consumer Image Quad From Url]はkeypathで指定されたURL形式の値を使ってWebリクエストを行いダウンロードした画像をQuadに描画します。

最初に空のGameObjectを作成し[Data Consumer Text]コンポーネントを追加します。

背景パネルの追加

子要素として背景用のBackplateを追加します。
空のGameObjectを追加し、[Mesh Fileter]、[Mesh Renderer]を追加します。それぞれ以下のパラメータを充てると標準の背景と同じパネルを構築することが可能です。

• MeshFilter.Mesh : rounded_edge
• MeshRenderer.Materials : MRTK_Backplate_10mm_Gradient

タイトルと詳細のテキスト領域の作成

次にJsonデータの[title],[description]を表示するためのテキストを追加します。それぞれTextMeshProで構築します。

• title用の設定
  • position(0,0.17,-0.001)
  • width : 20
  • Height : 5
  • scale : (0.003,0.003,0.003)
  • text : {{ title }}

• description用の設定
  • position(0.0108,-0.008,-0.001)
  • width : 40
  • Height : 15
  • scale : (0.002,0.002,0.002)
  • text : {{ description }}

先ほど親要素にDataConsumerTextを割り当てているのでこの2つのオブジェクトはData Souceによる変更対象となります。

画像の表示エリアの作成

最後に画像の表示エリアを作成します。子要素にQuadを追加します。Quadには画像を割り当てたいので[DataConsumerImageQuadFromUrl]を追加してJsonデータ内のURLから画像をダウンロードするように変更します。

* position(-0.07,0,-0.001)
* scale : (0.04,0.04,0.01)
* DataConsumerImageQuadFromUrl.KeyPath : imageUrl

以上で子要素を表示するオブジェクトの作成が完了です。これをPrefab化しておきましょう。

Data Consumer を追加します。

今回はリスト表示を行うので[Data Consumer Collection]を利用します。
Data Sourceを割り当てたオブジェクトの下に空のオブジェクトを作成し、[Data Consumer Collection]を追加します。

コンポーネントの設定は以下の部分を変更しています。

• Collections Key Path : details（Jsonデータの配列要素を持つキー）
• Item Prefab : Detail(先ほど作った子要素のPrefab)

Collections Key Pathには今回作成したJsonで配列を返す要素を作っているのでその設定になります。このようにJsonをデータソースにした場合はJsonのキーを直接指定する形になります。階層が深い場合はピリオド区切りでつなげていくことが可能です。例えば、{{ details[0].title }}と記載したテキストを用意すると、detailsの0番目の要素のtitleの値が反映されるようになっています。あまりに階層が深く扱いが難しい場合はDataSourceをカスタムして可読性を上げたりといったことも可能だと思います。

{
	"title": "MRTK3 Sample Json Data",
	"description": "MRTK3 sample for Data binding",
	"details": [
		{
			"title": "MRTK3 Sample Image00",
			"description": "This is Sample Info No.00",
			"imageUrl": "https://Hoge.mrtk/images/mrtk00.jpg"
		},
		{
			"title": "MRTK3 Sample Image01",
			"description": "This is Sample Info No.01",
			"imageUrl": "https://Hoge.mrtk/images/mrtk00.jpg"
		},...
	]
}

きれいに配置するための設定

上記の設定だけで実行することは可能ですが、生成されるオブジェクトが無秩序に配置されてしまいます。このような生成されたオブジェクトを整列して配置したい場合は[Data Collection Item Placer Offset]を利用します。先ほど作ったDataConsumerCollectionと同じオブジェクトに追加します。

一度に表示するオブジェクト数、配置の仕方については以下の情報で調整します。

設定項目	説明
Item Ofest	Paddingを含めた1要素のオフセット値（オブジェクトサイズ＋Padding）
X Count	X軸方向の要素数
Y Count	Y軸方向の要素数
Z Count	Z軸方向の要素数

データ送りを実現する

上記までの対応で、配列要素をきれい整列して動的に表示することが可能になります。ただし、表示できる要素数を超えた場合はデータ送りをしてすべての要素をみたくないですか？そういった機能も提供されています。[Data Collection Item Placer Offset]にはデータを送りやページングの機能が提供されています。例えば、コレクションの上部にデータ送り用のボタンを用意し以下のメソッドを呼び出すことで、表示されている情報を切り替えることができます。

設定項目	説明
MoveToPreviousItem	要素を１つ戻す
MoveToNextItem	要素を１つ進める
PageBackward	前ページへ
PageForward	次ページへ

以下のボタンを押すと要素を1つ戻すことができる実装例です。

さらに[Data Collection Item Placer Offset]に[Data Collection Events Handler]を設定することで、表示されているデータの状態に応じて様々なイベントを発生させることができます。

以下は、表示しているデータが先頭、最後尾によって、ページ送りのボタンの表示/非表示を制御する例です。

[Data Collection Events Handler]にはこれ以外にも様々なイベントが利用できます。

設定項目	説明
Attach	データがアタッチされた場合に発生
CollectionAtEnd	データの最後に来た場合に発生
CollectionAtStart	データの最初に来た場合に発生
CollectionCanGoBackward	1要素戻ることができる場合に発生
CollectionCanGoForward	1要素進むことができる場合に発生
CollectionChanged	データコレクションが変更された場合に発生
CollectionContextSwitch
CollectionEmpty	データが空になった場合に発生
CollectionInMiddle	データの中央に来た場合に発生
CollectionNotEmpty	データが空でない場合に発生
CollectionPagedBackward	ページを戻すことができる場合に発生
CollectionPagedForward	ページを進めることができる場合に発生
CollectionScrolledBackward	スクロールを戻すことができる場合に発生
CollectionScrolledForward	スクロールを進めることができる場合に発生
Detach	データがデタッチされた場合に発生
EndPlacement	配置が完了した場合に発生
ItemPlaced	アイテムを配置した場合に発生
StartPlacement	配置を開始した場合に発生

参考リンク

• Github - Mixed Reality Toolkit 3
• MTRK3ドキュメント
• MRTK3 Tutorial : "Zappy's Playground"
• Mixed Reality Dev Days 2022
  • 再生リスト(Youtube)
  • Introducing MRTK3 – Shaping the future of the MR Developer Experience.
    →過去のMRTKの取組みから振返り、MRTK3がどういったコンセプトで今回作られたのか
  • Getting started with your first MRTK3 project
    →MRTK3動かしてみようぜ
  • MRTK3 Interaction building blocks
    →MRTK3の入力系についての設計や構造
  • Building Rich UI for MR in MRTK3
    →MRTK3の素敵なUIをどう構築しているか
  • Working with Dynamic Data and Theming in MRTK3
    →データバインディングとテーマ制御について
  • Deploy Everywhere with OpenXR and MRTK3
    →MRTK3のOpenXR対応で色々デバイスで動く話