Usar cuadros de diálogo en pestañas

Artículo
02/07/2024

Agregue diálogos modales (denominados módulos de tareas en TeamsJS v1.x) a las pestañas para simplificar la experiencia del usuario para cualquier flujo de trabajo que requiera entrada de datos. Los cuadros de diálogo permiten recopilar la entrada del usuario en una ventana modal de Microsoft Teams-Aware, como editar tarjetas de Planner. Puede usar diálogos para crear una experiencia similar.

Las dos operaciones principales de los diálogos implican abrirlos y cerrarlos (enviarlos). Las funciones son ligeramente diferentes para versiones anteriores (anteriores a v2.x.x) de la biblioteca teamsJS:

TeamsJs v2
TeamsJs v1

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

Nota:

Solo se puede llamar a la dialog.submit propiedad dentro de un cuadro de diálogo.

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

En las secciones siguientes se explica el proceso de invocar un diálogo desde una pestaña y enviar el resultado.

Invocación de un cuadro de diálogo desde una pestaña

Nota:

A partir de TeamsJS v2.8.x, el dialog espacio de nombres admite diálogos basados en tarjeta adaptable. El tasks espacio de nombres sigue siendo compatible con versiones anteriores; sin embargo, el procedimiento recomendado es actualizar tasks.startTask() la llamada a dialog.url.open o dialog.adaptiveCard.open para los diálogos basados en HTML y tarjeta adaptable, respectivamente. Para obtener más información, vea el espacio de nombres del cuadro de diálogo.

Puede invocar un cuadro de diálogo HTML o tarjeta adaptable desde una pestaña.

Cuadro de diálogo HTML

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

El valor de UrlDialogInfo.url se establece en la ubicación del contenido del cuadro de diálogo. Se abre la ventana de diálogo y UrlDialogInfo.url se carga como una <iframe> dentro de ella. JavaScript en la página de diálogo llama a microsoftTeams.app.initialize(). Si hay una submitHandler función en la página y hay un error al invocar microsoftTeams.dialog.url.open(), submitHandler se invoca con err establecido en la cadena de error que indica lo mismo.

Advertencia

Los servicios en la nube de Microsoft, incluidas las versiones web de los dominios de Teams (teams.microsoft.com), Outlook (outlook.com) y Microsoft 365 (microsoft365.com) se migran al dominio cloud.microsoft . Realice los pasos siguientes antes de junio de 2024 para asegurarse de que la aplicación continúa representándose en el cliente web de Teams:

Actualice el SDK de TeamsJS a la versión 2.19.0 o posterior. Para obtener más información sobre la versión más reciente del SDK de TeamsJS, consulte Biblioteca cliente JavaScript de Microsoft Teams.
Actualice los encabezados de la directiva de seguridad de contenido en la aplicación de Teams para permitir que la aplicación acceda al dominio teams.cloud.microsoft . Si la aplicación de Teams se extiende a través de Outlook y Microsoft 365, asegúrese de permitir que la aplicación acceda a los dominios teams.cloud.microsoft, outlook.cloud.microsoft y m365.cloud.microsoft .

Cuadro de diálogo Tarjeta adaptable

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

El valor de adaptiveCardDialogInfo.card es el JSON de una tarjeta adaptable. Puede especificar que submitHandler se llame a con una cadena err , si se produjo un error al invocar open() o si el usuario cierra el cuadro de diálogo con el botón X (Salir).

En la sección siguiente se proporciona un ejemplo de invocación de un cuadro de diálogo.

Ejemplo de invocación de un cuadro de diálogo

En la imagen siguiente se muestra el cuadro de diálogo:

Formulario personalizado del módulo de tareas

El código siguiente se adapta desde el ejemplo de diálogo:

TeamsJs v2
TeamsJs v1

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

submitHandler hace eco de los valores de err o result a la consola.

Enviar el resultado de un cuadro de diálogo

Si se produce un error al invocar el cuadro de diálogo, submitHandler la función se invoca inmediatamente con una err cadena que indica qué error se produjo. También submitHandler se llama a la función con una err cadena cuando el usuario selecciona X en el cuadro de diálogo para salir.

Si no hay ningún error de invocación y el usuario no selecciona X para descartar el cuadro de diálogo, el usuario selecciona un botón enviar cuando termine. En las secciones siguientes se explica lo que sucede a continuación para los tipos de diálogo HTML y tarjeta adaptable.

Cuadros de diálogo HTML o JavaScript

Después de validar la entrada del usuario, llame a microsoftTeams.dialog.url.submit(). Puede llamar a submit() sin ningún parámetro si desea que Teams cierre el cuadro de diálogo, o bien puede volver a pasar un objeto o cadena result a la aplicación como primer parámetro y una appId de la aplicación que abrió el cuadro de diálogo como segundo parámetro. Si llama submit() a con un result parámetro, debe pasar ( appId o una matriz de cadenas de appId aplicaciones autorizadas para recibir el resultado del cuadro de diálogo). Esta acción permite a Teams validar que la aplicación que envía el resultado es la misma que el cuadro de diálogo invocado.

A continuación, Teams invocará su submitHandler donde err es null y result es el objeto o cadena que ha pasado a submit().

Cuadros de diálogo de tarjeta adaptable

Al invocar el cuadro de diálogo con y submitHandler el usuario selecciona un Action.Submit botón, los valores de la tarjeta se devuelven como su data objeto. Si el usuario presiona la tecla Esc o selecciona X para salir del cuadro de diálogo, submitHandler se le llama con la err cadena . Si la aplicación contiene un bot además de una pestaña, puede incluir el appId del bot como el valor de completionBotId en el TaskInfo objeto (BotAdaptiveCardDialogInfo).

El cuerpo de la tarjeta adaptable rellenado por el usuario se envía al bot mediante un mensaje de task/submit invoke cuando el usuario selecciona un botón de Action.Submit. El esquema del objeto que recibe es similar al esquema que recibe para los mensajes task/fetch y task/submit. La única diferencia es que el esquema del objeto JSON es un objeto de tarjeta adaptable en lugar de un objeto que contiene un objeto de tarjeta adaptable como cuando se usan tarjetas adaptables con bots.

El código siguiente es el ejemplo de carga útil:

{
  "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"
    }
  }
}

El código siguiente es el ejemplo de solicitud invoke:

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

En la sección siguiente se proporciona un ejemplo de envío del resultado de un cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x).

Ejemplo de envío del resultado de un cuadro de diálogo

Tomando el ejemplo anterior de invocación de un cuadro de diálogo HTML, este es un ejemplo del formulario HTML incrustado en el cuadro de diálogo:

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

Hay cinco campos en este formulario, pero este ejemplo solo requiere tres valores, name, emaily favoriteBook.

El código siguiente proporciona un ejemplo de la función validateForm() que llama a 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;
}

Errores de invocación de cuadros de diálogo

Nota:

El tasks espacio de nombres se reemplaza por el espacio de dialog nombres. El dialog espacio de nombres incluye sub namespaces para la funcionalidad HTML (url), Adaptive Card (adaptiveCard) y bot-based (dialog.url.bot y dialog.adaptiveCard.bot).

En la tabla siguiente se proporcionan los valores posibles de err que submitHandler recibe:

Problema	Mensaje de error que es el valor de `err`
Se especificaron valores para `TaskInfo.url` y `TaskInfo.card`.	Se especificaron valores para la tarjeta y la dirección URL. Se permiten una u otra, pero no ambas.
`TaskInfo.url` y `TaskInfo.card` especificados.	Debe especificar un valor para la tarjeta o la dirección URL.
`appId`No válido.	Id. de aplicación no válido.
El usuario seleccionó el botón X y lo cerró.	El usuario canceló o cerró el cuadro de diálogo.

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js	Manifiesto
Bots de ejemplo de cuadro de diálogo-V4	En este ejemplo se muestra cómo crear diálogos mediante las pestañas bot framework v4 y teams.	View	View	View

Paso siguiente

Uso de diálogos de bots

Usar cuadros de diálogo en pestañas

Invocación de un cuadro de diálogo desde una pestaña

Cuadro de diálogo HTML

Cuadro de diálogo Tarjeta adaptable

Ejemplo de invocación de un cuadro de diálogo

Enviar el resultado de un cuadro de diálogo

Cuadros de diálogo HTML o JavaScript

Cuadros de diálogo de tarjeta adaptable

Ejemplo de envío del resultado de un cuadro de diálogo

Errores de invocación de cuadros de diálogo

Ejemplo de código

Paso siguiente

Consulte también

Comentarios

Recursos adicionales