DIALOG API : MRTK3

Los diálogos son vistas de interfaz de usuario de corta duración que proporcionan información contextual de la aplicación. A menudo solicitan alguna acción al usuario y, a continuación, devuelven el resultado a la lógica de negocios de la aplicación en una tarea asincrónica o un resultado. Use cuadros de diálogo para notificar a los usuarios información importante o solicitar confirmación antes de que se pueda completar una acción.

MRTK3 UXCore proporciona la IDialog API, junto con la implementación básica Dialog y un DialogPool para generar y administrar instancias. En esta documentación se describe la API fluida basada en código para mostrar diálogos desde la lógica de negocios. Para obtener documentación sobre los objetos prefabricados incluidos en el paquete componentes de la experiencia de usuario, consulte la documentación prefabricada del cuadro de diálogo aquí.

Uso

Coloque un DialogPool elemento en algún lugar de la escena o jerarquía de la interfaz de usuario. Si lo desea, puede administrar su propia referencia global DialogPool con un singleton, un administrador u otro patrón. MRTK en sí no ejerce una opinión sobre cómo mantener una referencia global DialogPool , pero el componente debe estar en la escena en algún lugar para que el objeto prefabricado de la vista de cuadro de diálogo al que se hace referencia se incluya en la compilación.

DialogPool establecerá automáticamente su referencia prefabricada a los componentes CanvasDialog.prefab estándar de la experiencia de usuario si el paquete está instalado. Para obtener más información sobre el estándar CanvasDialog.prefabUX Components , consulte la documentación aquí.

Una vez que haya obtenido la DialogPool referencia, puede usar una API de generador de estilo fluido para configurar y mostrar el cuadro de diálogo.

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 los subcontrolos especificados en las llamadas a la API del generador estarán visibles en el cuadro de diálogo de reutilización. Por ejemplo, el ejemplo de código anterior dará como resultado un cuadro de diálogo con texto de encabezado y texto del cuerpo, pero solo un solo botón de opción positiva. Se pueden especificar botones adicionales encadenando otras llamadas a métodos.

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

Los args que se pasan a través de las devoluciones de llamada del botón serán DialogButtonEventArgs, que incluyen una referencia al IDialog que generó el evento y el DialogButtonType del botón que eligió el usuario.

Es posible que un cuadro de diálogo se descarte externamente antes de que el usuario pueda tomar una decisión. Esto puede deberse a que se abre otro cuadro de diálogo o que el cuadro de diálogo se descarta manualmente en el código. En este caso, la devolución de llamada proporcionada a SetPositive() nunca se invocaría. Si desea escuchar cualquier evento en el cuadro de diálogo, incluido un despido externo, puede escuchar la devolución de OnDismissed llamada.

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

OnDismissed pasará un DialogDismissedEventArgsobjeto , que contendrá si DialogButtonEventArgs el usuario ha tomado una decisión o null si el cuadro de diálogo se ha descartado por algún otro motivo.

El método estándar IDialog.Show() es adecuado para el uso típico de Unity idiomático en métodos que noasync son. Si escribe lógica de negocios en un async contexto, puede usar el IDialog.ShowAsync() método para await en el resultado del cuadro de diálogo con una sintaxis más expresiva.

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 devolverá el mismo tipo de arg que OnDismissed, un DialogDismissedEventArgs.

Escena de ejemplo y objetos prefabricados

Para obtener información sobre los prefabricados incluidos y las escenas de ejemplo, consulte la documentación de componentes de la experiencia de usuario aquí.