Uso de módulos de tareas en pestañas

• 25/06/2020
• Tiempo de lectura: 5 minutos
• • l

Agregar un módulo de tareas a la pestaña puede simplificar enormemente la experiencia del usuario para los flujos de trabajo que requieran la entrada de datos. Los módulos de tareas le permiten recopilar su entrada en un elemento emergente que reconozca los equipos. Un buen ejemplo de esto es editar las tarjetas de Planner; puede usar los módulos de tareas para crear una experiencia similar.

Para admitir la característica de módulo de tareas, se agregaron dos nuevas funciones al SDK del cliente de Microsoft Teams:

microsoftTeams.tasks.startTask(
    taskInfo: TaskInfo,
    submitHandler?: (err: string, result: string | any) => void
): void;

microsoftTeams.tasks.submitTask(
    result?: string | any,
    appIds?: string | string[]
): void;

Vamos a ver cómo funciona cada uno de ellos.

Invocar un módulo de tareas desde una pestaña

Para invocar un módulo de tareas desde una pestaña, use el microsoftTeams.tasks.startTask() paso de un objeto TaskInfo y una submitHandler función de devolución de llamada opcional. Como se describió anteriormente, hay dos casos que hay que tener en cuenta:

1. El valor de TaskInfo.url se establece en una dirección URL. Aparece la ventana módulo de tarea y TaskModule.url se carga como <iframe> en su interior. JavaScript en esa página debe llamar a microsoftTeams.initialize() . Si hay una submitHandler función en la página y se produce un error al invocar microsoftTeams.tasks.startTask() , entonces submitHandler se invoca con err set en la cadena de error que indica el error, como se describe a continuación.
2. El valor de taskInfo.card es el JSON de una tarjeta adaptable. En este caso, obviamente no hay ninguna submitHandler función JavaScript para llamar cuando el usuario cierra o presiona un botón en la tarjeta adaptable; la única forma de recibir lo que el usuario ha escrito es pasar el resultado a un bot. Para usar un módulo de tareas de tarjeta adaptable desde una pestaña, la aplicación debe incluir un bot para obtener la información del usuario. Esto se explica a continuación.

Ejemplo: invocación de un módulo de tareas

El siguiente código se adapta desde el ejemplo de módulo de tarea. Así es como se ve el módulo de tareas:

El submitHandler es muy sencillo; solo repite el valor de err o result a la consola:

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

Enviar el resultado de un módulo de tareas

La submitHandler función se usa con TaskInfo.url . La submitHandler función reside en la TaskInfo.url Página Web. Si hay un error al invocar el módulo de tareas submitHandler , la función se invocará inmediatamente con una err cadena que indica el error que se ha producido. submitHandlerTambién se llama a la función con una err cadena cuando el usuario presiona la X en la parte superior derecha del módulo de tarea.

Si no hay ningún error de invocación y el usuario no presiona X para descartarlo, el usuario presiona un botón cuando termina. En función de si es una dirección URL o una tarjeta adaptable en el módulo de tareas, esto es lo que sucede:

HTML/JavaScript ( TaskInfo.url )

Una vez que haya validado lo que ha escrito el usuario, llame a la microsoftTeams.tasks.submitTask() función SDK (denominada de ahora en adelante con submitTask() fines de legibilidad). submitTask()Si solo desea que Microsoft Teams cierre el módulo de tareas, puede llamar a sin ningún parámetro, pero la mayoría de las veces querrá pasar un objeto o una cadena a su submitHandler .

Pase el resultado como primer parámetro. Microsoft Teams invocará submitHandler dónde será err null y result será el objeto o la cadena que haya pasado submitTask() . Si llama a submitTask() con un result parámetro, debe pasar una appId o una matriz de appId cadenas: Esto permite a Microsoft Teams validar que la aplicación que envía el resultado es la misma que ha invocado el módulo de tareas.

Tarjeta adaptable ( TaskInfo.card )

Si ha invocado el módulo de tareas con una submitHandler , cuando el usuario presiona un Action.Submit botón, los valores de la tarjeta se devolverán como el valor de result . Si el usuario presiona el botón ESC o presiona la X, se err devolverá en su lugar. Como alternativa, si la aplicación contiene un bot, además de una pestaña, puede incluir simplemente el appId Bot? n como el valor de completionBotId en el TaskInfo objeto. El cuerpo de la tarjeta adaptable (como rellenado por el usuario) se enviará al bot a través de un task/submit invoke mensaje cuando el usuario presione un Action.Submit botón. El esquema del objeto que recibe es muy similar al esquema que recibe para los mensajes de tarea/búsqueda y de tarea o envío; 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.

Ejemplo: enviar el resultado de un módulo de tareas

Recupere el formulario en el módulo de tareas anterior con un formulario HTML. Aquí es donde se define el formulario:

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

Hay cinco campos en este formulario, pero solo estamos interesados en los valores de tres de ellos para este ejemplo: name , email y favoriteBook .

Esta es la validateForm() función que llama submitTask() :

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

Errores de invocación de módulo de tarea

Estos son los valores posibles err que puede recibir submitHandler :