Kartenaktionen

Wichtig

Diese Dokumentation gilt als veraltet. Umfassende Informationen und Ressourcen im Zusammenhang mit adaptiven Karten finden Sie im Dokumentationshub für adaptive Karten.

Screenshot: Startseite der Microsoft Adaptive Karten-Website

Der Dokumentationshub für adaptive Karten bietet eine vollständige und aktuelle Referenzdokumentation, eine aktualisierte adaptive Karten-Designer, integrierte JSON-Beispiele, bewährte Entwurfsmethoden und einen detaillierten Releaseverlauf der Features adaptiver Karten. Weitere Informationen finden Sie unter Einführung in den Dokumentationshub für adaptive Karten und neue Updates für adaptive Karten.

Adaptive Karten unterstützen interaktive Elemente über Aktionsschaltflächen, Links und Eingabeübermittlungstrigger, die auf Benutzerinteraktionen reagieren. Sie können diese verwenden, um Formulareingaben zu sammeln, Workflows auszulösen, URLs zu öffnen und vieles mehr.

Das Teams SDK bietet Generatorhilfsprogramme und serverseitige Handler, die das Arbeiten mit Karte Aktionen vereinfachen. Die folgenden Aktionstypen werden unterstützt:

Aktionstyp Anwendungsfall Beschreibung
Action.Execute Serverseitige Verarbeitung Sendet Daten zur Verarbeitung an Ihren Bot. Am besten geeignet für Formulare und mehrstufige Workflows.
Action.Submit Einfache Datenübermittlung Legacyaktionstyp. Bevorzugen Sie Action.Execute neue Projekte.
Action.OpenUrl Externe Navigation Öffnet eine URL im Browser des Benutzers.
Action.ShowCard Progressive Offenlegung Zeigt bei Auswahl eine geschachtelte Karte an.
Action.ToggleVisibility Zustandsverwaltung der Benutzeroberfläche Blendet Karte Elemente dynamisch ein oder aus.

Hinweis

Eine vollständige Referenz zu Aktionstypen finden Sie in der Dokumentation zu adaptiven Karten.

Erstellen von Aktionen mit dem SDK

Das SDK stellt Generatorhilfsprogramme bereit, die den zugrunde liegenden JSON-Code abstrahieren. Sie können Aktionen mit stark typisierten Klassen aus dem Microsoft.Teams.Cards Namespace erstellen.

Action.Execute

Action.Execute ist der empfohlene Aktionstyp für die serverseitige Verarbeitung. Wenn ein Benutzer eine Aktion Ausführen auswählt, werden die Eingabewerte und alle konfigurierten Daten als card.action Aktivität an Ihren Bot gesendet.

Der folgende Code zeigt ein Beispiel für eine Action.Execute Aktion in C#:

using Microsoft.Teams.Cards;

var action = new ExecuteAction
{
    Title = "Submit Feedback",
    Data = new Union<string, SubmitActionData>(new SubmitActionData
    {
        NonSchemaProperties = new Dictionary<string, object?>
        {
            { "action", "submit_feedback" }
        }
    }),
    AssociatedInputs = AssociatedInputs.Auto
};

Action.OpenUrl

Action.OpenUrl öffnet eine angegebene URL im Browser des Benutzers.

Hinweis

Wenn Sie verwenden Action.OpenUrl, stellen Sie sicher, dass Sie die Domäne der Ziel-URL in den validDomains Abschnitt Ihres App-Manifests einschließen. Wenn die Domäne nicht aufgeführt ist, zeigt Teams die Meldungs-URL an, die zu nicht vertrauenswürdigen Inhalten führen kann.

Der folgende Code zeigt ein Beispiel für eine Action.OpenUrl Aktion in C#:

using Microsoft.Teams.Cards;

var action = new OpenUrlAction("https://adaptivecards.microsoft.com")
{
    Title = "Learn More"
};

Aktionssätze

Sie können mehrere Aktionen mithilfe einer adaptiven ActionSet Karte gruppieren:

Der folgende Code zeigt ein Beispiel für Gruppierungsaktionen in C#:

using Microsoft.Teams.Cards;

var card = new AdaptiveCard
{
    Schema = "http://adaptivecards.io/schemas/adaptive-card.json",
    Actions = new List<Microsoft.Teams.Cards.Action>
    {
        new ExecuteAction
        {
            Title = "Submit Feedback",
            Data = new Union<string, SubmitActionData>(new SubmitActionData
            {
                NonSchemaProperties = new Dictionary<string, object?>
                {
                    { "action", "submit_feedback" }
                }
            })
        },
        new OpenUrlAction("https://adaptivecards.microsoft.com")
        {
            Title = "Learn More"
        }
    }
};

Alternative zu unformatiertem JSON

Wenn Sie lieber mit unformatiertem JSON arbeiten möchten, können Sie es in die SDK-Typen deserialisieren:

var actionJson = """
{
  "type": "Action.OpenUrl",
  "url": "https://adaptivecards.microsoft.com",
  "title": "Learn More"
}
""";
var action = OpenUrlAction.Deserialize(actionJson);

Arbeiten mit Eingabewerten

Zuordnen von Daten zu Karten

Sie können eine Karte senden und bestimmte Daten zuordnen lassen. Legen Sie den data Wert fest, der an den Client zurückgesendet werden soll, damit Sie ihn einer bestimmten Entität zuordnen können.

Der folgende Code zeigt ein Beispiel für das Zuordnen von Daten zu Karte Aktionen in C#:

using Microsoft.Teams.Cards;

private static AdaptiveCard CreateProfileCard()
{
    return new AdaptiveCard
    {
        Schema = "http://adaptivecards.io/schemas/adaptive-card.json",
        Body = new List<CardElement>
        {
            new TextBlock("User Profile")
            {
                Weight = TextWeight.Bolder,
                Size = TextSize.Large
            },
            new TextInput
            {
                Id = "name",
                Label = "Name",
                Value = "John Doe"
            },
            new TextInput
            {
                Id = "email",
                Label = "Email",
                Value = "john@contoso.com"
            },
            new ToggleInput("Subscribe to newsletter")
            {
                Id = "subscribe",
                Value = "false"
            }
        },
        Actions = new List<Microsoft.Teams.Cards.Action>
        {
            new ExecuteAction
            {
                Title = "Save",
                Data = new Union<string, SubmitActionData>(new SubmitActionData
                {
                    NonSchemaProperties = new Dictionary<string, object?>
                    {
                        { "action", "save_profile" },
                        { "entity_id", "12345" }
                    }
                }),
                AssociatedInputs = AssociatedInputs.Auto
            }
        }
    };
}

Wenn der Benutzer die Karte übermittelt, empfängt der Handler die Eingabewerte, die mit den Aktionsdaten zusammengeführt werden:

data["action"]      → "save_profile"
data["entity_id"]   → "12345"
data["name"]        → "John Doe"
data["email"]       → "john@contoso.com"
data["subscribe"]   → "true"

Eingabeüberprüfung

Eingabesteuerelemente bieten eine integrierte Überprüfung. Weitere Informationen finden Sie in der Dokumentation zur Eingabeüberprüfung adaptiver Karten.

Der folgende Code zeigt ein Beispiel für die Eingabeüberprüfung in C#:

using Microsoft.Teams.Cards;

private static AdaptiveCard CreateProfileCardWithValidation()
{
    return new AdaptiveCard
    {
        Schema = "http://adaptivecards.io/schemas/adaptive-card.json",
        Body = new List<CardElement>
        {
            new TextBlock("Profile with Validation")
            {
                Weight = TextWeight.Bolder,
                Size = TextSize.Large
            },
            new NumberInput
            {
                Id = "age",
                Label = "Age",
                IsRequired = true,
                Min = 0,
                Max = 120
            },
            new TextInput
            {
                Id = "name",
                Label = "Name",
                IsRequired = true,
                ErrorMessage = "Name is required"
            },
            new TextInput
            {
                Id = "location",
                Label = "Location"
            }
        },
        Actions = new List<Microsoft.Teams.Cards.Action>
        {
            new ExecuteAction
            {
                Title = "Save",
                Data = new Union<string, SubmitActionData>(new SubmitActionData
                {
                    NonSchemaProperties = new Dictionary<string, object?>
                    {
                        { "action", "save_profile" }
                    }
                }),
                AssociatedInputs = AssociatedInputs.Auto
            }
        }
    };
}

Bedingte Aktivierung von Aktionsschaltflächen

Sie können die conditionallyEnabled -Eigenschaft verwenden, um Aktionsschaltflächen zu deaktivieren, bis der Benutzer den Wert von mindestens einer der erforderlichen Eingaben ändert. Diese Eigenschaft kann nur mit Action.Submit - und Action.Execute -Aktionen verwendet werden. Bei einer bedingt aktivierten Schaltfläche werden Aktionen unabhängig von der Eingabe deaktiviert, wenn die isEnabled -Eigenschaft auf falsefestgelegt ist.

So wird die conditionallyEnabled -Eigenschaft definiert:

Eigenschaft Typ Erforderlich Beschreibung
conditionallyEnabled Boolean ✔️ Steuert, ob die Aktion nur aktiviert ist, wenn mindestens eine erforderliche Eingabe vom Benutzer ausgefüllt wurde.

Die folgende Karte Nutzlast zeigt eine bedingt aktivierte Schaltfläche an:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
        {
            "type": "Input.Text",
            "placeholder": "Placeholder text",
            "label": "Required text input",
            "isRequired": true,
            "id": "text"
        },
        {
            "type": "Input.Date",
            "label": "Required date input",
            "isRequired": true,
            "id": "date"
        }
    ],
    "actions": [
        {
            "type": "Action.Execute",
            "title": "Submit",
            "conditionallyEnabled": true
        },
        {
            "type": "Action.Execute",
            "title": "Permanently disabled button",
            "isEnabled": false
        }
    ]
}

Disabled

Screenshot: Adaptive Karte mit deaktivierter Schaltfläche

Enabled

Screenshot: Adaptive Karte mit aktivierter Schaltfläche

Serverhandler

Übermittlungen für universelle Aktionen werden als invoke Aktivitäten mit dem Namen adaptiveCard/actionan Ihren Bot übermittelt. Im Teams SDK werden diese für Ihre App als card.action Aktivitäten angezeigt, die Ihnen Zugriff auf die überprüften Eingabewerte sowie alle data Werte ermöglichen, die Sie so konfiguriert haben, dass sie an Sie zurückgesendet werden.

Verwenden Sie den OnAdaptiveCardAction Handler, um Karte Aktionen zu verarbeiten:

using System.Text.Json;
using Microsoft.Teams.Api.Activities.Invokes.AdaptiveCards;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Annotations;
using Microsoft.Teams.Common.Logging;

//...

teams.OnAdaptiveCardAction(async context =>
{
    var activity = context.Activity;
    context.Log.Info("[CARD_ACTION] Card action received");

    var data = activity.Value?.Action?.Data;

    context.Log.Info($"[CARD_ACTION] Raw data: {JsonSerializer.Serialize(data)}");

    if (data == null)
    {
        context.Log.Error("[CARD_ACTION] No data in card action");
        return new ActionResponse.Message("No data specified") { StatusCode = 400 };
    }

    string? action = data.TryGetValue("action", out var actionObj) ? actionObj?.ToString() : null;

    if (string.IsNullOrEmpty(action))
    {
        context.Log.Error("[CARD_ACTION] No action specified in card data");
        return new ActionResponse.Message("No action specified") { StatusCode = 400 };
    }
    context.Log.Info($"[CARD_ACTION] Processing action: {action}");

    string? GetFormValue(string key)
    {
        if (data.TryGetValue(key, out var val))
        {
            if (val is JsonElement element)
                return element.GetString();
            return val?.ToString();
        }
        return null;
    }

    switch (action)
    {
        case "submit_feedback":
            var feedbackText = GetFormValue("feedback") ?? "No feedback provided";
            await context.Send($"Feedback received: {feedbackText}");
            break;

        case "create_task":
            var title = GetFormValue("title") ?? "Untitled";
            var priority = GetFormValue("priority") ?? "medium";
            var dueDate = GetFormValue("due_date") ?? "No date";
            await context.Send($"Task created!\nTitle: {title}\nPriority: {priority}\nDue: {dueDate}");
            break;

        case "save_profile":
            var name = GetFormValue("name") ?? "Unknown";
            var email = GetFormValue("email") ?? "No email";
            var subscribe = GetFormValue("subscribe") ?? "false";
            await context.Send($"Profile saved!\nName: {name}\nEmail: {email}\nSubscribed: {subscribe}");
            break;

        default:
            context.Log.Error($"[CARD_ACTION] Unknown action: {action}");
            return new ActionResponse.Message("Unknown action") { StatusCode = 400 };
    }

    return new ActionResponse.Message("Action processed successfully") { StatusCode = 200 };
});

Hinweis

Die data Werte stammen aus JSON und müssen mithilfe der oben gezeigten Hilfsmethode extrahiert werden, um verschiedene JSON-Elementtypen zu verarbeiten.

End-to-End-Beispiel: Aufgabenformular Karte

Das folgende Beispiel zeigt eine vollständige Karte mit Eingabefeldern und einem Aktionshandler.

Erstellen des Karte

using Microsoft.Teams.Cards;

private static AdaptiveCard CreateTaskFormCard()
{
    return new AdaptiveCard
    {
        Schema = "http://adaptivecards.io/schemas/adaptive-card.json",
        Body = new List<CardElement>
        {
            new TextBlock("Create New Task")
            {
                Weight = TextWeight.Bolder,
                Size = TextSize.Large
            },
            new TextInput
            {
                Id = "title",
                Label = "Task Title",
                Placeholder = "Enter task title"
            },
            new TextInput
            {
                Id = "description",
                Label = "Description",
                Placeholder = "Enter task details",
                IsMultiline = true
            },
            new ChoiceSetInput
            {
                Id = "priority",
                Label = "Priority",
                Value = "medium",
                Choices = new List<Choice>
                {
                    new() { Title = "High", Value = "high" },
                    new() { Title = "Medium", Value = "medium" },
                    new() { Title = "Low", Value = "low" }
                }
            },
            new DateInput
            {
                Id = "due_date",
                Label = "Due Date",
                Value = DateTime.Now.ToString("yyyy-MM-dd")
            }
        },
        Actions = new List<Microsoft.Teams.Cards.Action>
        {
            new ExecuteAction
            {
                Title = "Create Task",
                Data = new Union<string, SubmitActionData>(new SubmitActionData
                {
                    NonSchemaProperties = new Dictionary<string, object?>
                    {
                        { "action", "create_task" }
                    }
                }),
                AssociatedInputs = AssociatedInputs.Auto,
                Style = ActionStyle.Positive
            }
        }
    };
}

Senden des Karte

teams.OnMessage(async context =>
{
    var text = context.Activity.Text?.ToLowerInvariant() ?? "";

    if (text.Contains("form"))
    {
        await context.Typing();
        var card = CreateTaskFormCard();
        await context.Send(card);
    }
});

Codebeispiele

S.No. Karte Beschreibung .NET Node.js Python Java Manifest
1 Adaptive Kartenaktionen In diesem Beispiel wird gezeigt, wie Adaptive Karten mit mehreren Aktionstypen mithilfe eines Teams-Bots gesendet werden. View View View – –
2 Verwenden von Karten Stellt alle Karte-Typen vor, einschließlich Miniaturansichten, Audio, Medien usw. Baut auf Begrüßung von Benutzer und Bot mit mehreren Eingabeaufforderungen auf, indem ein Karte mit Schaltflächen in der Willkommensnachricht präsentiert wird, die an das entsprechende Dialogfeld weitergeleitet werden. View View View – –
3 Adaptive Karten Veranschaulicht, wie das Dialogfeld mit mehreren Durchläufen eine Karte verwenden kann, um Benutzereingaben für Name und Alter abzurufen. View View View – –
4 Kartenformatierung In diesem Beispiel wird eine Schaltfläche mit bedingter Aktivierung veranschaulicht. View View – – –

Nächster Schritt

Erstellen adaptiver Karten

Siehe auch

  • Last updated on