Obter a entrada do usuário com formulários

Anterior: Exibir conteúdo de markdown

Agora que sabemos como apresentar conteúdo básico de markdown, vamos tentar exibir algo mais significativo aproveitando o poder de Cartões Adaptáveis. Isso é útil para criar formulários ou para exibir conteúdo mais complexo.

Trabalhando com formulários

Você pode criar um cartão na Paleta de Comandos com a IFormContent interface (consulte FormContent para a implementação do kit de ferramentas). Isso permite que você forneça o JSON do Cartão Adaptável e a Paleta de Comandos o renderizará para você. Quando o usuário envia o formulário, a Paleta de Comandos chamará o método SubmitForm no seu formulário, com a carga útil JSON e as entradas do formulário.

1. Pages No diretório, adicione uma nova classe
2. Nomeie a classe FormPage
3. Atualize a FormPage classe:

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

O FormPage é uma página de conteúdo que exibe um formulário (SampleContentForm) para o usuário. Ele cria uma instância de SampleContentForm, que é um formulário (definido posteriormente) que descreve a interface do usuário e a lógica de um formulário de entrada do usuário.

1. Na parte inferior do arquivo (na FormPage classe) adicione:

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

O SampleContentForm contém o formulário e a lógica de envio de formulário. TemplateJson contém a estrutura e as ações do formulário. Este exemplo contém apenas uma entrada de texto que tem a ID de "Name" e tem uma ação de enviar o formulário. O SubmitForm gerencia a análise do payload; se for inválido, retornará o comando ao estado inicial e, caso contrário, exibirá uma caixa de diálogo de confirmação e uma notificação toast.

1. Abrir <ExtensionName>CommandsProvider.cs
2. Substitua o MarkdownPage por FormPage:

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

1. Implantar sua extensão
2. Na paleta de comandos, Reload

Cartões Adaptáveis podem fazer formulários mais complexos, incluindo o uso de outro objeto json para criar dinamicamente formulários personalizados. Primeiro, você configurará seu formulário com o Designer de Cartão Adaptável e, em seguida, atualizará seu comando.

1. Abrir https://adaptivecards.io/designer/
2. No CARD PAYLOAD EDITOR substitua o JSON por:

{
    "$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. No SAMPLE DATA EDITOR substitua pelo JSON:

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

A ferramenta Designer deve ser semelhante a esta:

Para adicionar esse conteúdo à sua extensão:

1. Atualizar TemplateJson com o conteúdo de CARD PAYLOAD EDITOR
2. Em TemplateJson, adicione:

        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. Implantar sua extensão
2. Na paleta de comandos, Reload

TemplateJson e DataJson trabalhem em conjunto para criar formulários dinâmicos controlados por dados. TemplateJson pode atuar como fhe Form Blueprint e DataJson como a Fonte de Conteúdo Dinâmico.

Exemplo completo

Para obter um exemplo completo de como usar as páginas Formulários e Conteúdo, vá para SamplePagesExtension/Pages/SampleContentPage.cs.

Itens-chave

• Defina o layout do formulário usando a propriedade TemplateJson do seu FormContent. Este é o conteúdo JSON do EDITOR DE CONTEÚDO DE CARTÃO no https://adaptivecards.io/designer/. Ele descreve a estrutura e a UI do formulário.

• Opcionalmente, associe dados dinâmicos usando a DataJson propriedade. Este é o JSON do EDITOR DE DADOS DE EXEMPLO no Designer de Cartões Adaptáveis. Ele permite que você insira valores dinâmicos em seu cartão usando espaços reservados ${...}, tornando seus formulários mais fáceis de localizar e manter.

• Manipule envios de formulário implementando o SubmitForm método. Esse método é chamado quando o usuário envia o formulário. Você receberá o conteúdo do formulário como uma cadeia de caracteres JSON, que pode ser analisada e usada para disparar ações, mostrar caixas de diálogo de confirmação ou retornar resultados de navegação.

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

Conteúdo relacionado

• PowerToys Utilitário paleta de comandos
• Visão geral da extensibilidade
• Exemplos de extensão