API de caixa de diálogo — MRTK3

As caixas de diálogo são exibições de interface do usuário de curta duração que fornecem informações contextuais do aplicativo. Muitas vezes, eles solicitam alguma ação do usuário e retornam o resultado de volta à lógica de negócios do aplicativo em uma tarefa ou resultado assíncrono. Use caixas de diálogo para notificar os usuários sobre informações importantes ou solicitar confirmação antes que uma ação possa ser concluída.

O UXCore do MRTK3 fornece a IDialog API, juntamente com a implementação básica Dialog e uma DialogPool para gerar e gerenciar instâncias. Esta documentação descreve a API fluente controlada por código para mostrar caixas de diálogo da lógica de negócios. Para obter a documentação sobre os pré-fabricados incluídos no pacote componentes de UX, consulte a documentação de pré-fabricado caixa de diálogo aqui.

Uso

Coloque um DialogPool em algum lugar em sua cena ou hierarquia de interface do usuário. Se desejado, você pode gerenciar sua própria referência global DialogPool com um singleton, gerente ou outro padrão. O próprio MRTK não exerce uma opinião sobre como você mantém uma referência global DialogPool , mas o componente deve estar em sua cena em algum lugar para que o pré-fabricado de exibição de caixa de diálogo referenciado seja incluído em seu build.

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

Depois de obter sua DialogPool referência, você poderá usar uma API de construtor de estilo fluente para configurar e mostrar 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()

Somente os subcontroles especificados em suas chamadas para a API do construtor ficarão visíveis na caixa de diálogo de reutilização. Por exemplo, o exemplo de código acima resultará em uma caixa de diálogo com texto de cabeçalho e texto do corpo, mas apenas um único botão de opção positiva. Botões adicionais podem ser especificados encadeando 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()

O args que é passado pelos retornos de chamada do botão será DialogButtonEventArgs, que incluirá uma referência ao IDialog que gerou o evento e o DialogButtonType do botão escolhido pelo usuário.

É possível que uma caixa de diálogo seja descartada externamente antes que o usuário possa tomar uma decisão. Isso pode ser causado por outra caixa de diálogo que está sendo aberta ou pela caixa de diálogo ser descartada manualmente no código. Nesse caso, o retorno de chamada fornecido a SetPositive() nunca seria invocado. Se você quiser ouvir qualquer evento na caixa de diálogo, incluindo uma demissão externa, poderá ouvir o OnDismissed retorno de chamada.

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

OnDismissed passará um DialogDismissedEventArgs, que conterá um DialogButtonEventArgs se o usuário tiver feito uma escolha ou null se a caixa de diálogo tiver sido descartada por algum outro motivo.

O método padrão IDialog.Show() é adequado para uso típico do Unity idioma em métodos não-async . Se você estiver escrevendo lógica de negócios em um async contexto, poderá usar 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 retornará o mesmo tipo de arg que OnDismissed, um DialogDismissedEventArgs.

Exemplo de cena e pré-fabricados

Para obter informações sobre os pré-fabricados incluídos e as cenas de exemplo, consulte a documentação componentes da experiência do usuário aqui.