Usar caixas de diálogo em guias

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

As duas principais operações dos diálogos envolvem abri-los e fechá-los (enviá-los). As funções são ligeiramente diferentes para versões anteriores (anteriores à v2.x.x) da biblioteca TeamsJS:

// 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;

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

Você pode invocar uma caixa de diálogo HTML ou Cartão Adaptável em 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 um <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(), então submitHandler será invocado com err set para a cadeia de caracteres de erro indicando o mesmo.

https://*.cloud.microsoft

Caixa de diálogo Cartão Adaptável

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

O valor de adaptiveCardDialogInfo.card é o JSON de um Cartão Adaptável. Você pode especificar um submitHandler a ser chamado com uma cadeia de caracteres err , se houver 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:

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

urlDialogInfo.url = "https://contoso.com/atk/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);

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

taskInfo.url = "https://contoso.com/atk/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);

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

Enviar o resultado de um 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 ignorar a caixa de diálogo, o usuário selecionará um botão de envio quando terminar. As seções a seguir explicam o que acontece a seguir para os 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 pode passar 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 um 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 invoca seu submitHandler where err is null e result is the object or string que você passou para submit().

Caixas de diálogos do 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 card 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, Ur submitHandler será chamado com a err cadeia de caracteres. Se o aplicativo contiver um bot além de uma guia, você poderá incluir o appId do bot como o valor de 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 recebido é semelhante ao esquema recebido para mensagens de envio de diálogo. A única diferença é que o esquema do objeto JSON é um objeto Adaptive Card em vez de um objeto que contém um objeto Adaptive Card, como quando Cartões Adaptáveis são usados com bots.

O código a seguir é o exemplo de conteúdo:

{
  "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 Invocar solicitaçã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 (referido como módulo de tarefa no TeamsJS v1.x).

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

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

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

Existem cinco campos neste formulário, mas este exemplo requer apenas três valores, name, email, e 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

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

Exemplo de código

Próxima etapa

Confira também

• Cartões e caixas de diálogo
• Invocar e ignorar diálogos