Obtención de datos de usuario con formularios

Anterior: Mostrar contenido de Markdown

Ahora que sabemos cómo presentar contenido básico de Markdown, vamos a probar a mostrar algo más significativo aprovechando la eficacia de Tarjetas adaptables. Esto es útil para crear formularios o para mostrar contenido más complejo.

Trabajar con formularios

Puede crear una tarjeta en la paleta de comandos con la IFormContent interfaz (consulte FormContent para la implementación del kit de herramientas). Esto le permite proporcionar el JSON de tarjeta adaptable y la paleta de comandos la representará automáticamente. Cuando el usuario envíe el formulario, la Paleta de comandos llamará al método SubmitForm en el formulario, con la carga JSON y las entradas del formulario.

1. En el Pages directorio , agregue una nueva clase.
2. Asigne un nombre a la clase FormPage
3. Actualice la FormPage clase :

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

FormPage es una página de contenido que muestra un formulario (SampleContentForm) al usuario. Crea una instancia de , que es un formulario (definido más adelante) que describe la interfaz de usuario y la lógica de un formulario de SampleContentFormentrada de usuario.

1. En la parte inferior del archivo (en la FormPage clase) agregue:

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 contiene el formulario y la lógica de envío de formularios. TemplateJson contiene la estructura y las acciones del formulario. Este ejemplo solo contiene una entrada de texto que tiene el identificador "Name" y tiene una acción de enviar el formulario. El SubmitForm gestiona el análisis de la carga; si es inválida, devolverá el comando a inicio. De lo contrario, mostrará un cuadro de diálogo de confirmación y una notificación emergente.

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

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

1. Implementación de la extensión
2. En la paleta de comandos, Reload

Tarjetas adaptables puede hacer formularios más complejos, incluido el uso de otro objeto json para crear formularios personalizados dinámicamente. Primero configurará el formulario con el Diseñador de tarjetas adaptables y, a continuación, actualizará el comando.

1. Abrir https://adaptivecards.io/designer/
2. Reemplace el contenido de CARD PAYLOAD EDITOR por un json:

{
    "$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. En el SAMPLE DATA EDITOR, reemplace el json por:

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

La herramienta Diseñador debe tener un aspecto similar al siguiente:

Para agregar este contenido a la extensión:

1. Actualizar TemplateJson con el contenido de CARD PAYLOAD EDITOR
2. En TemplateJson, agregue:

        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. Implementación de la extensión
2. En la paleta de comandos, Reload

TemplateJson y DataJson trabajan juntos para crear formularios dinámicos y controlados por datos. TemplateJson puede actuar como plano técnico de formulario y DataJson como origen de contenido dinámico.

Ejemplo completo

Para obtener un ejemplo completo del uso de formularios y páginas de contenido, vaya a SamplePagesExtension/Pages/SampleContentPage.cs.

Elementos clave

• Defina la disposición de su formulario mediante la propiedad TemplateJson de su FormContent. Esta es la carga JSON del EDITOR DE CARGA DE TARJETA en https://adaptivecards.io/designer/. Describe la estructura y la interfaz de usuario del formulario.

• Opcionalmente, enlazar datos dinámicos mediante la DataJson propiedad . Este es el JSON del EDITOR DE DATOS DE EJEMPLO en el Diseñador de tarjetas adaptables. Permite insertar valores dinámicos en la tarjeta con marcadores de posición ${...}, lo que facilita la localización y el mantenimiento de los formularios.

• Controle los envíos de formularios mediante la implementación del SubmitForm método . Se llama a este método cuando el usuario envía el formulario. Recibirá la carga del formulario como una cadena JSON, que puede analizar y usar para desencadenar acciones, mostrar diálogos de confirmación o devolver resultados de navegación.

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

Contenido relacionado

• PowerToys Utilidad de la paleta de comandos
• Visión general de la extensibilidad
• Ejemplos de extensión