Dialog-API – MRTK3

Dialoge sind kurzlebige Benutzeroberflächenansichten, die Kontextinformationen zu Apps 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 benachrichtigen oder eine Bestätigung der Anforderung zu erhalten, bevor eine Aktion abgeschlossen werden kann.

MRTK3 UXCore stellt die IDialog API zusammen mit der grundlegenden Dialog Implementierung und einem 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. Eine Dokumentation zu den Prefabs, die im UX-Komponentenpaket enthalten sind, finden Sie hier in der Dokumentation zum Dialog-Prefab.

Verwendung

Platzieren Sie einen an einer DialogPool Beliebigen Stelle in Ihrer Szene oder Ui-Hierarchie. Auf Wunsch 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 Dialogfeldansichts-Prefab, auf das verwiesen wird, in Ihrem Build enthalten ist.

DialogPool legt den Prefab-Verweis automatisch auf die Standardmäßigen 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 erhalten haben, können Sie eine Fluent-Generator-API 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 erneuten Abrufen angezeigt. Das obige Codebeispiel führt z. B. zu einem Dialog mit Kopf- und Textkörper, aber nur einer einzigen positiven Auswahlschaltfläche. Zusätzliche Schaltflächen können durch Verkettung 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 werden. Wenn Sie auf ein Ereignis im Dialog lauschen 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 die typische Unity-idiomatische Verwendung in Nicht-Methodenasync . Wenn Sie Geschäftslogik in einem async Kontext schreiben, können Sie die IDialog.ShowAsync() -Methode verwenden, um await das Ergebnis des Dialogs mit einer ausdrucksstärkeren Syntax zu 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 denselben Argtyp wie OnDismissedzurück, ein DialogDismissedEventArgs.

Beispielszene und Prefabs

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