API de boîte de dialogue — MRTK3

Les boîtes de dialogue sont des vues d’interface utilisateur de courte durée qui fournissent des informations contextuelles sur l’application. Ils demandent souvent une action à l’utilisateur, puis retournent le résultat à la logique métier de l’application dans une tâche ou un résultat asynchrone. Utilisez des boîtes de dialogue pour informer les utilisateurs d’informations importantes ou demander une confirmation avant qu’une action puisse être effectuée.

MRTK3 UXCore fournit l’API IDialog , ainsi que l’implémentation de base Dialog et un DialogPool pour la génération et la gestion des instances. Cette documentation décrit l’API Fluent pilotée par le code pour afficher les dialogues de votre logique métier. Pour obtenir de la documentation sur les préfabriqués inclus dans le package UX Components, consultez la documentation sur le préfabriqué de boîte de dialogue ici.

Utilisation

Placez un DialogPool quelque part dans votre hiérarchie de scène ou d’interface utilisateur. Si vous le souhaitez, vous pouvez gérer votre propre référence globale DialogPool avec un singleton, un responsable ou un autre modèle. MRTK lui-même n’exerce pas d’opinion sur la façon dont vous gérez une référence globale DialogPool , mais le composant doit se trouver dans votre scène quelque part afin que le préfabriqué de l’affichage de boîte de dialogue référencé soit inclus dans votre build.

DialogPool définit automatiquement sa référence de préfabriqué sur les composants CanvasDialog.prefab d’expérience utilisateur standard si le package est installé. Pour plus d’informations sur la norme CanvasDialog.prefabUX Components , consultez la documentation ici.

Une fois que vous avez obtenu votre DialogPool référence, vous pouvez utiliser une API de générateur de style fluent pour configurer et afficher votre boîte de dialogue.

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()

Seuls les sous-contrôles spécifiés dans vos appels à l’API du générateur sont visibles dans la boîte de dialogue de réutilisation. Par exemple, l’exemple de code ci-dessus génère une boîte de dialogue avec à la fois le texte d’en-tête et le corps du texte, mais un seul bouton de choix positif. Des boutons supplémentaires peuvent être spécifiés en chaînant d’autres appels de méthode.

// 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()

Le args qui est transmis via les rappels de bouton est DialogButtonEventArgs, qui inclut à la IDialog fois une référence au qui a généré l’événement et le DialogButtonType du bouton que l’utilisateur a choisi.

Il est possible qu’une boîte de dialogue soit ignorée en externe avant que l’utilisateur puisse prendre une décision. Cela peut être dû à l’ouverture d’un autre dialogue ou au fait que le dialogue est ignoré manuellement dans le code. Dans ce cas, le rappel fourni à SetPositive() ne serait jamais appelé. Si vous souhaitez écouter un événement dans la boîte de dialogue, y compris un licenciement externe, vous pouvez écouter le OnDismissed rappel.

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

OnDismissed transmet un DialogDismissedEventArgs, qui contient un DialogButtonEventArgs si l’utilisateur a fait un choix, ou null si la boîte de dialogue a été ignorée pour une autre raison.

La méthode standard IDialog.Show() convient à une utilisation unity-idiomatique classique dans les méthodes non-async . Si vous écrivez une logique métier dans un async contexte, vous pouvez utiliser la IDialog.ShowAsync() méthode pour await sur le résultat du dialogue avec une syntaxe plus expressive.

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 retourne le même type arg que OnDismissed, un DialogDismissedEventArgs.

Exemple de scène et de préfabriqués

Pour plus d’informations sur les préfabriqués inclus et les exemples de scènes, consultez la documentation composants d’expérience utilisateur ici.