Pobieranie danych wejściowych użytkownika za pomocą formularzy

Poprzedni: Wyświetlanie zawartości markdown

Teraz, gdy wiemy, jak przedstawić podstawową zawartość markdown, spróbujmy wyświetlić coś bardziej znaczącego, wykorzystując możliwości kart adaptacyjnych. Jest to przydatne w przypadku tworzenia formularzy lub wyświetlania bardziej złożonej zawartości.

Praca z formularzami

Możesz utworzyć kartę w palecie poleceń za pomocą interfejsu IFormContent (zobacz FormContent dla implementacji zestawu narzędzi). Dzięki temu można podać JSON dla karty adaptacyjnej, a paleta poleceń je wyrenderuje. Gdy użytkownik prześle formularz, Paleta Poleceń wywoła metodę SubmitForm w odniesieniu do twojego formularza, wraz z ładunkiem JSON i danymi wejściowymi z formularza.

1. Pages W katalogu dodaj nową klasę
2. Nadaj klasie nazwę FormPage
3. Zaktualizuj klasę FormPage :

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
    }
}

Strona Formularza to strona zawartości, która wyświetla użytkownikowi formularz (SampleContentForm). Tworzy instancję SampleContentForm, która jest formularzem (zdefiniowanym później) opisującym interfejs użytkownika i logikę formularza wejściowego użytkownika.

1. W dolnej części pliku (pod klasą FormPage ) dodaj:

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

Zawiera SampleContentForm formularz i logikę przesyłania formularzy. Element TemplateJson zawiera strukturę formularza i działania. Ten przykład zawiera tylko jedno wprowadzanie tekstu, które ma identyfikator "Name" i ma jedną akcję przesyłania formularza. SubmitForm zajmuje się przetwarzaniem ładunku. Jeśli jest on nieprawidłowy, zwróci polecenie do źródła, a w przeciwnym razie wyświetli okno dialogowe potwierdzenia i powiadomienie typu toast.

1. Otwórz <ExtensionName>CommandsProvider.cs
2. Zamień MarkdownPage na FormPage.

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

1. Wdrażanie rozszerzenia
2. W palecie poleceń, Reload

Karty adaptacyjne mogą wykonywać bardziej złożone formularze, w tym przy użyciu innego obiektu json w celu dynamicznego tworzenia formularzy niestandardowych. Najpierw skonfigurujesz formularz za pomocą projektanta kart adaptacyjnych , a następnie zaktualizujesz polecenie.

1. Otwórz https://adaptivecards.io/designer/
2. W CARD PAYLOAD EDITOR zamień JSON na:

{
    "$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. W SAMPLE DATA EDITOR zastąp zawartość JSON następująco:

{
    "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"
            }
        ]
    }
}

Narzędzie Projektant powinno wyglądać mniej więcej tak:

Aby dodać tę zawartość do rozszerzenia:

1. Zaktualizuj TemplateJson przy użyciu zawartości CARD PAYLOAD EDITOR
2. W obszarze TemplateJsondodaj:

        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. Wdrażanie rozszerzenia
2. W palecie poleceń, Reload

TemplateJson i DataJson współpracują ze sobą w celu tworzenia dynamicznych formularzy opartych na danych. TemplateJson może działać jako szablon formularza, a DataJson jako źródło zawartości dynamicznej.

Pełny przykład

Aby uzyskać pełny przykład użycia stron formularzy i zawartości, przejdź do strony SamplePagesExtension/Pages/SampleContentPage.cs.

Kluczowe elementy

• Ustaw układ formularza przy użyciu właściwości TemplateJson swojej FormContent. Jest to ładunek JSON z EDYTORA ŁADUNKU KARTY w pliku https://adaptivecards.io/designer/. Opisuje strukturę i interfejs użytkownika formularza.

• Opcjonalnie powiąż dane dynamiczne przy użyciu DataJson właściwości . Jest to kod JSON z EDYTORA PRZYKŁADOWYCH DANYCH w Projektancie kart adaptacyjnych. Umożliwia ona wprowadzanie wartości dynamicznych do karty przy użyciu symboli zastępczych ${...}, co ułatwia lokalizowanie i konserwację formularzy.

• Obsługa przesyłania formularzy przez zaimplementowanie metody SubmitForm. Ta metoda jest wywoływana, gdy użytkownik prześle formularz. Ładunek formularza otrzymasz jako ciąg JSON, który można przeanalizować i użyć do wyzwalania akcji, wyświetlania okien dialogowych potwierdzenia lub zwracania wyników nawigacji.

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

Treści powiązane

• PowerToys Narzędzie Paleta poleceń
• Omówienie rozszerzalności
• Przykłady rozszerzeń