Dialoogvenster-API — MRTK3

Dialoogvensters zijn korte ui-weergaven die contextuele app-informatie bieden. 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 paaien en beheren van exemplaren. In deze documentatie wordt de codegestuurde Fluent-API beschreven voor het weergeven van dialoogvensters vanuit uw bedrijfslogica. Zie de prefabdocumentatie voor dialoogvensters hier voor documentatie over de prefabs die zijn opgenomen in het pakket UX-onderdelen.

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 ergens in uw scène staan, zodat de prefab van de dialoogvensterweergave waarnaar wordt verwezen, is 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 naar de opbouwfunctie-API zijn zichtbaar in het dialoogvenster voor opnieuw gebruiken. Het bovenstaande codevoorbeeld resulteert bijvoorbeeld in een dialoogvenster met zowel koptekst als hoofdtekst, maar slechts één positieve keuzeknop. Extra 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 DialogButtonType van de 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 callback die is opgegeven aan SetPositive() 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 bepalen 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 argumenttype als OnDismissed, een DialogDismissedEventArgs.

Voorbeeld van scène en prefabs

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