Benutzereingaben mit Formularen erfassen

Zurück: Anzeigen von Markdowninhalten

Nachdem wir nun wissen, wie Sie grundlegende Markdowninhalte präsentieren, versuchen wir, etwas aussagekräftiger anzuzeigen, indem wir die Leistungsfähigkeit von Adaptive Karten nutzen. Dies ist nützlich zum Erstellen von Formularen oder zum Anzeigen komplexerer Inhalte.

Arbeiten mit Formularen

Sie können eine Karte in der Befehlspalette mit der IFormContent Schnittstelle erstellen (siehe FormContent für die Toolkitimplementierung). Auf diese Weise können Sie den JSON-Code für adaptive Karten bereitstellen, der von der Befehlspalette gerendert wird. Wenn der Benutzer das Formular sendet, ruft die Befehlspalette die SubmitForm Methode auf Ihrem Formular mit den JSON-Daten und den Eingaben aus dem Formular auf.

1. Fügen Sie im Pages Verzeichnis eine neue Klasse hinzu.
2. Benennen der Klasse FormPage
3. Aktualisieren Sie die FormPage Klasse:

internal sealed partial class FormPage : ContentPage
{
    private readonly SampleContentForm sampleForm = new();

    public override IContent[] GetContent() => [sampleForm];

    public FormPage()
    {
        Name = "Open";
        Title = "Sample Content";
        Icon = new IconInfo("\uECA5"); // Tiles
    }
}

Die FormPage ist eine Inhaltsseite, die dem Benutzer ein Formular (SampleContentForm) anzeigt. Es erstellt eine Instanz von SampleContentForm, bei der es sich um ein Formular (später definiert) handelt, das die Benutzeroberfläche und Logik für ein Benutzereingabeformular beschreibt.

1. Fügen Sie unten in der Datei (unter der FormPage Klasse) Folgendes hinzu:

internal sealed partial class SampleContentForm : FormContent
{
    public SampleContentForm()
    {
        TemplateJson = $$"""
{
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.6",
    "body": [
        {
            "type": "TextBlock",
            "size": "medium",
            "weight": "bolder",
            "text": " Sample",
            "horizontalAlignment": "center",
            "wrap": true,
            "style": "heading"
        },
        {
            "type": "Input.Text",
            "label": "Name",
            "style": "text",
            "id": "SimpleVal",
            "isRequired": true,
            "errorMessage": "Name is required",
            "placeholder": "Enter your name"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit",
            "data": {
                "id": "1234567890"
            }
        }
    ]
}
""";

    }

    public override CommandResult SubmitForm(string payload)
    {
        var formInput = JsonNode.Parse(payload)?.AsObject();
        Debug.WriteLine($"Form submitted with formInput: {formInput}");
        if (formInput == null)
        {
            return CommandResult.GoHome();
        }
        ConfirmationArgs confirmArgs = new()
        {
            PrimaryCommand = new AnonymousCommand(
                () =>
                {
                    string? name = formInput["Name"]?.ToString();
                    ToastStatusMessage t = new($"Hi {name}" ?? "No name entered");
                    t.Show();
                })
            {
                Name = "Confirm",
                 Result = CommandResult.KeepOpen(),
            },
            Title = "You can set a title for the dialog",
            Description = "Are you really sure you want to do the thing?",
        };
        return CommandResult.Confirm(confirmArgs);
    }
}

SampleContentForm enthält die Formular- und die Übermittlungslogik des Formulars. Das TemplateJson enthält die Formularstruktur und -aktionen. Dieses Beispiel enthält nur eine Texteingabe mit der ID "Name" und eine Aktion zum Senden des Formulars. Die SubmitForm verarbeitet das Analysieren der Nutzlast. Wenn sie ungültig ist, wird der Befehl an die Startseite zurückgegeben, andernfalls wird ein Bestätigungsdialogfeld und eine Toast-Benachrichtigung angezeigt.

1. <ExtensionName>CommandsProvider.cs öffnen
2. Ersetzen Sie MarkdownPage durch FormPage.

public <ExtensionName>CommandsProvider()
{
    DisplayName = "My sample extension";
    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
    _commands = [
+       new CommandItem(new FormPage()) { Title = DisplayName },
    ];
}

1. Stellen Sie Ihre Erweiterung bereit
2. In der Befehlspalette, Reload

Adaptive Karten können komplexere Formulare ausführen, einschließlich der Verwendung eines anderen JSON-Objekts zum dynamischen Erstellen von benutzerdefinierten Formularen. Sie richten ihr Formular zuerst mit dem Designer für adaptive Karten ein und aktualisieren dann ihren Befehl.

1. https://adaptivecards.io/designer/ öffnen
2. Ersetzen Sie im CARD PAYLOAD EDITOR den JSON-Code durch:

{
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.6",
    "body": [
        {
            "type": "TextBlock",
            "size": "medium",
            "weight": "bolder",
            "text": " ${ParticipantInfoForm.title}",
            "horizontalAlignment": "center",
            "wrap": true,
            "style": "heading"
        },
        {
            "type": "Input.Text",
            "label": "Name",
            "style": "text",
            "id": "Name",
            "isRequired": true,
            "errorMessage": "Name is required",
            "placeholder": "Enter your name"
        },
        {
            "type": "TextBlock",
            "size": "medium",
            "weight": "bolder",
            "text": "${Survey.title} ",
            "horizontalAlignment": "center",
            "wrap": true,
            "style": "heading"
        },
        {
            "type": "Input.Toggle",
            "label": "Please accept the terms and conditions:",
            "title": "${Survey.questions[0].question}",
            "valueOn": "true",
            "valueOff": "false",
            "id": "AcceptsTerms",
            "isRequired": true,
            "errorMessage": "Accepting the terms and conditions is required"
        },
        {
            "type": "Input.Toggle",
            "label": "How do you feel about red cars?",
            "title": "${Survey.questions[1].question}",
            "valueOn": "RedCars",
            "valueOff": "NotRedCars",
            "id": "ColorPreference"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit",
            "data": {
                "id": "1234567890"
            }
        }
    ]
}

1. Im SAMPLE DATA EDITOR ersetzen Sie den JSON-Code durch:

{
    "ParticipantInfoForm": {
        "title": "Input.Text elements"
    },
    "Survey": {
        "title": "Input Toggle",
        "questions": [
            {
                "question": "I accept the terms and conditions (True/False)"
            },
            {
                "question": "Red cars are better than other cars"
            }
        ]
    }
}

Das Designertool sollte etwa wie folgt aussehen:

So fügen Sie diese Inhalte zu Ihrer Erweiterung hinzu:

1. Aktuellisiere TemplateJson mit CARD PAYLOAD EDITOR Inhalt
2. Unter TemplateJson hinzufügen:

        DataJson = $$"""
{
    "ParticipantInfoForm": {
        "title": "Input.Text elements"
    },
    "Survey": {
        "title": "Input Toggle",
        "questions": [
            {
                "question": "I accept the terms and conditions (True/False)"
            },
            {
                "question": "Red cars are better than other cars"
            }
        ]
    }
}
""";

1. Stellen Sie Ihre Erweiterung bereit
2. In der Befehlspalette, Reload

TemplateJson und DataJson zusammenarbeiten, um dynamische, datengesteuerte Formulare zu erstellen. TemplateJson kann als fhe Form Blueprint und DataJson als dynamische Inhaltsquelle fungieren.

Vollständiges Beispiel

Ein vollständiges Beispiel für die Verwendung von Formularen und Inhaltsseiten finden Sie weiter.SamplePagesExtension/Pages/SampleContentPage.cs

Wichtige Elemente

• Definieren Sie das Formularlayout mithilfe der TemplateJson-Eigenschaft Ihrer FormContent. Dies ist die JSON-Nutzlast aus dem CARD PAYLOAD EDITOR in dem https://adaptivecards.io/designer/. Es beschreibt die Struktur und Benutzeroberfläche Ihres Formulars.

• Binden Sie optional dynamische Daten mithilfe der DataJson Eigenschaft. Dies ist der JSON-Code aus dem SAMPLE DATA EDITOR im Designer für adaptive Karten. Sie können dynamische Werte mithilfe von ${...}-Platzhaltern in Ihre Karte einfügen, wodurch Ihre Formulare einfacher lokalisiert und verwaltet werden können.

• Behandeln Sie Formularübermittlungen, indem Sie die SubmitForm Methode implementieren. Diese Methode wird aufgerufen, wenn der Benutzer das Formular sendet. Sie erhalten die Nutzlast des Formulars als JSON-Zeichenfolge, die Sie analysieren und verwenden können, um Aktionen auszulösen, Bestätigungsdialogen anzuzeigen oder Navigationsergebnisse zurückzugeben.

public override CommandResult SubmitForm(string payload)
{
    var formInput = JsonNode.Parse(payload)?.AsObject();
    if (formInput == null)
    {
        return CommandResult.GoHome();
    }

    // retrieve the value of the input field with the id "name"
    var name = formInput["name"]?.AsString();
        
    // do something with the data

    // and eventually
    return CommandResult.GoBack();
}

Verwandte Inhalte

• PowerToys Befehlspalette-Tool
• Übersicht über die Erweiterbarkeit
• Erweiterungsbeispiele