Información general de formularios de ASP.NET Core Blazor

En este artículo se explica cómo usar formularios en Blazor.

Componentes y formularios de entrada

El marco de Blazor admite formularios y proporciona componentes de entrada integrados:

• Enlazado a un objeto o modelo que puede usar anotaciones de datos
  • Formularios HTML con el elemento <form>
  • Componentes EditForm
• Componentes de entrada integrados

El espacio de nombres Microsoft.AspNetCore.Components.Forms proporciona:

• Clases para administrar elementos de formulario, estado y validación.
• Acceso a componentes de Input* integrados.

Un proyecto creado a partir de la plantilla de proyecto Blazor incluye el espacio de nombres de forma predeterminada en el archivo _Imports.razor de la aplicación, lo que hace que el espacio de nombres esté disponible para los componentes de Razor de la aplicación.

Se admiten formularios HTML estándar. Cree un formulario con la etiqueta HTML normal <form> y especifique un controlador de @onsubmit para controlar la solicitud de formulario enviada.

StarshipPlainForm.razor:

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

En el componente StarshipPlainForm anterior:

• El formulario se representa donde aparece el elemento <form>. El formulario recibe el nombre del atributo de directiva @formname, que identifica de forma única el formulario en el marco de trabajo Blazor.
• El modelo se crea en el bloque @code del componente y se conserva en una propiedad pública (Model). El atributo [SupplyParameterFromForm] indica que el valor de la propiedad asociada debe proporcionarse a partir de los datos del formulario. Los datos de la solicitud que coinciden con el nombre de la propiedad están vinculados a la propiedad.
• El componente InputText es un componente de entrada para editar valores de cadena. El atributo de directiva @bind-Value enlaza la propiedad del modelo Model.Id a la propiedad Value del componente InputText.
• El método Submit se registra como controlador para la devolución de llamada @onsubmit. Se llama al controlador cuando el usuario envía el formulario.

Importante

Use siempre el atributo de directiva @formname con un nombre de formulario único.

Blazor mejora la navegación de páginas y el control de formularios mediante la interceptación de la solicitud para aplicar la respuesta al DOM existente, conservando la mayor parte del formulario representado como sea posible. La mejora evita la necesidad de cargar completamente la página y proporciona una experiencia de usuario mucho más fluida, similar a una aplicación de página única (SPA), aunque el componente se representa en el servidor. Para más información, vea Enrutamiento y navegación de Blazor de ASP.NET Core.

La representación en streaming es compatible con formularios HTML simples.

Nota:

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

El ejemplo anterior incluye soporte antifalsificación mediante la inclusión de un componente de AntiforgeryToken en el formulario. El soporte antifalsificación se explica con más detalle en la sección Soporte antifalsificación de este artículo.

Para enviar un formulario basado en los eventos DOM de otro elemento, por ejemplo oninput o onblur, utilice JavaScript para enviar el formulario (submit(documentación MDN)).

En lugar de usar formularios simples en las aplicaciones Blazor, un formulario generalmente se define con el soporte de formulario integrado de Blazor usando el componente del marco EditForm. El componente siguiente Razor muestra elementos típicos, componentes y código Razor para representar un formulario web mediante un componente EditForm.

Starship1.razor:

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

En el componente Starship1 anterior:

• El componente EditForm se representa donde aparezca el elemento <EditForm>. El formulario recibe el nombre del atributo de directiva @formname, que identifica de forma única el formulario en el marco de trabajo Blazor.
• El modelo se crea en el bloque @code del componente y se conserva en una propiedad pública (Model). La propiedad se asigna al parámetro EditForm.Model. El atributo [SupplyParameterFromForm] indica que el valor de la propiedad asociada debe proporcionarse a partir de los datos del formulario. Los datos de la solicitud que coinciden con el nombre de la propiedad están vinculados a la propiedad.
• El componente InputText es un componente de entrada para editar valores de cadena. El atributo de directiva @bind-Value enlaza la propiedad del modelo Model.Id a la propiedad Value del componente InputText.
• El método Submit se registra como controlador para la devolución de llamada OnSubmit. Se llama al controlador cuando el usuario envía el formulario.

Importante

Use siempre el atributo de directiva @formname con un nombre de formulario único.

Blazor mejora la navegación de páginas y el control de formularios para los componentes EditForm. Para más información, vea Enrutamiento y navegación de Blazor de ASP.NET Core.

La representación en streaming es compatible con EditForm.

Nota:

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

†Para más información sobre el enlace de propiedades, vea Enlace de datos Blazor de ASP.NET Core.

En el ejemplo siguiente, se modifica el componente anterior para crear el formulario en el componente Starship2:

• OnSubmit se reemplaza por OnValidSubmit, que procesa el controlador de eventos asignado si el formulario es válido cuando el usuario lo envía.
• Se agrega un componente ValidationSummary para mostrar mensajes de validación cuando el formulario no es válido en el envío del formulario.
• El validador de anotaciones de datos (componente† DataAnnotationsValidator) expone la compatibilidad con la validación mediante anotaciones de datos:
  • Si el campo de formulario <input> se deja en blanco cuando se selecciona el botón Submit, aparece un error en el resumen de validación (componente‡ ValidationSummary) ("The Id field is required.") y se llama a Submit.
  • Si el campo de formulario <input> contiene más de diez caracteres cuando se selecciona el botón Submit, aparece un error en el resumen de validación ("Id is too long."). Submitno se llama.
  • Si el campo de formulario <input> contiene un valor válido cuando se selecciona el botón Submit, se llama a Submit.

†El componente DataAnnotationsValidator se trata en la sección Componentes de validador. ‡El componente ValidationSummary se trata en la sección Resumen de validación y componentes de los mensajes de validación.

Starship2.razor:

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

Control del envío de formularios

El componente EditForm proporciona las siguientes devoluciones de llamada para controlar el envío de formularios:

• Use OnValidSubmit para asignar un controlador de eventos que se ejecute cuando se envía un formulario con campos válidos.
• Use OnInvalidSubmit para asignar un controlador de eventos que se ejecute cuando se envía un formulario con campos no válidos.
• Use OnSubmit para asignar un controlador de eventos que se ejecute independientemente del estado de validación de los campos de formulario. El formulario se valida mediante una llamada a EditContext.Validate en el método de controlador de eventos. Si Validate devuelve true, el formulario es válido.

Borrar un formulario o campo

Restablezca un formulario borrando su modelo y llevándolo de nuevo a su estado predeterminado, lo que se puede realizar dentro o fuera de un marcado de EditForm:

<button @onclick="ClearForm">Clear form</button>

...

private void ClearForm() => Model = new();

Como alternativa, use una expresión explícita Razor:

<button @onclick="@(() => Model = new())">Clear form</button>

Restablezca un campo borrando su valor de modelo y llevándolo a su estado predeterminado:

<button @onclick="ResetId">Reset Identifier</button>

...

private void ResetId() => Model!.Id = string.Empty;

Como alternativa, use una expresión explícita Razor:

<button @onclick="@(() => Model!.Id = string.Empty)">Reset Identifier</button>

No es necesario llamar a StateHasChanged en los ejemplos anteriores porque el marco Blazor llama automáticamente a StateHasChanged para volver a representar el componente después de invocar un controlador de eventos. Si no se usa un controlador de eventos para invocar los métodos que borran un formulario o campo, el código de desarrollador debe llamar a StateHasChanged para volver a representar el componente.

Compatibilidad con antiforgería

Los servicios antifalsificación se agregan automáticamente a las aplicaciones Blazor cuando se llama a AddRazorComponents en el archivo Program.

La aplicación usa el middleware antifalsificación llamando a UseAntiforgery en su canalización de procesamiento de solicitudes en el archivo Program. UseAntiforgery se llama después de la llamada a UseRouting. Si hay llamadas a UseRouting y UseEndpoints, la llamada a UseAntiforgery debe ir entre ellas. Se debe realizar una llamada a UseAntiforgery después de las llamadas a UseAuthentication y UseAuthorization.

El componente AntiforgeryToken representa un token antiforgería como un campo oculto y el atributo [RequireAntiforgeryToken] habilita la protección antiforgería. Si se produce un error en una comprobación antiforgería, se produce una respuesta 400 - Bad Request y no se procesa el formulario.

En el caso de los formularios basados en EditForm, el componente AntiforgeryToken y el atributo [RequireAntiforgeryToken] se agregan automáticamente para proporcionar protección antiforgería de forma predeterminada.

Para formularios basados en el elemento HTML <form>, agregue manualmente el componente AntiforgeryToken al formulario:

<form method="post" @onsubmit="Submit" @formname="starshipForm">
    <AntiforgeryToken />
    <input id="send" type="submit" value="Send" />
</form>

@if (submitted)
{
    <p>Form submitted!</p>
}

@code{
    private bool submitted = false;

    private void Submit() => submitted = true;
}

Advertencia

Para los formularios basados en EditForm o en el elemento <form> de HTML, se puede deshabilitar la protección antiforgería pasando required: false al atributo [RequireAntiforgeryToken] . En el ejemplo siguiente se deshabilita la antiforgería y no se recomienda para las aplicaciones públicas:

@using Microsoft.AspNetCore.Antiforgery
@attribute [RequireAntiforgeryToken(required: false)]

Para obtener más información, consulte Autenticación y autorización Blazor de ASP.NET Core.

Control mejorado de formularios

Mejore la navegación para solicitudes POST de formularios con el parámetro Enhance para formularios EditForm o el atributo data-enhance para formularios HTML (<form>):

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

❌No admitido: No se puede establecer la navegación mejorada en el elemento antepasado de un formulario para habilitar el control mejorado de formularios.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Los envíos de formularios mejorados solo funcionan con Blazor puntos de conexión. La publicación de un formulario mejorado en un noBlazor punto de conexión produce un error.

Para deshabilitar el control mejorado de formularios:

• Para un EditForm, elimine el parámetro Enhance del elemento del formulario (o configúrelo a false: Enhance="false").
• Para un HTML <form>, elimine el atributo data-enhance del elemento formulario (o configúrelo a false: data-enhance="false").

Blazor navegación mejorada y el control de formularios pueden deshacer cambios dinámicos en el DOM si el contenido actualizado no forma parte de la renderización del servidor. Para conservar el contenido de un elemento, utilice el atributo data-permanent.

En el siguiente ejemplo, el contenido del elemento <div> se actualiza dinámicamente mediante un script cuando se carga la página:

<div data-permanent>
    ...
</div>

Para deshabilitar la navegación mejorada y la administración de formularios de forma global, consulte Inicio de BlazorASP.NET Core.

Para obtener orientación sobre el uso del event enhancedloado para escuchar actualizaciones de páginas mejoradas, consulte Enrutamiento y navegación de ASP.NET Core Blazor.

Ejemplos

Los ejemplos no adoptan la administración de formularios mejorada para las solicitudes POST de formularios, pero todos los ejemplos pueden actualizarse para adoptar las funciones mejoradas siguiendo las instrucciones de la sección Control mejorado de formularios.

Para demostrar cómo funcionan los formularios con anotaciones de datos validación, los componentes de ejemplo se basan en la API de System.ComponentModel.DataAnnotations. Si desea evitar una línea de código adicional en componentes que usan anotaciones de datos, haga que el espacio de nombres esté disponible en todos los componentes de la aplicación con el archivo de importaciones (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Ejemplos de formulario hacen referencia a aspectos del universo de Star Trek . Star Trek está protegido por copyright ©1966-2023 de CBS Studios y Paramount.

Recursos adicionales

• Cargas de archivos de Blazor en ASP.NET Core
• Repositorio de GitHub con ejemplos de Blazor (dotnet/blazor-samples) (cómo descargar)
• El repositorio GitHub de ASP.NET Core (dotnet/aspnetcore) forma recursos de pruebas