Dialoogvenster-API — MRTK3

Dialoogvensters zijn korte ui-weergaven met contextuele app-informatie. Ze vragen vaak om een actie van de gebruiker en retourneren vervolgens het resultaat terug naar de bedrijfslogica van de app in een asynchrone taak of resultaat. Gebruik dialoogvensters om gebruikers op de hoogte te stellen van belangrijke informatie of om bevestiging te vragen voordat een actie kan worden voltooid.

MRTK3 UXCore biedt de IDialog API, samen met de basisimplementatie Dialog en een DialogPool voor het uitzetten en beheren van exemplaren. In deze documentatie wordt de codegestuurde Fluent-API beschreven voor het weergeven van dialoogvensters uit uw bedrijfslogica. Zie de prefabdocumentatie voor dialoogvensters voor documentatie over de prefabs die zijn opgenomen in het UX Components-pakket.

Gebruik

Plaats een DialogPool ergens in uw scène- of UI-hiërarchie. Indien gewenst kunt u uw eigen globale DialogPool referentie beheren met een singleton, manager of een ander patroon. MRTK zelf geeft geen mening over hoe u een globale DialogPool verwijzing onderhoudt, maar het onderdeel moet zich ergens in uw scène bevindt, zodat de prefab van de dialoogvensterweergave waarnaar wordt verwezen, wordt opgenomen in uw build.

DialogPool stelt de prefabverwijzing automatisch in op de standaard UX-onderdelen CanvasDialog.prefab als het pakket is geïnstalleerd. Zie de documentatie hier voor meer informatie over de UX Components-standaardCanvasDialog.prefab.

Zodra u uw DialogPool referentie hebt verkregen, kunt u een opbouw-API in fluent-stijl gebruiken om uw dialoogvenster te configureren en weer te geven.

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

Alleen de subbesturingselementen die zijn opgegeven in uw aanroepen voor de opbouwfunctie-API, zijn zichtbaar in het dialoogvenster opnieuw gebruiken. Het bovenstaande codevoorbeeld resulteert bijvoorbeeld in een dialoogvenster met zowel koptekst als hoofdtekst, maar slechts één knop met positieve keuze. Aanvullende knoppen kunnen worden opgegeven door verdere methode-aanroepen te koppelen.

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

De args die worden doorgegeven via de callbacks van de knop zijn DialogButtonEventArgs, die zowel een verwijzing bevatten naar de IDialog die de gebeurtenis heeft gegenereerd als de van de DialogButtonType knop die de gebruiker heeft gekozen.

Het is mogelijk dat een dialoogvenster extern wordt gesloten voordat de gebruiker een beslissing kan nemen. Dit kan worden veroorzaakt doordat een ander dialoogvenster wordt geopend of doordat het dialoogvenster handmatig in code wordt gesloten. In dit geval wordt de opgegeven SetPositive() callback nooit aangeroepen. Als u wilt luisteren naar een gebeurtenis in het dialoogvenster, inclusief een extern ontslag, kunt u luisteren naar de OnDismissed callback.

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

OnDismissed geeft een DialogDismissedEventArgsdoor, die een DialogButtonEventArgs bevat als de gebruiker een keuze heeft gemaakt of null als het dialoogvenster om een andere reden is gesloten.

De standaardmethode IDialog.Show() is geschikt voor typisch Unity-idiomatisch gebruik in niet-methodenasync . Als u bedrijfslogica in een async context schrijft, kunt u de IDialog.ShowAsync() methode gebruiken om await het resultaat van het dialoogvenster te bekijken met een meer expressieve syntaxis.

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 retourneert hetzelfde argtype als OnDismissed, een DialogDismissedEventArgs.

Voorbeeldscène en prefabs

Zie de documentatie voor UX-onderdelen hier voor informatie over de opgenomen prefabs en voorbeeldscènes.