Verwenden von Aufgabenmodulen in Registerkarten

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

Zur Unterstützung des Aufgabenmodulfeatures werden dem Teams Client-SDKzwei 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

Zum Aufrufen eines Aufgabenmoduls über eine Registerkarte übergeben Sie microsoftTeams.tasks.startTask() ein TaskInfo-Objekt und eine optionale submitHandler Rückruffunktion. Es gibt zwei Zu berücksichtigende Fälle:

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

Aufgabenmodul – benutzerdefiniertes Formular

Der folgende Code basiert auf dem Aufgabenmodulbeispiel:

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

Dies submitHandler ist sehr einfach und entspricht dem Wert der Konsole oder der err result Konsole.

Übermitteln des Ergebnisses eines Aufgabenmoduls

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

Wenn kein Aufruffehler auftritt und der Benutzer X nicht auswählt, um es zu schließen, wählt der Benutzer nach Abschluss eine Schaltfläche aus. Je nachdem, ob es sich um eine URL oder eine adaptive Karte im Aufgabenmodul handelt, enthalten die nächsten Abschnitte Details dazu, was geschieht.

HTML oder JavaScript TaskInfo.url

Rufen Sie nach dem Überprüfen der Eingaben des Benutzers die microsoftTeams.tasks.submitTask() SDK-Funktion auf, die als submitTask() bezeichnet wird. Rufen submitTask() Sie ohne Parameter auf, wenn Sie nur möchten, dass Teams das Aufgabenmodul schließt. Sie können ein Objekt oder eine Zeichenfolge an Ihre submitHandler übergeben.

Übergeben Sie Ihr Ergebnis als ersten Parameter. Teams ruft auf, wo sich das Objekt oder die Zeichenfolge befindet submitHandler err und null result ist, an die Sie übergeben submitTask() haben. Wenn Sie submitTask() mit einem Parameter result aufrufen, müssen Sie ein oder ein Array von appId appId Zeichenfolgen übergeben. Dadurch können Teams überprüfen, ob die App, die das Ergebnis sendet, mit dem aufgerufenen Aufgabenmodul übereinstimmt.

Adaptive Karte TaskInfo.card

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

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

Beispiel für das Übermitteln 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()">

Es gibt fünf Felder in diesem Formular, 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 err Werte, die von Ihnen empfangen werden submitHandler können:

Problem Fehlermeldung, die den Wert von err
Werte für beide TaskInfo.url werte und TaskInfo.card wurden angegeben. Werte für Karte und URL wurden angegeben. Die eine oder die andere, aber nicht beide, sind zulässig.
TaskInfo.urlWeder TaskInfo.card angegeben noch angegeben. Sie müssen einen Wert für karte oder URL angeben.
appIdUngültig. Ungültige App-ID.
Der Benutzer hat die X-Schaltfläche ausgewählt und sie geschlossen. Der Benutzer hat das Aufgabenmodul abgebrochen oder geschlossen.

Codebeispiel

Beispielname Beschreibung .NET Node.js
Aufgabenmodul-Beispielregisterkarten und Bots-V3 Beispiele zum Erstellen von Aufgabenmodulen. View View

Nächster Schritt

Siehe auch

Aufrufen und Schließen von Aufgabenmodulen