Usar cuadros de diálogo en pestañas
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:
// 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.
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, Outlook y Microsoft 365, se migran al *.cloud.microsoft dominio. Realice los pasos siguientes antes de septiembre de 2024 para asegurarse de que la aplicación sigue representándose en los hosts de cliente web de Microsoft 365 admitidos:
Actualice la biblioteca TeamsJS a v.2.19.0 o posterior. Para obtener más información sobre la versión más reciente de TeamsJS, consulte Biblioteca cliente JavaScript de Microsoft Teams.
Si ha definido encabezados de directiva de seguridad de contenido (CSP) para la aplicación, actualice la directiva frame-ancestors para incluir el
*.cloud.microsoftdominio. Para garantizar la compatibilidad con versiones anteriores durante la migración, conserve los valores existentesframe-ancestorsen los encabezados de CSP. Este enfoque garantiza que la aplicación sigue funcionando en aplicaciones host de Microsoft 365 existentes y futuras y minimiza la necesidad de cambios posteriores.
Actualice el dominio siguiente en la frame-ancestors directiva de los encabezados de CSP de la aplicación:
https://*.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:
El código siguiente se adapta desde el ejemplo 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);
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 invoca el submitHandler valor where 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. |
appIdNo 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 |