Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In diesem Artikel wird beschrieben, wie Sie Dialoge (früher als Aufgabenmodule bezeichnet) mithilfe des Teams SDK (Teams KI-Bibliothek) aufrufen und schließen. Im Teams SDK werden Dialoge über Adaptive Card-Aktionen mithilfe von TaskFetchAction aufgerufen und über dialog open- und submit-Ereignisse für die App Klasse behandelt.
Die Ereignisregistrierung variiert je nach Sprache:
-
TypeScript:
app.on('dialog.open', ...)undapp.on('dialog.submit', ...) -
C#:
teamsApp.OnTaskFetch(...)undteamsApp.OnTaskSubmit(...) -
Python:
@app.on_dialog_openund@app.on_dialog_submit
Der Dialoginhalt kann eine adaptive Karte oder eine URL-basierte Webseite sein.
Dialoge können je nach App-Architektur auch über andere Ansätze aufgerufen werden:
- Über Registerkarten, die die TeamsJS-Clientbibliothek verwenden. Weitere Informationen finden Sie unter Verwenden von Dialogfeldern in Registerkarten.
- Von Bots, die Bot Framework oder Deep-Links verwenden. Weitere Informationen finden Sie unter Verwenden von Dialogen mit Bots.
- Aus einer Deep Link-URL. Informationen zum Öffnen eines Dialogfelds finden Sie unter Deep-Link.
Anleitungen zur Migration von Bot Framework zum Teams SDK finden Sie unter Migrieren von BotBuilder.
In der folgenden Tabelle wird die Funktionsweise von Dialogfeldern im Teams SDK zusammengefasst:
| Schritt | Dialog mit adaptiver Karte | Dialogfeld mit Webseiten-URL |
|---|---|---|
| Auslösen des Dialogfelds | 1. Senden Sie eine adaptive Karte mit einer TaskFetchAction Schaltfläche an den Benutzer. Die Daten der value Aktion geben den Typ des zu öffnenden Dialogfelds an. 2. Wenn der Benutzer die Schaltfläche auswählt, sendet Teams einen Task fetch-Aufruf an Ihre App. |
1. Senden Sie eine adaptive Karte mit einer TaskFetchAction Schaltfläche an den Benutzer. 2. Wenn der Benutzer die Schaltfläche auswählt, sendet Teams einen Task fetch-Aufruf an Ihre App. |
| Behandeln des Dialogöffnungsereignisses | 3. Geben Sie im Handler zum Öffnen des Dialogfelds eine Fortsetzungsantwort des Aufgabenmoduls zurück, die Dialogmetadaten (Titel, Dimensionen und die anzuzeigende adaptive Karte) enthält. Verwenden Sie TaskInfo in C# mit einem ContinueTask Wrapper. Verwenden Sie CardTaskModuleTaskInfoin TypeScript . Verwenden Sie CardTaskModuleTaskInfo in Python innerhalb eines TaskModuleContinueResponse. |
3. Geben Sie im Handler zum Öffnen des Dialogfelds eine Fortsetzungsantwort des Aufgabenmoduls zurück, die Dialogmetadaten mit einer url Eigenschaft enthält, die auf die Webseite verweist. Die URL-Domäne muss sich im validDomains Array in Ihrem App-Manifest befinden. Verwenden Sie TaskInfoin C# . Verwenden Sie UrlTaskModuleTaskInfoin TypeScript . Verwenden Sie UrlTaskModuleTaskInfo in Python innerhalb eines TaskModuleContinueResponse. |
| Behandeln der Dialogübermittlung | 4. Wenn der Benutzer eine Action.Submit Schaltfläche drückt, sendet Teams eine Aufgabe übermitteln Aufruf an Ihre App mit den Formulardaten. 5. Sie können antworten wie folgt: • Nichts tun (Aufgabe abgeschlossen) • Anzeigen einer Meldung (C#: MessageTask, TypeScript/Python: TaskModuleMessageResponse) • Verketten mit einem anderen Dialogfeld (C#: ContinueTask, TypeScript/Python: TaskModuleContinueResponse) |
4. Die Webseite ruft die Teams JS-Clientbibliothek auf, um Daten zurückzusenden. Teams sendet einen Task-Submit-Aufruf an Ihre App mit dem Ergebnis. |
Im nächsten Abschnitt werden die Dialogmetadaten beschrieben, die den Inhalt und die Darstellung eines Dialogs definieren.
Dialogmetadaten
Die Dialogmetadaten definieren den Inhalt und die Darstellung eines Dialogs. Jede Sprache verwendet ihre eigenen Typen, um diese Metadaten darzustellen:
-
C#:
TaskInfo(vonMicrosoft.Teams.Api.TaskModules) -
TypeScript:
CardTaskModuleTaskInfooderUrlTaskModuleTaskInfo(von@microsoft/teams.api) -
Python:
CardTaskModuleTaskInfooderUrlTaskModuleTaskInfo(vonmicrosoft_teams.api)
In der folgenden Tabelle sind die allgemeinen Eigenschaften in allen Sprachen aufgeführt:
| Attribut | Typ | Beschreibung |
|---|---|---|
title |
string | Dieses Attribut wird unter dem App-Namen und rechts neben dem App-Symbol angezeigt. |
height |
Zahl oder Zeichenfolge | Dieses Attribut kann eine Zahl sein, die die Höhe des Dialogfelds in Pixel oder small, mediumoder largedarstellt. Verwenden Sie Union<int, Size>in C# . |
width |
Zahl oder Zeichenfolge | Dieses Attribut kann eine Zahl sein, die die Breite des Dialogfelds in Pixel oder small, mediumoder largedarstellt. Verwenden Sie Union<int, Size>in C# . |
url |
string | Die URL der Seite, die als im <iframe> Dialogfeld geladen wurde. Die Domäne der URL muss sich im validDomains-Array der App in Ihrem App-Manifest befinden. Verwenden Sie UrlTaskModuleTaskInfo in TypeScript/Python, oder legen Sie die Url Eigenschaft in C# fest TaskInfo . |
card |
Attachment | Die adaptive Karte, die im Dialogfeld angezeigt werden soll. Legen Sie in C# die Card -Eigenschaft auf TaskInfo mit einem fest Attachment. Verwenden Sie cardAttachment() in TypeScript mit CardTaskModuleTaskInfo. Verwenden Sie card_attachment(AdaptiveCardAttachment(...)) in Python mit CardTaskModuleTaskInfo. |
Hinweis
Das Dialogfeldfeature erfordert, dass die Domänen aller URLs, die validDomains Sie laden möchten, im Array im Manifest Ihrer App enthalten sind.
Im nächsten Abschnitt wird die Größe des Dialogfelds angegeben, mit der der Benutzer die Höhe und Breite des Dialogfelds festlegen kann.
Dialogfeldgrößenanpassung
Die Werte von width und height legen die Höhe und Breite des Dialogfelds in Pixel fest. Abhängig von der Größe des Teams-Fensters und der Bildschirmauflösung können diese Werte proportional reduziert werden, während das Seitenverhältnis beibehalten wird.
Wenn width und height , mediumoder largesindsmall, entspricht die Größe des roten Rechtecks in der folgenden Abbildung einem Anteil des verfügbaren Platzes, 20 %, 50 % und 60 % für width und 20 %, 50 % und 66 % für height:
Der nächste Abschnitt enthält Beispiele für das Auslösen und Behandeln von Dialogen mithilfe des Teams SDK.
Auslösen eines Dialogfelds mit TaskFetchAction
Um ein Dialogfeld zu öffnen, senden Sie eine adaptive Karte mit einer TaskFetchAction Schaltfläche. Wenn der Benutzer die Schaltfläche auswählt, sendet Teams einen Aufruf zum Abrufen einer Aufgabe an Ihre App. Die Daten jeder Schaltfläche geben den Typ des zu öffnenden Dialogfelds value an (z. B { "data": "AdaptiveCard" }. ).
using Microsoft.Teams.Api.Activities;
using Microsoft.Teams.Cards;
teamsApp.OnMessage(async (context) =>
{
var card = new AdaptiveCard
{
Body = new List<CardElement>
{
new TextBlock("Task Module Invocation from Adaptive Card")
{
Weight = TextWeight.Bolder,
Size = TextSize.Large
}
},
Actions = new List<Action>
{
new TaskFetchAction(new Dictionary<string, object?> { { "data", "AdaptiveCard" } })
{ Title = "Adaptive Card" },
new TaskFetchAction(new Dictionary<string, object?> { { "data", "CustomForm" } })
{ Title = "Custom Form" },
new TaskFetchAction(new Dictionary<string, object?> { { "data", "MultiStep" } })
{ Title = "Multi-step Form" }
}
};
await context.Send(new MessageActivity
{
Attachments = new List<Attachment>
{
new Attachment
{
ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
Content = card
}
}
});
});
Behandeln des Dialogöffnungsereignisses
Wenn Teams einen Aufruf zum Abrufen einer Aufgabe sendet, gibt Ihre App den Dialoginhalt zurück. Der Inhalt kann eine adaptive Karte oder eine Webseiten-URL sein. Umschließen Sie in C# die Dialogmetadaten in einer ContinueTask Antwort. Geben Sie in TypeScript mit type: 'continue'zurückTaskModuleResponse. Geben Sie in Python eine InvokeResponse zurück, die eine enthält TaskModuleContinueResponse.
using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Cards;
using Microsoft.Teams.Common;
teamsApp.OnTaskFetch(async (context) =>
{
var activity = context.Activity;
var json = JsonSerializer.Deserialize<JsonElement>(JsonSerializer.Serialize(activity));
var data = json.GetProperty("value").GetProperty("data").GetProperty("data").GetString();
TaskInfo taskInfo;
if (data == "CustomForm")
{
taskInfo = new TaskInfo
{
Title = "Custom Form",
Width = new Union<int, Size>(510),
Height = new Union<int, Size>(450),
Url = $"{botEndpoint}/customform",
FallbackUrl = $"{botEndpoint}/customform"
};
}
else if (data == "MultiStep")
{
var step1Card = new AdaptiveCard
{
Body = new List<CardElement>
{
new TextBlock("Step 1 of 2 - Your Name") { Size = TextSize.Large, Weight = TextWeight.Bolder },
new TextInput { Id = "name", Label = "Name", Placeholder = "Enter your name", IsRequired = true }
},
Actions = new List<Action>
{
new SubmitAction().WithTitle("Next").WithData(
new Union<string, SubmitActionData>(new SubmitActionData
{
NonSchemaProperties = new Dictionary<string, object?> { { "submissiontype", "multi_step_1" } }
}))
}
};
taskInfo = new TaskInfo
{
Title = "Multi-step Form",
Width = new Union<int, Size>(400),
Height = new Union<int, Size>(300),
Card = new Attachment
{
ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
Content = step1Card
}
};
}
else
{
var dialogCard = new AdaptiveCard
{
Body = new List<CardElement>
{
new TextBlock("Enter Text Here") { Weight = TextWeight.Bolder },
new TextInput { Id = "usertext", Placeholder = "add some text and submit", IsMultiline = true }
},
Actions = new List<Action> { new SubmitAction { Title = "Submit" } }
};
taskInfo = new TaskInfo
{
Title = "Adaptive Card: Inputs",
Width = new Union<int, Size>(400),
Height = new Union<int, Size>(200),
Card = new Attachment
{
ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
Content = dialogCard
}
};
}
return new Response(new ContinueTask(taskInfo));
});
Behandeln der Dialogübermittlung
Wenn ein Benutzer in einem Dialogfeld drückt Action.Submit , sendet Teams einen Aufruf zum Übermitteln einer Aufgabe an Ihre App. Sie können antworten, indem Sie die Aufgabe abschließen, eine Nachricht anzeigen oder ein weiteres Dialogfeld öffnen (z. B. zum Verketten von Formularen mit mehreren Schritten).
using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Cards;
using Microsoft.Teams.Common;
teamsApp.OnTaskSubmit(async (context) =>
{
var activity = context.Activity;
var json = JsonSerializer.Deserialize<JsonElement>(JsonSerializer.Serialize(activity));
var submitData = JsonSerializer.Deserialize<Dictionary<string, object>>(
json.GetProperty("value").GetProperty("data").GetRawText());
var submissionType = submitData?.GetValueOrDefault("submissiontype")?.ToString();
if (submissionType == "multi_step_1")
{
var name = submitData["name"]?.ToString();
var step2Card = new AdaptiveCard
{
Body = new List<CardElement>
{
new TextBlock("Step 2 of 2 - Your Email") { Size = TextSize.Large, Weight = TextWeight.Bolder },
new TextInput { Id = "email", Label = "Email", Placeholder = "Enter your email", IsRequired = true }
},
Actions = new List<Action>
{
new SubmitAction().WithTitle("Submit").WithData(
new Union<string, SubmitActionData>(new SubmitActionData
{
NonSchemaProperties = new Dictionary<string, object?>
{
{ "submissiontype", "multi_step_2" },
{ "name", name! }
}
}))
}
};
var taskInfo = new TaskInfo
{
Title = "Multi-step Form: Step 2",
Width = new Union<int, Size>(400),
Height = new Union<int, Size>(300),
Card = new Attachment
{
ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
Content = step2Card
}
};
return new Response(new ContinueTask(taskInfo));
}
if (submissionType == "multi_step_2")
{
await context.Send($"Hi {submitData["name"]}, thanks for submitting! Your email is {submitData["email"]}");
return new Response(new MessageTask("Multi-step form completed!"));
}
var usertext = submitData?.GetValueOrDefault("usertext")?.ToString();
await context.Send($"You submitted: {usertext}");
return new Response(new MessageTask("Thanks for submitting!"));
});
Tastatur- und Barrierefreiheitsrichtlinien
Stellen Sie für URL-basierte Dialoge, die HTML-Inhalte laden, die Barrierefreiheit der Tastatur sicher:
- Verwenden Sie das tabindex-Attribut in Ihren HTML-Tags, um zu steuern, welche Elemente fokussiert werden können, und um die sequenzielle Tastaturnavigation mit den TAB- und UMSCHALT-TAB-Tasten zu definieren.
- Behandeln Sie den ESC-Schlüssel in JavaScript für Ihre Dialogfeldseite entsprechend.
Microsoft Teams stellt sicher, dass die Tastaturnavigation von der Dialogüberschrift in Ihren HTML-Code und umgekehrt ordnungsgemäß funktioniert.
Codebeispiel
| Beispielname | Beschreibung | .NET | Node.js | Python |
|---|---|---|---|---|
| Bottaskmodule | In dieser Beispiel-App wird veranschaulicht, wie Dialoge (in TeamsJS v1.x als Aufgabenmodule bezeichnet) mit dem Teams KI SDK verwendet werden. | View | View | View |