API de Caixa de Diálogo – MRTK3

As caixas de diálogo são vistas de IU de curta duração que fornecem informações contextuais da aplicação. Muitas vezes, pedem alguma ação ao utilizador e, em seguida, devolvem o resultado à lógica de negócio da aplicação numa tarefa ou resultado assíncrono. Utilize caixas de diálogo para notificar os utilizadores de informações importantes ou pedir confirmação antes de uma ação poder ser concluída.

O MRTK3 UXCore fornece a IDialog API, juntamente com a implementação básica Dialog e uma DialogPool para desova e gestão de instâncias. Esta documentação descreve a API fluente condicionada por código para mostrar Caixas de diálogo da sua lógica de negócio. Para obter documentação sobre os pré-fabricados incluídos no pacote Componentes UX, consulte a documentação pré-fabricada da caixa de diálogo aqui.

Utilização

Coloque um DialogPool algures na sua cena ou hierarquia de IU. Se desejar, pode gerir a sua própria referência global DialogPool com um singleton, gestor ou outro padrão. O MRTK em si não exerce uma opinião sobre a forma como mantém uma referência global DialogPool , mas o componente tem de estar na sua cena algures para que a vista de diálogo referenciada seja incluída na sua compilação.

DialogPool definirá automaticamente a referência pré-fabricada para os Componentes CanvasDialog.prefab UX padrão se o pacote estiver instalado. Para obter mais informações sobre a norma CanvasDialog.prefabComponentes UX, veja a documentação aqui.

Depois de obter a referência DialogPool , pode utilizar uma API de construtor de estilo fluente para configurar e mostrar a sua caixa 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()

Apenas os subcontrolos especificados nas chamadas para a API do construtor estarão visíveis na caixa de diálogo de reutilização. Por exemplo, o exemplo de código acima resultará numa Caixa de diálogo com texto de cabeçalho e corpo de texto, mas apenas um único botão de escolha positiva. Podem ser especificados botões adicionais ao encadear outras chamadas 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()

Os args que são transmitidos através das chamadas de retorno do botão serão DialogButtonEventArgs, que incluem uma referência ao IDialog que gerou o evento e ao DialogButtonType botão que o utilizador escolheu.

É possível que uma caixa de diálogo possa ser dispensada externamente antes de o utilizador poder tomar uma decisão. Isto pode ser causado por outra caixa de diálogo ser aberta ou pela caixa de diálogo ser manualmente dispensada no código. Neste caso, a chamada de retorno fornecida para SetPositive() nunca seria invocada. Se quiser ouvir qualquer evento na caixa de diálogo, incluindo um despedimento externo, pode ouvir a OnDismissed chamada de retorno.

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

OnDismissed irá transmitir um DialogDismissedEventArgs, que conterá um DialogButtonEventArgs se o utilizador tiver feito uma escolha ou null se a caixa de diálogo tiver sido dispensada por outro motivo.

O método padrão IDialog.Show() é adequado para uma utilização típica do Unity-idiomatic em métodos nãoasync - Se estiver a escrever lógica de negócio num async contexto, pode utilizar o IDialog.ShowAsync() método para await no resultado da caixa de diálogo com uma sintaxe mais expressiva.

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á o mesmo tipo de arg que OnDismissed, a DialogDismissedEventArgs.

Cenário de exemplo e prefabs

Para obter informações sobre os pré-fabricados incluídos e os cenários de exemplo, veja a documentação dos Componentes UX aqui.