Sobre caixas de diálogo de componente e cascata
APLICA-SE A: SDK v4
As caixas de diálogo vêm em alguns tipos diferentes. Este artigo descreve as caixas de diálogo componente, cascata e prompt. Para obter informações sobre diálogos em geral, consulte o artigo da biblioteca de diálogos . Para obter informações sobre diálogos adaptáveis, consulte a introdução às caixas de diálogo adaptáveis.
Uma caixa de diálogo em cascata (ou cascata) define uma sequência de etapas, permitindo que o bot guie um usuário por meio de um processo linear. Essas caixas de diálogo foram projetadas para funcionar dentro do contexto de uma caixa de diálogo de componente.
Uma caixa de diálogo de componente é um tipo de caixa de diálogo de contêiner que permite que as caixas de diálogo no conjunto chamem outras caixas de diálogo no conjunto, como caixas de diálogo de chamada de caixa de diálogo em cascata ou outra caixa de diálogo em cascata. As caixas de diálogo do componente gerenciam um conjunto de caixas de diálogo filho , como caixas de diálogo de cascata, prompts e assim por diante. Você pode criar uma caixa de diálogo de componente para lidar com tarefas específicas e reutilizá-la, no mesmo bot ou em vários bots.
As caixas de diálogo prompt (prompts) são caixas de diálogo projetadas para solicitar ao usuário tipos específicos de informações, como um número, uma data ou um nome e assim por diante. Os prompts foram projetados para funcionar com caixas de diálogo em cascata em uma caixa de diálogo de componente.
Diálogos de componente
Às vezes, você deseja gravar um diálogo reutilizável para usar em diferentes cenários, como um diálogo de endereço que pede ao usuário para fornecer valores para rua, cidade e CEP.
O diálogo de componente oferece uma estratégia para a criação de diálogos independentes para lidar com cenários específicos, como dividir um conjunto de diálogos grandes em partes mais gerenciáveis. Cada uma dessas partes tem seu próprio conjunto de diálogos e evita qualquer conflito de nome com o conjunto de diálogos que as contém. Para obter mais informações, consulte a caixa de diálogo de componente como fazer isso.
Diálogos em cascata
Um diálogo em cascata é uma implementação específica de um diálogo, geralmente usado para coletar informações do usuário ou orientá-lo em uma série de tarefas. Cada etapa da conversa é implementada como uma função assíncrona que usa um parâmetro de contexto da etapa de cascata (step). Em cada etapa, o bot solicita entrada ao usuário (ou pode iniciar uma caixa de diálogo filho, mas que geralmente é um prompt), aguarda uma resposta e passa o resultado para a próxima etapa. O resultado da primeira função é passado como um argumento para a função seguinte, e assim por diante.
O diagrama a seguir mostra uma sequência de etapas de cascata e as operações de pilha que ocorrem. Os detalhes sobre o uso da pilha de diálogos estão abaixo na seção usando diálogos.
Nas etapas em cascata, o contexto do diálogo em cascata é armazenado em seu contexto de etapas em cascata. O contexto da etapa é semelhante ao contexto da caixa de diálogo e fornece acesso ao contexto e ao estado da curva atual. Use o objeto de contexto da etapa de cascata para interagir com um conjunto de caixas de diálogo de dentro da etapa de cascata.
Você pode manipular um valor retornado de um diálogo a partir de uma etapa em cascata em um diálogo ou a partir do manipulador de turnos do bot, embora você normalmente só precise verificar o status do resultado do turno do diálogo com a lógica de turnos do bot. Dentro de uma etapa de cascata, o diálogo fornece o valor retornado na propriedade result do contexto da etapa de cascata.
Propriedades de contexto da etapa em cascata
O contexto da etapa de cascata contém as seguintes propriedades:
- Opções: contém informações de entrada para o diálogo.
- Valores: contém informações que você pode adicionar ao contexto e são repassados para as etapas seguintes.
- Resultado: contém o resultado da etapa anterior.
Além disso, o próximo método (NextAsync em C#, próximo em JavaScript e Python) continua para a próxima etapa da caixa de diálogo cascata na mesma curva, permitindo que seu bot ignore uma determinada etapa, se necessário.
Solicitações
Prompts, na biblioteca de diálogos, fornecem uma maneira fácil de pedir ao usuário informações e avaliar sua resposta. Por exemplo, para um prompt numérico, você especifica a pergunta ou as informações que está solicitando e o prompt verifica automaticamente se ele recebeu uma resposta numérica válida. Se isso aconteceu, a conversa pode continuar; se não o fez, ele repromptará o usuário para obter uma resposta válida.
Nos bastidores, os prompts são uma caixa de diálogo em duas etapas. Primeiro, o prompt solicitará a entrada, em seguida, ele retornará o valor válido ou iniciará tudo novamente com um novo prompt.
Os prompts têm opções de prompt fornecidas quando são chamados, nas quais você pode especificar o texto do prompt, o prompt de repetição se a validação falhar e as opções para responder o prompt. Em geral, as propriedades de prompt e prompt de repetição são atividades, embora haja alguma variação sobre como isso é tratado em diferentes linguagens de programação.
Além disso, você pode optar por adicionar alguma validação personalizada ao seu prompt quando ele é criado. Por exemplo, digamos que quiséssemos obter o tamanho de um grupo usando o prompt de número, mas o tamanho desse grupo deve ser maior do que 2 e menor que 12. O prompt primeiro verifica se ele recebeu um número válido e, em seguida, executa a validação personalizada se for fornecido. Se a validação personalizada falhar, ele será reprompado do usuário conforme acima.
Quando um prompt for concluído, ele retorna explicitamente o valor resultante que foi solicitado. Quando esse valor é retornado, podemos ter certeza de que ele passou a validação de prompt interno e qualquer validação personalizada adicional que possa ter sido fornecida.
Para obter exemplos sobre como usar vários prompts, dê uma olhada em como usar a biblioteca de diálogos para coletar a entrada do usuário.
Tipos de prompt
Nos bastidores, os prompts são uma caixa de diálogo em duas etapas. Primeiro, o prompt solicita entrada; segundo, ele retorna o valor válido ou reinicia da parte superior com um reprompt. A biblioteca de diálogos oferece vários prompts básicos, cada um usado para coletar um tipo diferente de resposta. Os prompts básicos podem interpretar a entrada de linguagem natural, como "dez" ou "uma dúzia" para um número, ou "amanhã" ou "sextas-feira às 10h" para uma data e hora.
| Prompt | Descrição | Retornos |
|---|---|---|
| Prompt de anexo | Solicita um ou mais anexos, como um documento ou uma imagem. | Uma coleção de objetos attachment. |
| Prompt de escolha | Solicita a escolha dentre um conjunto de opções. | Um objeto found choice. |
| Prompt de confirmação | Solicita uma confirmação. | Um valor booliano. |
| Prompt de data e hora | Solicita uma data e hora. | Uma coleção de objetos date-time resolution. |
| Prompt de número | Solicita um número. | Um valor numérico. |
| Texto do prompt | Solicita a entrada de texto geral. | Uma cadeia de caracteres. |
Para solicitar uma entrada ao usuário, defina um prompt usando uma das classes internas, como text prompt, e adicione-o ao seu conjunto de diálogos. Os prompts têm IDs fixas que devem ser exclusivas dentro de um conjunto de caixas de diálogo. Você pode ter um validador personalizado para cada prompt, e para alguns prompts, você pode especificar uma localidade padrão.
Localidade do prompt
A localidade é usada para determinar o comportamento específico do idioma dos prompts choice, confirm, date-time e number. Para qualquer entrada fornecida pelo usuário, se o canal forneceu uma propriedade de localidade na mensagem do usuário, então essa é a usada. Caso contrário, se a localidade padrão do prompt for definida, fornecendo-a ao chamar o construtor do prompt ou configurando-a mais tarde, então essa é a usada. Se nenhuma dessas localidades for fornecida, o inglês ("en-us") será usado como localidade.
A localidade é um código ISO 639 de dois, três ou quatro caracteres que representa uma família de idiomas ou idiomas.
Opções de prompt
O segundo parâmetro do método de prompt do contexto da etapa usa um objeto opções de prompt, que tem as propriedades a seguir.
| Propriedade | Descrição |
|---|---|
| Prompt | A atividade inicial para enviar o usuário, para solicitar sua entrada. |
| Prompt de nova tentativa | A atividade para enviar o usuário se a primeira entrada não foi validada. |
| Opções | Uma lista de opções para o usuário escolher, para ser usado com um prompt de escolha. |
| Validações | Parâmetros adicionais a serem usados com um validador personalizado. |
| Estilo | Define como as opções de um prompt de escolha ou prompt de confirmação serão apresentadas a um usuário. |
Você sempre deve especificar a atividade de prompt inicial a ser enviada ao usuário e um prompt de repetição para instâncias em que a entrada do usuário não é validada.
Se a entrada do usuário não for válida, o prompt de repetição será enviado ao usuário; se não houver nenhuma repetição especificada, o prompt inicial será usado. No entanto, se uma atividade for enviada de volta ao usuário de dentro do validador, nenhum aviso de nova tentativa será enviado.
Validação da prompt
Você pode validar uma resposta do prompt antes de retornar o valor para a próxima etapa da cascata. Uma função de validador tem um parâmetro de contexto do validador de prompt e retorna um valor booleano que indica se a entrada passa na validação. O contexto do validador de prompt inclui as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
| Contexto | O contexto de turnos atual para o bot. |
| Reconhecido | Um resultado do reconhecedor de prompts que contém informações sobre a entrada do usuário, conforme processado pelo reconhecedor. |
| Opções | Contém as opções de prompt que foram fornecidas na chamada para iniciar o prompt. |
O resultado do reconhecedor de prompts tem as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
| Êxito | Indica se o reconhecedor foi capaz de analisar a entrada. |
| Valor | O valor retornado do reconhecedor. Se necessário, o código de validação pode modificar esse valor. |
Usar os diálogos
Diálogos podem ser considerados como uma pilha programática, que chamamos de pilha de diálogos, com o manipulador de turnos sendo o responsável pelo direcionamento e servindo como o fallback se a pilha estiver vazia. O item mais importante nessa pilha é considerado a caixa de diálogo ativa e o contexto da caixa de diálogo direciona toda a entrada para a caixa de diálogo ativa.
Quando uma caixa de diálogo começa, ela é enviada por push para a pilha e agora é a caixa de diálogo ativa. Ela permanece a caixa de diálogo ativa até terminar, é removida pelo método de caixa de diálogo de substituição ou outra caixa de diálogo é enviada por push para a pilha (pelo manipulador de turnos ou pela própria caixa de diálogo ativa) e se torna a caixa de diálogo ativa. Quando essa nova caixa de diálogo termina, ela é exibida da pilha e a próxima caixa de diálogo para baixo torna-se a caixa de diálogo ativa novamente. Isso permite repetir um diálogo ou ramificar uma conversa, o que será discutido abaixo.
Você pode iniciar ou continuar uma caixa de diálogo raiz usando o método de extensão de caixa de diálogo de execução . No código do bot, chamar o método de extensão de execução da caixa de diálogo continua a caixa de diálogo existente ou inicia uma nova instância da caixa de diálogo se a pilha estiver vazia no momento. O controle e a entrada do usuário vão para a caixa de diálogo ativa na pilha.
O método de execução requer um acessador de propriedade de estado para acessar o estado da caixa de diálogo. O acessador é criado e usado da mesma maneira que outros acessadores de estado, mas é criado como sua própria propriedade baseada no estado da conversa. Detalhes sobre como gerenciar o estado podem ser encontrados no tópico de gerenciamento de estado, e o uso do estado do diálogo é mostrado nas instruções sobre o fluxo sequencial da conversa.
De dentro de uma caixa de diálogo, você tem acesso ao contexto da caixa de diálogo e pode usá-lo para iniciar outras caixas de diálogo, encerrar a caixa de diálogo atual e executar outras operações.
Para iniciar uma caixa de diálogo
De dentro de uma caixa de diálogo em cascata, passe a ID da caixa de diálogo que você deseja iniciar no contexto da caixa de diálogo de cascata usando o método de diálogo iniciar, solicitar ou substituir a caixa de diálogo .
- Os métodos de diálogo prompt e begin enviarão uma nova instância da caixa de diálogo referenciada para a parte superior da pilha.
- O método replace dialog destacará o diálogo atual na fila e enviará o diálogo de substituição por push para a fila. O diálogo de substituição é cancelado, e todas as informações contidas nessa instância são descartadas.
Use o parâmetro options para passar informações para a nova instância do diálogo. As opções passadas para o novo diálogo podem ser acessadas por meio da propriedade options do contexto da etapa em qualquer etapa do diálogo. Para obter mais informações, consulte como criar fluxo de conversa avançado usando branches e loops.
Para continuar um diálogo
Em uma caixa de diálogo em cascata, use a propriedade de valores do contexto de etapa para persistir o estado entre as curvas. Qualquer valor adicionado a essa coleção em um turno anterior estará disponível nos turnos seguintes. Para obter mais informações, consulte como criar fluxo de conversa avançado usando branches e loops.
Para encerrar uma caixa de diálogo
Em uma caixa de diálogo em cascata, use o método de caixa de diálogo final para encerrar uma caixa de diálogo, tirando-a da pilha. O método de caixa de diálogo final pode retornar um resultado opcional para o contexto pai (como a caixa de diálogo que o chamou ou o manipulador de turnos do bot). Isso geralmente é chamado de dentro do diálogo para encerrar a instância atual de si mesmo.
Você pode chamar o método end dialog de qualquer lugar onde se tenha um contexto de diálogo, mas ele será exibido ao bot que foi chamado no diálogo ativo atual.
Dica
É prática recomendada chamar explicitamente o método de caixa de diálogo final no final da caixa de diálogo.
Para limpar todos os diálogos
Caso você queira remover todas as caixas de diálogo da pilha, é possível limpar a pilha de caixas chamando o método cancel all dialogs do contexto da caixa de diálogo.
Repetindo um diálogo
Você pode substituir um diálogo por ele mesmo, criando um loop, usando o método replace dialog. Essa é uma ótima maneira de lidar com interações complexas e uma técnica para gerenciar menus.
Observação
Se você precisar persistir o estado interno da caixa de diálogo atual, precisará passar informações para a nova instância da caixa de diálogo na chamada para o método de caixa de diálogo de substituição e, em seguida, inicializar a caixa de diálogo adequadamente.
Ramificar uma conversa
O contexto do diálogo mantém uma pilha de diálogos e, para cada diálogo na pilha, controla qual é a etapa a seguir. O método begin dialog cria um diálogo filho e o envia para o topo da pilha e o método end dialog retira o primeiro diálogo da pilha. End dialog geralmente é chamado de dentro do diálogo que está terminando.
Um diálogo pode iniciar um novo diálogo no mesmo conjunto de diálogo chamando o método begin dialog do contexto do diálogo e fornecendo o ID do novo diálogo, o que transformará o novo diálogo em diálogo ativo. O diálogo original ainda está na pilha, mas as chamadas para o método continue dialog do contexto do diálogo só são enviadas para o diálogo que está no topo da pilha, o diálogo ativo. Quando um diálogo é retirado da pilha, o contexto do diálogo é retomado com a próxima etapa da cascata na pilha em que ele parou em relação ao diálogo original.
Assim, você pode criar uma ramificação dentro do fluxo da sua conversa incluindo uma etapa em um diálogo que possa escolher condicionalmente um diálogo para iniciar a partir de um conjunto de diálogos disponíveis.
Informações adicionais
- Confira mais informações sobre caixas de diálogo adaptáveis em Introdução às caixas de diálogo adaptáveis.
- Confira mais informações em Sobre os skills.