ダイアログ API — MRTK3

ダイアログは、コンテキスト アプリ情報を提供する有効期間の短い UI ビューです。 多くの場合、ユーザーに何らかのアクションを要求し、非同期タスクまたは結果でアプリのビジネス ロジックに結果を返します。 ダイアログを使用して、ユーザーに重要な情報を通知するか、アクションを完了する前に確認を要求します。

MRTK3 UXCore は、API と、インスタンスを生成および管理するための基本的なDialog実装と DialogPool を提供IDialogします。 このドキュメントでは、ビジネス ロジックからのダイアログを表示するためのコード駆動型 fluent API について説明します。 UX コンポーネント パッケージに含まれるプレハブのドキュメントについては、 こちらのダイアログ プレハブのドキュメントを参照してください。

使用法

DialogPoolシーンまたは UI 階層のどこかに を配置します。 必要に応じて、シングルトン、マネージャー、またはその他のパターンを使用して独自のグローバル DialogPool 参照を管理できます。 MRTK 自体はグローバル DialogPool 参照を維持する方法について意見を示しませんが、参照されるダイアログ ビュー プレハブがビルドに含まれるように、コンポーネントがシーン内のどこかにある必要があります。

DialogPool は、パッケージがインストールされている場合、そのプレハブ参照を標準の UX コンポーネント CanvasDialog.prefab に自動的に設定します。 UX コンポーネント標準 CanvasDialog.prefabの詳細については、 こちらのドキュメントを参照してください。

参照を DialogPool 取得したら、fluent スタイルのビルダー API を使用して、ダイアログを構成して表示できます。

dialogPool.Get()
    .SetHeader("This is the Dialog's header.")
    .SetBody("You can specify the dialog's body text here.")
    .SetPositive("The positive button's label.", (args) => { /* Do thing! */ })
    .Show()

ビルダー API の呼び出しで指定されたサブコントロールのみが、再利用可能なダイアログに表示されます。 たとえば、上記のコード サンプルでは、ヘッダー テキストと本文テキストの両方を含むダイアログが生成されますが、正の選択肢のボタンは 1 つだけです。 追加のボタンは、さらにメソッド呼び出しをチェーンすることで指定できます。

// This dialog will show all three buttons.
dialogPool.Get()
    .SetHeader("A header.")
    .SetBody("Foobarbaz!")
    .SetPositive("The positive button's label.", (args) => { /* Do thing! */ })
    .SetNegative("The negative button's label.", (args) => { /* Do another thing! */ })
    .SetNeutral("A neutral option, too!", (args) => { /* Do some neutral thing. */ })
    .Show()

argsボタン コールバックを介して渡される は になりますDialogButtonEventArgs。これには、イベントを生成した へのIDialog参照と、ユーザーが選択したボタンの へのDialogButtonType参照の両方が含まれます。

ユーザーが決定を下す前に、ダイアログが外部で無視される可能性があります。 これは、別のダイアログが開かれているか、ダイアログがコードで手動で閉じられた場合に発生する可能性があります。 この場合、 に SetPositive() 指定されたコールバックは呼び出されません。 外部の無視を含むダイアログのイベントをリッスンする場合は、コールバックを OnDismissed リッスンできます。

var dialog = dialogPool.Get()?SetBody("Foobar!");
dialog.OnDismissed += (args) => { /* do things! */ };
dialog.Show();

OnDismissedは をDialogDismissedEventArgs渡します。ユーザーが選択を行った場合、またはnull他の理由でダイアログが閉じられた場合は が含まれますDialogButtonEventArgs。

標準 IDialog.Show() メソッドは、非async メソッドでの一般的な Unity の慣用的な使用に適しています。 コンテキストでビジネス ロジックを async 記述する場合は、 メソッドを IDialog.ShowAsync() 使用して await 、より表現力の高い構文を使用してダイアログの結果に対して を実行できます。

async void SomeAsyncBusinessLogic()
{
    var result = await dialogPool.Get()
                    .SetBody("The await will resolve when the user selects the option.")
                    .SetNeutral("A button!")
                    .ShowAsync();

    Debug.Log("Async dialog says: " + result.Choice?.ButtonText);
}

ShowAsync は、 と同じ arg 型 OnDismissedを DialogDismissedEventArgs返します。

シーンとプレハブの例

含まれているプレハブとサンプル シーンの詳細については、 こちらの UX コンポーネントのドキュメントを参照してください。