API de diálogo: 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 del usuario y, a continuación, devuelven el resultado a la lógica de negocios de la aplicación en una tarea o resultado asincrónicos. Use diálogos 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 controlada por código para mostrar diálogos de la lógica de negocios. Para obtener documentación sobre los objetos prefabricados incluidos en el paquete de componentes de la experiencia de usuario, consulte la documentación del objeto prefabricado dialogo aquí.

Uso

Coloque un elemento DialogPool en alguna parte de la escena o la 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 no ejerce una opinión sobre cómo se mantiene una referencia global DialogPool , pero el componente debe estar en la escena en algún lugar para que la vista de diálogo a la que se hace referencia esté incluida en la compilación.

DialogPool establecerá automáticamente su referencia prefabricada a los componentes CanvasDialog.prefab de experiencia de usuario estándar 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 subcontroles 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 de cuerpo, pero solo un solo botón de opción positiva. Se pueden especificar botones adicionales mediante el encadenamiento de más llamadas de método.

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

El args que se pasa a través de las devoluciones de llamada del botón será DialogButtonEventArgs, que incluye 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 otro cuadro de diálogo se abre o el 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 descarte externo, puede escuchar la OnDismissed devolución de llamada.

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

OnDismissed pasará un DialogDismissedEventArgs, que contendrá si DialogButtonEventArgs el usuario había elegido o null si el cuadro de diálogo se descartó 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 está escribiendo lógica de negocios en un async contexto, puede usar el IDialog.ShowAsync() método para await en el resultado del 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 argumento que OnDismissed, un DialogDismissedEventArgs.

Escena de ejemplo y objetos prefabricados

Para obtener información sobre los objetos prefabricados incluidos y las escenas de ejemplo, consulte la documentación de UX Components aquí.