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 erläutert, wie Sie Dialogfelder (früher als Aufgabenmodule bezeichnet) mithilfe des Teams SDK (Teams KI-Bibliothek) aufrufen und schließen. Im Teams SDK werden Dialogfelder aus adaptiven Kartenaktionen mithilfe des TaskFetchAction Dialogs aufgerufen und über Dialogereignisse zum Öffnen und Senden von Ereignissen für den App Kurs behandelt.
Die Veranstaltungsanmeldung variiert je nach Sprache:
-
TypeScript:
app.on('dialog.open', ...)undapp.on('dialog.submit', ...) -
C#:
teams.OnTaskFetch(...)undteams.OnTaskSubmit(...) -
Python:
@app.on_dialog_openund@app.on_dialog_submit
Der Dialoginhalt kann eine adaptive Karte oder eine URL-basierte Webseite sein.
Dialogfelder können je nach App-Architektur auch über andere Ansätze aufgerufen werden:
- Von Registerkarten mit der TeamsJS-Clientbibliothek. Weitere Informationen findest du unter Verwenden von Dialogfeldern in Registerkarten.
- Von Bots, die Bot Framework oder Deep Links verwenden. Weitere Informationen finden Sie unter Verwenden von Dialogfeldern mit Bots.
- Aus einer Deep-Link-URL. Siehe Deep Link zum Öffnen eines Dialogfelds.
Migrationsleitfaden von Bot Framework zum Teams SDK finden Sie unter Migrieren von BotBuilder.
In der folgenden Tabelle wird zusammengefasst, wie Dialoge im Teams SDK funktionieren:
| Schritt | Dialogfeld mit adaptiver Karte | Dialog 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 Aufgabenabrufaufruf 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 Aufgabenabrufaufruf an Ihre App. |
| Behandeln des Ereignisses "Dialog öffnen" | 3. Geben Sie in Ihrem geöffneten Dialoghandler eine Antwort zum Fortsetzen des Aufgabenmoduls zurück, die Dialogmetadaten (Titel, Dimensionen und die anzuzeigende adaptive Karte) enthält. In C# mit einem ContinueTask Wrapper verwendenTaskInfo. Verwenden Sie CardTaskModuleTaskInfoin TypeScript . Verwenden Sie CardTaskModuleTaskInfo in Python innerhalb einer TaskModuleContinueResponse. |
3. Geben Sie in Ihrem dialogoffenen Handler eine Aufgabenmodul-Continue-Antwort 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 einer TaskModuleContinueResponse. |
| Behandeln der Dialogübermittlung | 4. Wenn der Benutzer eine Action.Submit Schaltfläche drückt, sendet Teams einen Aufgabenübermittlungsaufruf mit den Formulardaten an Ihre App. 5. Sie können wie folgt reagieren: • 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 Aufgabenübermittlungsaufruf mit dem Ergebnis an Ihre App. |
Im nächsten Abschnitt werden die Metadaten des Dialogs beschrieben, die den Inhalt und die Darstellung eines Dialogfelds definieren.
Dialogfeldmetadaten
Die Dialogmetadaten definieren den Inhalt und das Erscheinungsbild eines Dialogs. Jede Sprache verwendet ihre eigenen Typen, um diese Metadaten darzustellen:
-
C#:
TaskInfo(fromMicrosoft.Teams.Api.TaskModules) -
TypeScript:
CardTaskModuleTaskInfoorUrlTaskModuleTaskInfo(from@microsoft/teams.api) -
Python:
CardTaskModuleTaskInfoorUrlTaskModuleTaskInfo(frommicrosoft_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 Pixeln darstellt, oder small, mediumoder large. Verwenden Sie Union<int, Size>in C# . |
width |
Zahl oder Zeichenfolge | Dieses Attribut kann eine Zahl sein, die die Breite des Dialogfelds in Pixeln darstellt, oder small, medium, oder large. Verwenden Sie Union<int, Size>in C# . |
url |
string | Die URL der Seite, die innerhalb des Dialogfelds <iframe> geladen wurde. Die Domäne der URL muss sich im validDomains-Array der App in Ihrem App-Manifest befinden. Verwenden Sie UrlTaskModuleTaskInfo es 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 mit TaskInfo einer .Attachment Verwenden Sie cardAttachment() in TypeScript mit CardTaskModuleTaskInfo. In Python verwenden Sie card_attachment(AdaptiveCardAttachment(...)) mit CardTaskModuleTaskInfo. |
Hinweis
Das Dialogfeature 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 Dialoggröße angegeben, mit der der Benutzer die Höhe und Breite des Dialogfelds festlegen kann.
Dialoggröße
Die Werte und widthheight legen Sie 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 unter Beibehaltung des Seitenverhältnisses proportional reduziert werden.
Wenn width und height sind small, medium, oder large, ist die Größe des roten Rechtecks in der folgenden Abbildung ein 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 Dialogfeldern 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 Aufgabenabruf-Invoke an Ihre App. Die value Daten jeder Schaltfläche geben den Typ des zu öffnenden Dialogfelds an (z. B { "data": "AdaptiveCard" }. ).
using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Schema;
using Microsoft.Teams.Cards;
teams.OnMessage(async (context, cancellationToken) =>
{
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" }
}
};
TeamsAttachment attachment = TeamsAttachment.CreateBuilder()
.WithAdaptiveCard(JsonSerializer.SerializeToElement(card))
.Build();
await context.SendAsync(new MessageActivityInput().AddAttachment(attachment), cancellationToken);
});
Behandeln des Ereignisses "Dialog öffnen"
Wenn Teams einen Aufgabenabrufaufruf 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 Metadaten des Dialogfelds in eine ContinueTask Antwort. Gib in TypeScript einen mit TaskModuleResponsetype: 'continue'zurück. Gib in Python eine zurück, die InvokeResponse einen TaskModuleContinueResponse.
using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Schema;
using Microsoft.Teams.Apps.TaskModules;
using Microsoft.Teams.Cards;
teams.OnTaskFetch(async (context, cancellationToken) =>
{
await Task.CompletedTask;
// The button's Action.Submit payload arrives on the invoke value, nested under "data".
string? data = context.Activity.Value?.Data is JsonElement value
&& value.TryGetProperty("data", out JsonElement dataProp)
? dataProp.GetString()
: null;
if (data == "CustomForm")
{
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Continue)
.WithTitle("Custom Form")
.WithWidth(510)
.WithHeight(450)
.WithUrl($"{botEndpoint}/customform")
.WithFallbackUrl($"{botEndpoint}/customform")
.Build();
}
if (data == "MultiStep")
{
var step1Card = new AdaptiveCard
{
Version = "1.5",
Body = new List<CardElement>
{
new TextBlock("Multi-step Form: Step 1") { Wrap = true },
new TextInput { Id = "name", Label = "Name" }
},
Actions = new List<Microsoft.Teams.Cards.Action>
{
new SubmitAction { Title = "Next" }
}
};
TeamsAttachment step1Attachment = TeamsAttachment.CreateBuilder()
.WithAdaptiveCard(JsonSerializer.SerializeToElement(step1Card))
.Build();
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Continue)
.WithTitle("Multi-step Form")
.WithWidth(400)
.WithHeight(300)
.WithCard(step1Attachment)
.Build();
}
var dialogCard = new AdaptiveCard
{
Version = "1.5",
Body = new List<CardElement>
{
new TextInput { Id = "usertext", Label = "Enter text" }
},
Actions = new List<Microsoft.Teams.Cards.Action>
{
new SubmitAction { Title = "Submit" }
}
};
TeamsAttachment attachment = TeamsAttachment.CreateBuilder()
.WithAdaptiveCard(JsonSerializer.SerializeToElement(dialogCard))
.Build();
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Continue)
.WithTitle("Adaptive Card: Inputs")
.WithWidth(400)
.WithHeight(200)
.WithCard(attachment)
.Build();
});
Behandeln der Dialogübermittlung
Wenn ein Benutzer in einem Dialogfeld drückt Action.Submit , sendet Teams einen Aufgabenübermittlungsaufruf an Ihre App. Sie können antworten, indem Sie die Aufgabe abschließen, eine Nachricht anzeigen oder ein weiteres Dialogfeld öffnen (z. B. um mehrstufige Formulare zu verknüpfen).
using System.Text.Json;
using Microsoft.Teams.Apps.TaskModules;
using Microsoft.Teams.Cards;
teams.OnTaskSubmit(async (context, cancellationToken) =>
{
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! }
}
}))
}
};
TeamsAttachment step2Attachment = TeamsAttachment.CreateBuilder()
.WithAdaptiveCard(JsonSerializer.SerializeToElement(step2Card))
.Build();
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Continue)
.WithTitle("Multi-step Form: Step 2")
.WithWidth(400)
.WithHeight(300)
.WithCard(step2Attachment)
.Build();
}
if (submissionType == "multi_step_2")
{
await context.SendAsync($"Hi {submitData["name"]}, thanks for submitting! Your email is {submitData["email"]}", cancellationToken);
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("Multi-step form completed!")
.Build();
}
var usertext = submitData?.GetValueOrDefault("usertext")?.ToString();
await context.SendAsync($"You submitted: {usertext}", cancellationToken);
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("Thanks for submitting!")
.Build();
});
Richtlinien für Tastaturnavigation und Barrierefreiheit
Stellen Sie bei URL-basierten Dialogfeldern, die HTML-Inhalte laden, die Barrierefreiheit über die 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 die Esc-Taste im JavaScript für Ihre Dialogseite entsprechend.
Microsoft Teams stellt sicher, dass die Tastaturnavigation vom Dialogheader in Ihren HTML-Code und umgekehrt ordnungsgemäß funktioniert.
Codebeispiel
| Beispielname | Beschreibung | .NET | Node.js | Python |
|---|---|---|---|---|
| Bot-Aufgabenmodule | Diese Beispiel-App veranschaulicht, wie Dialogfelder (in TeamsJS v1.x als Aufgabenmodule bezeichnet) mithilfe des Teams KI SDK verwendet werden. | View | View | View |