Verwenden von Aufgabenmodulen in Registerkarten

  • Artikel

Fügen Sie Ihrer Registerkarte ein Aufgabenmodul hinzu, um die Erfahrung Ihrer Benutzer mit Workflows zu vereinfachen, die Dateneingaben erfordern. Mit Aufgabenmodulen können Sie ihre Eingaben in einem Microsoft Teams-fähigen Popup erfassen. Ein gutes Beispiel hierfür ist das Bearbeiten von Planner-Karten. Sie können Aufgabenmodule verwenden, um eine ähnliche Erfahrung zu erstellen.

Zur Unterstützung des Aufgabenmodulfeatures werden der Teams JavaScript-Clientbibliothek zwei neue Funktionen hinzugefügt. Der folgende Code zeigt ein Beispiel für diese beiden Funktionen:

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

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

Sie können sehen, wie das Aufrufen eines Aufgabenmoduls über eine Registerkarte und das Übermitteln des Ergebnisses eines Aufgabenmoduls funktioniert.

Aufrufen eines Aufgabenmoduls über eine Registerkarte

Verwenden Sie zum Aufrufen eines Aufgabenmoduls über eine Registerkarte microsoftTeams.tasks.startTask(), und übergeben Sie ein TaskInfo-Objekt und eine optionale submitHandler-Rückruffunktion. Es müssen zwei Fälle berücksichtigt werden:

  • Der Wert von TaskInfo.url ist auf eine URL festgelegt. Das Aufgabenmodulfenster wird angezeigt, und TaskModule.url wird als ein <iframe> darin geladen. JavaScript auf dieser Seite ruft microsoftTeams.initialize() auf. Wenn auf der Seite eine submitHandler Funktion vorhanden ist und beim Aufrufen microsoftTeams.tasks.startTask()von ein Fehler auftritt, submitHandler wird aufgerufen, wobei err auf die Fehlerzeichenfolge festgelegt ist, die dasselbe angibt. Weitere Informationen finden Sie unter Aufgabenmodul-Aufruffehler.
  • Der Wert von taskInfo.card ist der JSON für eine adaptive Karte. Es gibt keine JavaScript-Funktion submitHandler , die aufgerufen werden kann, wenn der Benutzer eine Schaltfläche auf der adaptiven Karte schließt oder drückt. Die einzige Möglichkeit, den vom Benutzer eingegebenen Inhalt zu erhalten, besteht darin, das Ergebnis an einen Bot zu übergeben. Um ein Aufgabenmodul für eine adaptive Karte über eine Registerkarte zu verwenden, muss Ihre App einen Bot enthalten, um eine Antwort vom Benutzer zu erhalten.

Der nächste Abschnitt enthält ein Beispiel für das Aufrufen eines Aufgabenmoduls.

Beispiel für das Aufrufen eines Aufgabenmoduls

In der folgenden Abbildung wird das Aufgabenmodul angezeigt:

Benutzerdefinierte Maske für das Aufgabenmodul

Der folgende Code ist dem Beispiel des Aufgabenmoduls entnommen:

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

ist submitHandler einfach und gibt den Wert von err oder result an die Konsole zurück.

Übermitteln des Ergebnisses eines Aufgabenmoduls

Die submitHandler-Funktion befindet sich auf der TaskInfo.url-Webseite und wird mit TaskInfo.url verwendet. Wenn beim Aufrufen des Aufgabenmoduls ein Fehler auftritt, wird Ihre submitHandler Funktion sofort mit einer err Zeichenfolge aufgerufen, die angibt, welcher Fehler aufgetreten ist. Die submitHandler-Funktion wird auch mit einer err-Zeichenfolge aufgerufen, wenn der Benutzer oben rechts im Aufgabenmodul „X“ auswählt, um es zu schließen.

Wenn kein Aufruffehler auftritt und der Benutzer X nicht auswählt, um es zu schließen, wählt der Benutzer eine Schaltfläche aus, wenn er fertig ist. Je nachdem, ob es sich um eine URL oder eine adaptive Karte im Aufgabenmodul handelt, finden Sie in den nächsten Abschnitten Details dazu, was passiert.

HTML- oder JavaScript-TaskInfo.url

Rufen Sie nach dem Überprüfen der Benutzereingaben die Funktion auf, die microsoftTeams.tasks.submitTask() als bezeichnet wird submitTask(). Rufen Sie submitTask() ohne Parameter auf, wenn Teams nur das Aufgabenmodul schließen soll. Sie können ein Objekt oder eine Zeichenfolge an Ihren submitHandler übergeben.

Übergeben Sie Ihr Ergebnis als ersten Parameter. Teams ruft submitHandler auf, wobei err gleich null ist und result das Objekt oder die Zeichenfolge, das/die Sie an submitTask() übergeben haben. Wenn Sie submitTask() mit einem result-Parameter aufrufen, müssen Sie ein appId oder ein Array von appId-Zeichenfolgen übergeben. Dies erlaubt Teams zu validieren, ob die App, die das Ergebnis sendet, mit dem aufgerufenen Aufgabenmodul übereinstimmt.

Adaptive Karte TaskInfo.card

Wenn Sie das Aufgabenmodul mit einer submitHandler aufrufen und der Benutzer eine Action.Submit-Schaltfläche auswählt, werden die Werte auf der Karte als Wert von result zurückgegeben. Wenn der Benutzer oben rechts die ESC-Taste oder „X“ auswählt, wird stattdessen err zurückgegeben. Wenn Ihre App zusätzlich zu einer Registerkarte einen Bot enthält, können Sie den appId des Bots als Wert von completionBotId in das TaskInfo -Objekt einschließen. Der vom Benutzer ausgefüllte Text der adaptiven Karte wird mithilfe einer task/submit invoke-Nachricht an den Bot gesendet, wenn der Benutzer eine Action.Submit-Schaltfläche auswählt. Das Schema für das Objekt, das Sie erhalten, ähnelt dem Schema, das Sie für Aufgaben-/Abruf- und Task-/Sendenachrichten erhalten. Der einzige Unterschied besteht darin, dass das Schema des JSON-Objekts ein adaptives Kartenobjekt ist, im Gegensatz zu einem Objekt, das ein adaptives Kartenobjekt enthält wie bei der Verwendung von adaptiven Karten mit Bots.

Im Folgenden ist das Beispiel für Nutzlast dargestellt:

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

Im Folgenden ist das Beispiel für eine Aufrufanforderung dargestellt:

let taskInfo = {
    title: "Task Module Demo",
    height: "medium",
    width: "medium",
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

taskInfo.card = {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.4",
    "body": [
        {
            "type": "TextBlock",
            "text": "This is sample adaptive card.",
            "wrap": true
        }
    ]
}

submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    alert(
        "Result = " + JSON.stringify(result) + "\nError = " + JSON.stringify(err)
    );
};

microsoftTeams.tasks.startTask(taskInfo, submitHandler);

Der nächste Abschnitt enthält ein Beispiel für die Übermittlung des Ergebnisses eines Aufgabenmoduls.

Beispiel für die Übermittlung des Ergebnisses eines Aufgabenmoduls

Weitere Informationen finden Sie im HTML-Formular im Aufgabenmodul. Der folgende Code enthält ein Beispiel dafür, wo das Formular definiert ist:

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

Dieses Formular enthält fünf Felder, aber für dieses Beispiel sind nur drei Werte erforderlich: name, email und favoriteBook.

Der folgende Code enthält ein Beispiel für die validateForm()-Funktion, die submitTask() aufruft:

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

Der nächste Abschnitt enthält Aufrufprobleme des Aufgabenmoduls und deren Fehlermeldungen.

Fehler beim Aufrufen des Aufgabenmoduls

Die folgende Tabelle enthält die möglichen Werte von err, die von Ihrem submitHandler empfangen werden können:

Problem Fehlermeldung mit dem Wert err
Es wurden Werte für TaskInfo.url und TaskInfo.card angegeben. Werte für die Karte und die URL wurden angegeben. Die eine oder die andere, aber nicht beide, sind zulässig.
Weder TaskInfo.url noch TaskInfo.card wurden angegeben. Sie müssen einen Wert entweder für die Karte oder die URL angeben.
Ungültige appId. Ungültige App-ID.
Der Benutzer hat die Schaltfläche „X“ ausgewählt und es geschlossen. Der Benutzer hat das Aufgabenmodul abgebrochen oder geschlossen.

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Aufgabenmodul-Beispiel-Bots-V4 In diesem Beispiel wird gezeigt, wie Aufgabenmodule mithilfe von Bot Framework v4 und Teams-Registerkarten erstellt werden. View View Anzeigen

Nächster Schritt

Verwenden von Aufgabenmodulen aus Bots

Siehe auch