API di dialogo - MRTK3

Le finestre di dialogo sono viste dell'interfaccia utente di breve durata che forniscono informazioni sull'app contestuali. Spesso richiedono un'azione dall'utente e quindi restituiscono il risultato alla logica di business dell'app in un'attività o un risultato asincroni. Usare le finestre di dialogo per informare gli utenti di informazioni importanti o di conferma della richiesta prima che sia possibile completare un'azione.

MRTK3 UXCore fornisce l'API, insieme all'implementazione IDialog di base Dialog e a una DialogPool per generare e gestire le istanze. Questa documentazione descrive l'API fluente basata sul codice per visualizzare Dialoghi dalla logica di business. Per la documentazione sui prefab inclusi nel pacchetto componenti dell'esperienza utente, vedere la documentazione del prefab dialog qui.

Utilizzo

Posizionare un DialogPool elemento nella scena o nella gerarchia dell'interfaccia utente. Se si desidera, è possibile gestire il proprio riferimento globale DialogPool con un singleton, un gestore o un altro modello. MRTK non esercita un'opinione su come mantenere un riferimento globale DialogPool , ma il componente deve trovarsi nella scena in modo che il prefab della visualizzazione della finestra di dialogo a cui si fa riferimento sia incluso nella compilazione.

DialogPool imposta automaticamente il riferimento prefab ai componenti CanvasDialog.prefab UX standard se il pacchetto è installato. Per altre informazioni sullo standard CanvasDialog.prefabUX Components , vedere la documentazione qui.

Dopo aver ottenuto il DialogPool riferimento, è possibile usare un'API di generatore fluent-style per configurare e visualizzare la finestra di dialogo.

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

Solo i sotto-controlli specificati nelle chiamate all'API generatore saranno visibili nella finestra di dialogo di riutilizzo. Ad esempio, l'esempio di codice precedente genera un dialogo con testo di intestazione e testo del corpo, ma solo un singolo pulsante di scelta positiva. È possibile specificare pulsanti aggiuntivi concatenando ulteriori chiamate di metodo.

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

L'oggetto args passato attraverso i callback del pulsante sarà DialogButtonEventArgs, che include sia un riferimento all'evento IDialog che ha generato l'evento sia il DialogButtonType pulsante scelto dall'utente.

È possibile che un dialogo possa essere ignorato esternamente prima che l'utente possa prendere una decisione. Questa operazione può essere causata da un'altra finestra di dialogo aperta o dalla finestra di dialogo che viene ignorata manualmente nel codice. In questo caso, il callback fornito per SetPositive() non verrà mai richiamato. Se si vuole ascoltare qualsiasi evento nella finestra di dialogo, inclusa una chiusura esterna, è possibile ascoltare il OnDismissed callback.

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

OnDismissed passerà un DialogDismissedEventArgsoggetto , che conterrà se DialogButtonEventArgs l'utente ha fatto una scelta o null se la finestra di dialogo è stata ignorata per un altro motivo.

Il metodo standard IDialog.Show() è adatto per l'uso tipico di Unity-idiomatico nei metodi nonasync . Se si scrive la logica di business in un async contesto, è possibile usare il IDialog.ShowAsync() metodo per await il risultato della finestra di dialogo con una sintassi più espressiva.

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 restituirà lo stesso tipo arg di OnDismissed, un DialogDismissedEventArgsoggetto .

Scena di esempio e prefab

Per informazioni sui prefab e sulle scene di esempio incluse, vedere la documentazione relativa ai componenti dell'esperienza utente qui.