Verwenden von Aufgaben Modulen in RegisterkartenUsing task modules in tabs

Das Hinzufügen eines Aufgabenmoduls zur Registerkarte kann die Benutzerfreundlichkeit für Workflows erheblich vereinfachen, die Dateneingaben erfordern.Adding a task module to your tab can greatly simplify your user's experience for any workflows that require data input. Aufgaben Module ermöglichen es Ihnen, Ihre Eingaben in einem Teams-fähigen Popup-Fenster zu erfassen.Task modules allow you to gather their input in a Teams-aware popup. Ein gutes Beispiel hierfür ist das Bearbeiten von Planner-Karten; Sie können Aufgaben Module verwenden, um eine ähnliche Erfahrung zu erstellen.A good example of this is editing Planner cards; you can use task modules to create a similar experience.

Zur Unterstützung der Funktion "Aufgabenmodul" wurden dem Microsoft Teams-Client SDKzwei neue Funktionen hinzugefügt:To support the task module feature, two new functions were added to the Microsoft Teams client SDK:

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

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

Mal sehen, wie jeder von Ihnen funktioniert.Let's see how each of them work.

Aufrufen eines Aufgabenmoduls über eine RegisterkarteInvoking a task module from a tab

Zum Aufrufen eines Aufgabenmoduls aus einer Registerkarte verwenden Sie microsoftTeams.tasks.startTask() das Übergeben eines taskinfo-Objekts und einer optionalen submitHandler Rückruffunktion.To invoke a task module from a tab use microsoftTeams.tasks.startTask() passing a TaskInfo object and an optional submitHandler callback function. Wie zuvor beschrieben, gibt es zwei Fälle, die beachtet werden sollten:As described earlier, there are two cases to consider:

  1. Der Wert von TaskInfo.url ist auf eine URL festgelegt.The value of TaskInfo.url is set to a URL. Das Fenster Aufgabenmodul wird angezeigt, und TaskModule.url es wird als <iframe> darin geladen.The task module window appears and TaskModule.url is loaded as an <iframe> inside it. JavaScript auf dieser Seite sollte aufgerufen werden microsoftTeams.initialize() .JavaScript on that page should call microsoftTeams.initialize(). Wenn submitHandler auf der Seite eine Funktion vorhanden ist und beim Aufrufen ein Fehler auftritt microsoftTeams.tasks.startTask() , submitHandler wird mit err festgelegt, dass die Fehlerzeichenfolge den Fehler wie untenbeschrieben angibt.If there is a submitHandler function on the page and there is an error when invoking microsoftTeams.tasks.startTask(), then submitHandler is invoked with err set to the error string indicating the error as described below.
  2. Der Wert von taskInfo.card ist JSON für eine Adaptive Karte.The value of taskInfo.card is the JSON for an Adaptive card. In diesem Fall gibt es natürlich keine JavaScript- submitHandler Funktion, die aufgerufen wird, wenn der Benutzer eine Schaltfläche auf der adaptiven Karte schließt oder drückt; die einzige Möglichkeit, die Eingabe des Benutzers zu erhalten, besteht darin, das Ergebnis an einen bot zu übergeben.In this case there's obviously not any JavaScript submitHandler function to call when the user closes or presses a button on the Adaptive card; the only way to receive what the user entered is by passing the result to a bot. Um einen Adaptive Card-Aufgabenmodul aus einer Registerkarte zu verwenden, muss Ihre APP einen bot enthalten, um alle Informationen vom Benutzer zurück zu erhalten.To use an Adaptive card task module from a tab your app must include a bot to get any information back from the user. Dies wird im folgenden erläutert.This is explained below.

Beispiel: Aufrufen eines AufgabenmodulsExample: Invoking a task module

Der folgende Code wird aus dem Aufgabenmodul Beispielangepasst.The code below is adapted from the task module sample. Hier sehen Sie, wie das Aufgabenmodul aussieht:Here's what the task module looks like:

Aufgabenmodul – benutzerdefiniertes Formular

Das submitHandler ist sehr einfach; er gibt nur den Wert von err oder result in der Konsole wieder:The submitHandler is very simple; it just echoes the value of err or result to the console:

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

Übermitteln des Ergebnisses eines AufgabenmodulsSubmitting the result of a task module

Die submitHandler -Funktion wird mit verwendet TaskInfo.url .The submitHandler function is used with TaskInfo.url. Die submitHandler Funktion befindet sich auf der TaskInfo.url Webseite.The submitHandler function resides in the TaskInfo.url web page. Wenn beim Aufrufen des Aufgabenmoduls ein Fehler auftritt submitHandler , wird die Funktion sofort mit einer err Zeichenfolge aufgerufen, die angibt, welcher Fehler aufgetretenist.If there's an error when invoking the task module your submitHandler function will be immediately invoked with an err string indicating which error occurred. Die submitHandler Funktion wird auch mit einer err Zeichenfolge aufgerufen, wenn der Benutzer das X in der oberen rechten Ecke des Aufgabenmoduls drückt.The submitHandler function is also called with an err string when the user presses the X at the upper right of task module.

Wenn kein Aufruffehler vorliegt und der Benutzer nicht X drückt, um ihn zu schließen, drückt der Benutzer nach Abschluss eine Schaltfläche.If there's no invocation error and the user doesn't press X to dismiss it, the user presses a button when finished. In Abhängigkeit davon, ob es sich um eine URL oder eine Adaptive Karte im Aufgabenmodul handelt, gehen Sie folgendermaßen vor:Depending on whether it's a URL or an Adaptive card in the task module, here's what happens:

HTML/JavaScript ( TaskInfo.url )HTML/JavaScript (TaskInfo.url)

Nachdem Sie überprüft haben, was der Benutzer eingegeben hat, rufen Sie die microsoftTeams.tasks.submitTask() SDK-Funktion auf (wird im folgenden als submitTask() Zweck der Lesbarkeit bezeichnet).Once you've validated what the user has entered you call the microsoftTeams.tasks.submitTask() SDK function (referred to hereafter as submitTask() for readability purposes). Sie können submitTask() ohne Parameter aufrufen, wenn Sie lediglich möchten, dass Teams den Aufgabenmodul schließen, aber in den meisten Fällen möchten Sie ein Objekt oder eine Zeichenfolge an Ihren übergeben submitHandler .You can call submitTask() without any parameters if you just want Teams to close the task module, but most of the time you'll want to pass an object or a string to your submitHandler.

Übergeben Sie das Ergebnis als ersten Parameter.Pass your result as the first parameter. Teams rufen an, submitHandler wo err null result das Objekt/die Zeichenfolge, an das Sie übergeben werden, sein wird und wird submitTask() .Teams will invoke submitHandler where err will be null and result will be the object/string you passed to submitTask(). Wenn Sie submitTask() einen result Parameter aufrufen, müssen Sie ein appId oder ein Array von appId Zeichenfolgen übergeben: Dadurch können Teams überprüfen, ob die APP, die das Ergebnis sendet, dieselbe ist, die das Aufgabenmodul aufgerufen hat.If you do call submitTask() with a result parameter, you must pass an appId or an array of appId strings: this allows Teams to validate that the app sending the result is the same one which invoked the task module.

Adaptive Karte ( TaskInfo.card )Adaptive card (TaskInfo.card)

Wenn Sie den Aufgabenmodul mit einem aufgerufen submitHandler haben und der Benutzer eine Schaltfläche drückt, werden Action.Submit die Werte in der Karte als Wert von zurückgegeben result .If you invoked the task module with a submitHandler, when the user presses an Action.Submit button the values in the card will be returned as the value of result. Wenn der Benutzer die ESC-Taste drückt oder das X drückt, err wird stattdessen zurückgegeben.If the user presses the Esc button or presses the X, err will be returned instead. Alternativ können Sie, wenn Ihre APP zusätzlich zu einer Registerkarte einen bot enthält, den appId des bot einfach als Wert completionBotId in das TaskInfo Objekt einschließen.Alternatively, if your app contains a bot in addition to a tab you can simply include the appId of the bot as the value of completionBotId in the TaskInfo object. Der Adaptive Kartentext (wie vom Benutzer ausgefüllt) wird über eine Nachricht an den bot gesendet, task/submit invoke Wenn der Benutzer eine Action.Submit Schaltfläche drückt.The Adaptive card body (as filled in by the user) will be sent to the bot via a task/submit invoke message when the user presses an Action.Submit button. Das Schema für das empfangene Objekt ähnelt dem Schema, das Sie für Aufgaben/FETCH-und Task-/Submit-Nachrichten erhalten. der einzige Unterschied besteht darin, dass das Schema des JSON-Objekts ein adaptives Kartenobjekt im Gegensatz zu einem Objekt ist, das ein adaptives Kartenobjekt enthält , als Wenn Adaptive Karten mit Bots verwendet werden.The schema for the object you receive is very similar to the schema you receive for task/fetch and task/submit messages; the only difference is that the schema of the JSON object is an Adaptive card object as opposed to an object containing an Adaptive card object as when Adaptive cards are used with bots.

Beispiel: übermitteln des Ergebnisses eines AufgabenmodulsExample: submitting the result of a task module

Rufen Sie das Formular im obigen Aufgabenmodul mit einem HTML-Formular auf.Recall the form in the task module above with an HTML form. Hier wird das Formular definiert:Here's where the form is defined:

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

Es gibt fünf Felder in diesem Formular, aber wir sind nur an den Werten von drei für dieses Beispiel interessiert: name , email und favoriteBook .There are five fields on this form but we're only interested in the values of three of them for this example: name, email, and favoriteBook.

Hier ist die validateForm() Funktion, die submitTask() Folgendes aufruft:Here's the validateForm() function that calls 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;
}

Fehler beim Aufrufen des AufgabenmodulsTask module invocation errors

Hier sind die möglichen Werte err , die von Ihrem empfangen werden können submitHandler :Here are the possible values of err that can be received by your submitHandler:

ProblemProblem Fehlermeldung (Wert von err )Error message (value of err)
Werte für beide TaskInfo.url und TaskInfo.card wurden angegeben.Values for both TaskInfo.url and TaskInfo.card were specified. "Die Werte für Karte und URL wurden angegeben."Values for both card and url were specified. Die eine oder die andere, aber nicht beides, sind zulässig. "One or the other, but not both, are allowed."
Weder TaskInfo.url noch TaskInfo.card angegeben.Neither TaskInfo.url nor TaskInfo.card specified. "Sie müssen einen Wert für die Karten-oder URL-Adresse angeben.""You must specify a value for either card or url."
Ungültig appId .Invalid appId. "Ungültige Typkennung"."Invalid appId."
Der Benutzer hat die X-Schaltfläche gedrückt und geschlossen.User pressed X button, closing it. "Benutzer hat den Aufgabenmodul storniert/geschlossen.""User cancelled/closed the task module."