Dialog-API – MRTK3

Dialoge sind kurzlebige Benutzeroberflächenansichten, die kontextbezogene App-Informationen bereitstellen. Sie fordern häufig eine Aktion vom Benutzer an und geben das Ergebnis dann in einer asynchronen Aufgabe oder einem asynchronen Ergebnis an die Geschäftslogik der App zurück. Verwenden Sie Dialogfelder, um Benutzer über wichtige Informationen zu informieren oder eine Bestätigung anzufordern, bevor eine Aktion abgeschlossen werden kann.

MRTK3 UXCore stellt die IDialog API zusammen mit der grundlegenden Dialog Implementierung und einer DialogPool zum Erstellen und Verwalten von Instanzen bereit. In dieser Dokumentation wird die codegesteuerte Fluent-API zum Anzeigen von Dialogen aus Ihrer Geschäftslogik beschrieben. Die Dokumentation zu den Prefabs, die im UX-Komponentenpaket enthalten sind, finden Sie hier in der Dokumentation zum Dialog-Prefab.

Verwendung

Platzieren Sie an einer DialogPool beliebigen Stelle in Ihrer Szene oder Ui-Hierarchie. Bei Bedarf können Sie Ihren eigenen globalen DialogPool Verweis mit einem Singleton, manager oder einem anderen Muster verwalten. MRTK selbst gibt keine Meinung darüber ab, wie Sie einen globalen DialogPool Verweis verwalten, aber die Komponente muss sich irgendwo in Ihrer Szene befinden, damit das referenzierte Dialogfeldansichts-Prefab in Ihrem Build enthalten ist.

DialogPool legt den Prefab-Verweis automatisch auf die Standard-UX-Komponenten CanvasDialog.prefab fest, wenn das Paket installiert ist. Weitere Informationen zum UX-Komponentenstandard CanvasDialog.prefabfinden Sie in der Dokumentation hier.

Nachdem Sie Ihre DialogPool Referenz abgerufen haben, können Sie eine Generator-API im Fluent-Stil verwenden, um Ihren Dialog zu konfigurieren und anzuzeigen.

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

Nur die Untersteuerelemente, die in Ihren Aufrufen der Generator-API angegeben sind, werden im Dialogfeld zum Erneutverwenden angezeigt. Das obige Codebeispiel führt z. B. zu einem Dialog mit Kopfzeilen- und Textkörpertext, aber nur einer einzelnen Positivauswahlschaltfläche. Zusätzliche Schaltflächen können durch Verketten weiterer Methodenaufrufe angegeben werden.

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

Der args , der über die Schaltflächenrückrufe übergeben wird, ist DialogButtonEventArgs, was sowohl einen Verweis auf die IDialog enthält, die das Ereignis generiert hat, als auch die DialogButtonType der Schaltfläche, die der Benutzer ausgewählt hat.

Es ist möglich, dass ein Dialogfeld extern geschlossen wird, bevor der Benutzer eine Entscheidung treffen kann. Dies kann entweder dadurch verursacht werden, dass ein anderes Dialogfeld geöffnet wird, oder dass das Dialogfeld manuell im Code geschlossen wird. In diesem Fall würde der für bereitgestellte SetPositive() Rückruf nie aufgerufen. Wenn Sie ein Ereignis im Dialogfeld abhören möchten, einschließlich einer externen Kündigung, können Sie den Rückruf abhören OnDismissed .

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

OnDismissed übergibt eine DialogDismissedEventArgs, die eine DialogButtonEventArgs enthält, wenn der Benutzer eine Auswahl getroffen hat oder null wenn das Dialogfeld aus einem anderen Grund geschlossen wurde.

Die Standardmethode IDialog.Show() eignet sich für den typischen Unity-idiomatischen Einsatz in Nicht-Methodenasync . Wenn Sie Geschäftslogik in einem async Kontext schreiben, können Sie die IDialog.ShowAsync() -Methode verwenden, um das Ergebnis des Dialogs mit einer ausdrucksstärkeren Syntax zu await verwenden.

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 gibt den gleichen Arg-Typ wie OnDismissedzurück, ein DialogDismissedEventArgs.

Beispielszene und Prefabs

Informationen zu den enthaltenen Prefabs und Beispielszenen finden Sie hier in der Dokumentation zu UX-Komponenten.