Utilizar caixas de diálogo em separadores

Adicione caixas de diálogo modais (referidas como módulos de tarefas no TeamsJS v1.x) aos seus separadores para simplificar a experiência do utilizador para quaisquer fluxos de trabalho que necessitem de introdução de dados. As caixas de diálogo permitem-lhe recolher entradas de utilizadores numa janela modal do Microsoft Teams-Aware, como editar cartões do Planner. Pode utilizar caixas de diálogo para criar uma experiência semelhante.

As duas principais operações das caixas de diálogo envolvem abri-las e fechá-las (submeter). As funções são ligeiramente diferentes para versões anteriores (antes de v2.x.x) da biblioteca do 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 secções seguintes explicam o processo de invocar uma caixa de diálogo a partir de um separador e submeter o resultado.

Invocar uma caixa de diálogo a partir de um separador

Pode invocar uma caixa de diálogo HTML ou Cartão Ajustável a partir de um separador.

Caixa de diálogo HTML

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

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

https://*.cloud.microsoft

Caixa de diálogo Cartão Ajustável

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

O valor de adaptiveCardDialogInfo.card é o JSON para um cartão adaptável. Pode especificar um submitHandler para ser chamado com uma cadeia de erro, se tiver ocorrido um erro ao invocar open() ou se o utilizador fechar a caixa de diálogo com o botão X (Sair).

A secção seguinte dá um exemplo de invocação de uma caixa de diálogo.

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

A imagem seguinte apresenta a caixa de diálogo:

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

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

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 a consola.

Submeter o resultado de uma caixa de diálogo

Se ocorrer um erro ao invocar a caixa de diálogo, a função submitHandler é imediatamente invocada com uma err cadeia que indica o erro. A submitHandler função também é chamada com uma cadeia err quando o utilizador seleciona X na caixa de diálogo para sair.

Se não existir nenhum erro de invocação e o utilizador não selecionar X para dispensar a caixa de diálogo, o utilizador seleciona um botão submeter quando terminar. As secções seguintes explicam o que acontece a seguir para os tipos de caixa de diálogo HTML e Cartão Ajustável.

Caixas de diálogo HTML ou JavaScript

Depois de validar a entrada do utilizador, chame microsoftTeams.dialog.url.submit(). Pode chamar submit() sem parâmetros se pretender que o Teams feche a caixa de diálogo ou pode transmitir um objeto ou result cadeia de carateres de volta para a sua aplicação como o primeiro parâmetro e uma appId da aplicação que abriu a caixa de diálogo como o segundo parâmetro. Se chamar submit() com um result parâmetro, tem de transmitir uma appId (ou uma matriz de cadeias de appId aplicações autorizadas a receber o resultado da caixa de diálogo). Esta ação permite ao Teams validar que a aplicação que envia o resultado é igual à caixa de diálogo invocada.

Em seguida, o Teams invoca o seu submitHandler local onde err é nulo e result é o objeto ou cadeia que passou para submit().

Caixas de diálogo cartão ajustável

Quando invoca a caixa de diálogo com um submitHandler e o utilizador seleciona um Action.Submit botão, os valores no cartão são devolvidos como o respetivo data objeto. Se o utilizador premir a tecla Esc ou selecionar X para sair da caixa de diálogo, a sua submitHandler é chamada com a cadeia err . Se a sua aplicação contiver um bot para além de um separador, pode 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 que recebe é semelhante ao esquema que recebe para mensagens de tarefa/obtenção e tarefa/submissão. 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 seguinte é o exemplo de payload:

{
  "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 seguinte é o exemplo de Invocar pedido:

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 secção seguinte fornece um exemplo de submissão do resultado de uma caixa de diálogo (referida como módulo de tarefa no TeamsJS v1.x).

Exemplo de submissão do resultado de uma caixa de diálogo

Ao seguir o exemplo anterior de invocar uma caixa de diálogo HTML, eis 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, 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

A tabela seguinte fornece os valores possíveis dos err que recebe submitHandler :

Exemplo de código

Próxima etapa

Confira também

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