Dialog-API – MRTK3

Dialogrutor är kortlivade gränssnittsvyer som ger sammanhangsberoende appinformation. De begär ofta en åtgärd från användaren och returnerar sedan resultatet tillbaka till appens affärslogik i en asynkron uppgift eller ett resultat. Använd dialogrutor för att meddela användarna om viktig information eller begära bekräftelse innan en åtgärd kan slutföras.

MRTK3 UXCore tillhandahåller API:et IDialog , tillsammans med den grundläggande Dialog implementeringen och en DialogPool för att skapa och hantera instanser. Den här dokumentationen beskriver det koddrivna fluent-API:et för att visa dialogrutor från din affärslogik. Dokumentation om de prefab som ingår i UX-komponentpaketet finns i dokumentationen om dialogprefab här.

Användning

Placera en DialogPool plats i din scen- eller användargränssnittshierarki. Om du vill kan du hantera din egen globala DialogPool referens med en singleton, chef eller något annat mönster. MRTK självt utövar inte en åsikt om hur du underhåller en global DialogPool referens, men komponenten måste finnas i din scen någonstans så att den refererade dialogvyprefab ingår i din version.

DialogPool anger automatiskt prefab-referensen till standard-UX-komponenterna CanvasDialog.prefab om paketet är installerat. Mer information om UX-komponenternas standard CanvasDialog.prefabfinns i dokumentationen här.

När du har fått din DialogPool referens kan du använda ett API för flytande builder för att konfigurera och visa dialogrutan.

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

Endast de underkontroller som anges i dina anrop till builder-API:et visas i dialogrutan för återanvändning. Kodexemplet ovan resulterar till exempel i en dialogruta med både rubriktext och brödtext, men bara en enda knapp för positivt val. Ytterligare knappar kan anges genom att länka ytterligare metodanrop.

// 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 som skickas via knappåteranropen blir DialogButtonEventArgs, som innehåller både en referens till händelsen IDialog som genererade händelsen och DialogButtonType knappen som användaren valde.

Det är möjligt att en dialogruta kan stängas externt innan användaren kan fatta ett beslut. Detta kan bero antingen på att en annan dialogruta öppnas eller på att dialogrutan stängs manuellt i kod. I det här fallet anropas aldrig återanropet som tillhandahålls till SetPositive() . Om du vill lyssna på en händelse i dialogrutan, inklusive en extern uppsägning, kan du lyssna på återanropet OnDismissed .

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

OnDismissed skickar en DialogDismissedEventArgs, som innehåller en DialogButtonEventArgs om användaren har gjort ett val, eller null om dialogrutan har stängts av någon annan anledning.

IDialog.Show() Standardmetoden är lämplig för typisk Unity-idiomatisk användning i icke-metoderasync. Om du skriver affärslogik i en async kontext kan du använda IDialog.ShowAsync() metoden för att await visa resultatet av dialogrutan med en mer uttrycksfull syntax.

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 returnerar samma arg-typ som OnDismissed, en DialogDismissedEventArgs.

Exempelscen och prefabs

Information om inkluderade prefabs och exempelscener finns i dokumentationen för UX-komponenter här.