Usar caixas de diálogo em guias

Adicione caixas de diálogo modais (conhecidas como módulos de tarefa no TeamsJS v1.x) às suas guias para simplificar a experiência do usuário para quaisquer fluxos de trabalho que exijam entrada de dados. As caixas de diálogo permitem coletar a entrada do usuário em uma janela modal do Microsoft Teams-Aware, como editar cartões Planner. Você pode usar caixas de diálogo para criar uma experiência semelhante.

Os dois main operações de caixas de diálogo envolvem abri-las e fechá-las (enviar). As funções são ligeiramente diferentes para versões anteriores (antes de v2.x.x) da biblioteca do TeamsJS:

TeamsJs v2

// Open HTML dialog
microsoftTeams.dialog.url.open(
    urlDialogInfo: UrlDialogInfo, 
       submitHandler?: DialogSubmitHandler, 
       messageFromChildHandler?: PostMessageChannel
): void;

// Open Adaptive Card dialog
microsoftTeams.dialog.adaptiveCard.open(
    adaptiveCardDialogInfo: AdaptiveCardDialogInfo,
    submitHandler?: DialogSubmitHandler
): void;

// Submit HTML dialog (AC dialogs send result from Action.Submit)
   microsoftTeams.dialog.url.submit(
    result?: string | any,
    appIds?: string | string[]
): void;

Observação

A dialog.submit propriedade só pode ser chamada em uma caixa de diálogo.

TeamsJs v1

// Same function is used for both HTML and Adaptive Card dialogs.
microsoftTeams.tasks.startTask(
    taskInfo: TaskInfo,
    submitHandler?: (err: string, result: string | any) => void
): void;

// Only works for HTML dialogs (AC dialogs send result from Action.Submit)
microsoftTeams.tasks.submitTask(
    result?: string | any,
    appIds?: string | string[]
): void;

As seções a seguir explicam o processo de invocar uma caixa de diálogo de uma guia e enviar o resultado.

Invocar uma caixa de diálogo de uma guia

Observação

Começando com o TeamsJS v2.8.x, o dialog namespace dá suporte a caixas de diálogo baseadas em cartão adaptável. O tasks namespace ainda tem suporte para compatibilidade com versões anteriores, no entanto, a melhor prática é atualizar tasks.startTask() as dialog.url.opendialog.adaptiveCard.open caixas de diálogo baseadas em html e cartão adaptável, respectivamente. Para obter mais informações, consulte o namespace da caixa de diálogo.

Você pode invocar uma caixa de diálogo HTML ou Cartão Adaptável de uma guia.

Caixa de diálogo HTML

 microsoftTeams.dialog.url.open(urlDialogInfo, submitHandler);

O valor de UrlDialogInfo.url é definido como o local do conteúdo da caixa de diálogo. A janela da caixa de diálogo é aberta e UrlDialogInfo.url carregada como uma <iframe> dentro dela. JavaScript na página de diálogo chama microsoftTeams.app.initialize(). Se houver uma submitHandler função na página e houver um erro ao invocar microsoftTeams.dialog.url.open(), será submitHandler invocado com err definido como a cadeia de caracteres de erro que indica o mesmo.

Aviso

Os serviços de nuvem da Microsoft, incluindo versões web do Teams (teams.microsoft.com), outlook (outlook.com) e domínios do Microsoft 365 (microsoft365.com) estão migrando para o domínio cloud.microsoft . Execute as seguintes etapas antes de junho de 2024 para garantir que seu aplicativo continue a renderizar no cliente Web do Teams:

1. Atualize o SDK do TeamsJS para v.2.19.0 ou superior. Para obter mais informações sobre a versão mais recente do SDK do TeamsJS, consulte Biblioteca de clientes JavaScript do Microsoft Teams.

2. Atualize os cabeçalhos da Política de Segurança de Conteúdo em seu aplicativo do Teams para permitir que seu aplicativo acesse o domínio teams.cloud.microsoft . Se o aplicativo do Teams se estender pelo Outlook e pelo Microsoft 365, verifique se você permitirá que seu aplicativo acesse teams.cloud.microsoft, outlook.cloud.microsoft e domínios m365.cloud.microsoft .

Caixa de diálogo Cartão Adaptável

 microsoftTeams.dialog.adaptiveCard.open(adaptiveCardDialogInfo, submitHandler);

O valor de adaptiveCardDialogInfo.card é o JSON para um cartão adaptável. Você pode especificar um submitHandler para ser chamado com uma cadeia de caracteres de erro , se houve um erro ao invocar open() ou se o usuário fechar a caixa de diálogo usando o botão X (Sair).

A próxima seção fornece um exemplo de invocação de uma caixa de diálogo.

Exemplo de invocação de uma caixa de diálogo

A imagem a seguir exibe a caixa de diálogo:

O código a seguir é adaptado do exemplo de caixa de diálogo:

TeamsJs v2

let urlDialogInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    fallbackUrl: null,
};

urlDialogInfo.url = "https://contoso.com/teamsapp/customform";
urlDialogInfo.title = "Custom Form";
urlDialogInfo.height = 510;
urlDialogInfo.width = 430;
submitHandler = (submitHandler) => {
        console.log(`Submit handler - err: ${submitHandler.err}`);
        alert("Result = " + JSON.stringify(submitHandler.result) + "\nError = " + JSON.stringify(submitHandler.err));
    };

 microsoftTeams.dialog.url.open(urlDialogInfo, submitHandler);

TeamsJs v1

let taskInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

taskInfo.url = "https://contoso.com/teamsapp/customform";
taskInfo.title = "Custom Form";
taskInfo.height = 510;
taskInfo.width = 430;
submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    console.log(`Submit handler - result\rName: ${result.name}\rEmail: ${result.email}\rFavorite book: ${result.favoriteBook}`);
};
microsoftTeams.tasks.startTask(taskInfo, submitHandler);

O submitHandler ecoa os valores de err ou result para o console.

Enviar o resultado de uma caixa de diálogo

Se houver um erro ao invocar a caixa de diálogo, sua submitHandler função será imediatamente invocada com uma err cadeia de caracteres indicando qual erro ocorreu. A submitHandler função também é chamada com uma err cadeia de caracteres quando o usuário seleciona X na caixa de diálogo para sair.

Se não houver nenhum erro de invocação e o usuário não selecionar X para descartar a caixa de diálogo, o usuário selecionará um botão enviar quando concluído. As seções a seguir explicam o que acontece a seguir para tipos de caixa de diálogo HTML e Cartão Adaptável.

Caixas de diálogo HTML ou JavaScript

Depois de validar a entrada do usuário, chame microsoftTeams.dialog.url.submit(). Você pode chamar submit() sem parâmetros se quiser que o Teams feche a caixa de diálogo ou passe um objeto ou cadeia de caracteres result de volta para seu aplicativo como o primeiro parâmetro e um appId do aplicativo que abriu a caixa de diálogo como o segundo parâmetro. Se você chamar submit() com um result parâmetro, deverá passar uma appId (ou uma matriz de cadeias de appId caracteres de aplicativos autorizados a receber o resultado da caixa de diálogo). Essa ação permite que o Teams valide que o aplicativo que envia o resultado é o mesmo que a caixa de diálogo invocada.

Em seguida, o Teams invocará seu submitHandler local onde err é nulo e result é o objeto ou cadeia de caracteres que você passou para submit().

Caixas de diálogo Cartão Adaptável

Quando você invoca a caixa de diálogo com um submitHandler e o usuário seleciona um Action.Submit botão, os valores no cartão são retornados como seu data objeto. Se o usuário pressionar a tecla Esc ou selecionar X para sair da caixa de diálogo, você submitHandler será chamado com a err cadeia de caracteres. Se seu aplicativo contiver um bot além de uma guia, você poderá incluir o appId do bot como o valor do completionBotId no TaskInfo objeto (BotAdaptiveCardDialogInfo).

O corpo do Cartão adaptável conforme preenchido pelo usuário é enviado ao bot usando uma mensagem task/submit invoke quando o usuário seleciona um botão Action.Submit. O esquema do objeto que você recebe é semelhante ao esquema que você recebe para tarefas/busca e mensagens de tarefa/envio. A única diferença é que o esquema do objeto JSON é um objeto cartão adaptável em vez de um objeto que contém um objeto cartão adaptável como quando Cartões adaptáveis são usados com bots.

O código a seguir é o exemplo de carga:

{
  "task": {
    "type": "continue",
    "value": {
      "title": "Title",
      "height": "height",
      "width": "width",
      "url": null,
      "card": "Adaptive Card or Adaptive Card bot card attachment",
      "fallbackUrl": null,
      "completionBotID": "bot App ID"
    }
  }
}

O código a seguir é o exemplo de solicitação de invocação:

let adaptiveCardDialogInfo = {
    title: "Dialog Demo",
    height: "medium",
    width: "medium",
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

adaptiveCardDialogInfo.card = {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
        {
            "type": "TextBlock",
            "text": "This is a sample adaptive card.",
            "wrap": true
        }
    ]
}

submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    alert(
        "Result = " + JSON.stringify(result) + "\nError = " + JSON.stringify(err)
    );
};

microsoftTeams.dialog.adaptiveCard.open(adaptiveCardDialogInfo, submitHandler);

A próxima seção fornece um exemplo de envio do resultado de uma caixa de diálogo (conhecido como módulo de tarefa no TeamsJS v1.x).

Exemplo de envio do resultado de uma caixa de diálogo

Tomando o exemplo anterior de invocar uma caixa de diálogo HTML, aqui está um exemplo do formulário HTML inserido na caixa de diálogo:

<form method="POST" id="customerForm" action="/register" onSubmit="return validateForm()">

Há cinco campos neste formulário, mas este exemplo requer apenas três valores, name, emaile favoriteBook.

O código a seguir fornece um exemplo da função validateForm() que chama submit():

function validateForm() {
    var customerInfo = {
        name: document.forms["customerForm"]["name"].value,
        email: document.forms["customerForm"]["email"].value,
        favoriteBook: document.forms["customerForm"]["favoriteBook"].value
    }
    microsoftTeams.dialog.url.submit(customerInfo, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
    return true;
}

Erros de invocação de caixa de diálogo

Observação

O tasks namespace é substituído pelo dialog namespace. O dialog namespace inclui sub-namespaces para html (url), cartão adaptável (adaptiveCard) e funcionalidade baseada em bot (dialog.url.bot e dialog.adaptiveCard.bot) .

A tabela a seguir fornece os valores possíveis do err que você submitHandler recebe:

Problema	Mensagem de erro que é o valor de err
Valores para TaskInfo.url e TaskInfo.card foram especificados.	Os valores para cartão e URL foram especificados. Um ou outro, mas não ambos, são permitidos.
TaskInfo.url e TaskInfo.card especificado.	Você deve especificar um valor para o cartão ou a URL.
appId inválido	ID do aplicativo inválida.
O usuário selecionou o botão X, fechando-o.	O usuário cancelou ou fechou a caixa de diálogo.

Exemplo de código

Nome do exemplo	Descrição	.NET	Node.js	Manifesto
Bots de exemplo de caixa de diálogo-V4	Este exemplo mostra como criar caixas de diálogo usando a estrutura do bot v4 e as guias teams.	View	View	View

Próxima etapa

Usando caixas de diálogo de bots

Confira também

• Cartões e caixas de diálogo
• Invocar e descartar caixas de diálogo