Control de eventos de Blazor en ASP.NET Core

En este artículo se explican las características de control de eventos de Blazor, incluidos los tipos de argumento de evento, las devoluciones de llamadas de eventos y la administración de eventos predeterminados del explorador.

Controladores de eventos delegados

Especifique los controladores de eventos delegados en el marcado del componente Razor con la sintaxis @on{DOM EVENT}="{DELEGATE}"Razor:

• El marcador de posición {DOM EVENT} es un evento de DOM (por ejemplo, click).
• El marcador de posición {DELEGATE} es el controlador de eventos delegado de C#.

Para el control de eventos:

• Se admiten los controladores de eventos delegados asincrónicos que devuelven Task.
• Los controladores de eventos delegados desencadenan una representación de la interfaz de usuario de forma automática, por lo que no es necesario llamar a StateHasChanged manualmente.
• Se registran excepciones.

El código siguiente:

• Llama al método UpdateHeading cuando se selecciona el botón en la interfaz de usuario.
• Llama al método CheckChanged cuando se cambia la casilla en la interfaz de usuario.

EventHandler1.razor:

@page "/event-handler-1"

<PageTitle>Event Handler 1</PageTitle>

<h1>Event Handler Example 1</h1>

<h2>@headingValue</h2>

<p>
    <button @onclick="UpdateHeading">
        Update heading
    </button>
</p>

<p>
    <label>
        <input type="checkbox" @onchange="CheckChanged" />
        @checkedMessage
    </label>
</p>

@code {
    private string headingValue = "Initial heading";
    private string checkedMessage = "Not changed yet";

    private void UpdateHeading()
    {
        headingValue = $"New heading ({DateTime.Now})";
    }

    private void CheckChanged()
    {
        checkedMessage = $"Last changed at {DateTime.Now}";
    }
}

En el ejemplo siguiente, UpdateHeading:

• Se llama de forma asincrónica cuando se selecciona el botón.
• Espera dos segundos antes de actualizar el encabezado.

EventHandler2.razor:

@page "/event-handler-2"

<PageTitle>Event Handler 2</PageTitle>

<h1>Event Handler Example 2</h1>

<h2>@headingValue</h2>

<p>
    <button @onclick="UpdateHeading">
        Update heading
    </button>
</p>

@code {
    private string headingValue = "Initial heading";

    private async Task UpdateHeading()
    {
        await Task.Delay(2000);

        headingValue = $"New heading ({DateTime.Now})";
    }
}

Argumentos de eventos integrados

En el caso de los eventos que admiten un tipo de argumento de evento, solo es necesario especificar un parámetro de evento en la definición del método del evento si se usa el tipo de evento en el método. En el ejemplo siguiente, MouseEventArgs se usa en el método ReportPointerLocation para establecer el texto del mensaje que informa de las coordenadas del mouse cuando el usuario selecciona un botón en la interfaz de usuario.

EventHandler3.razor:

@page "/event-handler-3"

<PageTitle>Event Handler 3</PageTitle>

<h1>Event Handler Example 3</h1>

@for (var i = 0; i < 4; i++)
{
    <p>
        <button @onclick="ReportPointerLocation">
            Where's my mouse pointer for this button?
        </button>
    </p>
}

<p>@mousePointerMessage</p>

@code {
    private string? mousePointerMessage;

    private void ReportPointerLocation(MouseEventArgs e)
    {
        mousePointerMessage = $"Mouse coordinates: {e.ScreenX}:{e.ScreenY}";
    }
}

En la tabla siguiente se muestran los valores EventArgs admitidos.

evento	Clase	Notas de DOM
Portapapeles	ClipboardEventArgs
Arrastrar	DragEventArgs	DataTransfer y DataTransferItem contienen datos de elementos arrastrados. Implemente la función de arrastrar y colocar en las aplicaciones de Blazor mediante la Interoperabilidad de JS con Drag and Drop API en HTML.
Error	ErrorEventArgs
evento	EventArgs	EventHandlers contiene atributos para configurar las asignaciones entre los nombres de evento y los tipos de argumento de evento.
Foco	FocusEventArgs	No incluye compatibilidad con relatedTarget.
Entrada	ChangeEventArgs
Teclado	KeyboardEventArgs
Mouse	MouseEventArgs
Puntero	PointerEventArgs
Rueda del ratón	WheelEventArgs
Progreso	ProgressEventArgs
Tocar	TouchEventArgs	TouchPoint representa un único punto de contacto en un dispositivo sensible al tacto.

Para obtener más información, vea los siguientes recursos:

• Clases EventArgs en el origen de referencia de ASP.NET Core (rama main de dotnet/aspnetcore)

  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).

• EventHandlers contiene atributos para configurar las asignaciones entre los nombres de evento y los tipos de argumento de evento.

Argumentos de eventos personalizados

Blazor admite argumentos de eventos personalizados, que permiten pasar datos arbitrarios a controladores de eventos de .NET con eventos personalizados.

Configuración general

Los eventos personalizados con argumentos de eventos personalizados generalmente se habilitan con los pasos siguientes.

En JavaScript, defina una función para generar el objeto de argumento de evento personalizado a partir del evento de origen:

function eventArgsCreator(event) { 
  return {
    customProperty1: 'any value for property 1',
    customProperty2: event.srcElement.id
  };
}

El event parámetro es un evento DOM (documentación de MDN).

Registre el evento personalizado con el controlador anterior en un inicializador de JavaScript. Proporcione el nombre de evento del explorador apropiado a browserEventName, que para el ejemplo que se muestra en esta sección es click para la selección de un botón en la interfaz de usuario.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js (el marcador de posición {PACKAGE ID/ASSEMBLY NAME} es el identificador de paquete o el nombre del ensamblado de la aplicación):

Para una aplicación web de Blazor:

export function afterWebStarted(blazor) {
  blazor.registerCustomEventType('customevent', {
    browserEventName: 'click',
    createEventArgs: eventArgsCreator
  });
}

Para una aplicación Blazor Server o Blazor WebAssembly:

export function afterStarted(blazor) {
  blazor.registerCustomEventType('customevent', {
    browserEventName: 'click',
    createEventArgs: eventArgsCreator
  });
}

Nota:

La llamada a registerCustomEventType se realiza en un script solo una vez por evento.

Para la llamada a registerCustomEventType, use el parámetro blazor ( bminúsculas) proporcionado por el evento de inicio Blazor. Aunque el registro es válido cuando se usa el objeto Blazor (B mayúsculas), el enfoque preferido es usar el parámetro.

Defina una clase para los argumentos del evento:

namespace BlazorSample.CustomEvents;

public class CustomEventArgs : EventArgs
{
    public string? CustomProperty1 {get; set;}
    public string? CustomProperty2 {get; set;}
}

Conecte el evento personalizado con los argumentos de evento agregando un [EventHandler]atributo de anotación para el evento personalizado:

• Para que el compilador encuentre la clase [EventHandler], debe colocarse en un archivo de clase de C# (.cs), lo que lo convierte en una clase de nivel superior normal.
• Marque la clase public.
• La clase no requiere miembros.
• El compilador debe llamar a la clase "EventHandlers" para que la encuentre el compilador Razor.
• Coloque la clase en un espacio de nombres específico de la aplicación.
• Importe el espacio de nombres en el componente Razor (.razor) donde se usa el evento.

using Microsoft.AspNetCore.Components;

namespace BlazorSample.CustomEvents;

[EventHandler("oncustomevent", typeof(CustomEventArgs),
    enableStopPropagation: true, enablePreventDefault: true)]
public static class EventHandlers
{
}

Registre el controlador de eventos en uno o varios elementos HTML. Acceda a los datos pasados de JavaScript al método de controlador de delegado:

@using BlazorSample.CustomEvents

<button id="buttonId" @oncustomevent="HandleCustomEvent">Handle</button>

@if (!string.IsNullOrEmpty(propVal1) && !string.IsNullOrEmpty(propVal2))
{
    <ul>
        <li>propVal1: @propVal1</li>
        <li>propVal2: @propVal2</li>
    </ul>
}

@code
{
    private string? propVal1;
    private string? propVal2;

    private void HandleCustomEvent(CustomEventArgs eventArgs)
    {
        propVal1 = eventArgs.CustomProperty1;
        propVal2 = eventArgs.CustomProperty2;
    }
}

Si IntelliSense no reconoce el atributo @oncustomevent, asegúrese de que el componente o el archivo _Imports.razor contienen una instrucción @using para el espacio de nombres que contiene la clase EventHandler.

Cada vez que se desencadena el evento personalizado en el DOM, se llama al controlador de eventos con los datos pasados desde JavaScript.

Si se está intentando activar un evento personalizado, bubbles debe habilitarse estableciendo su valor en true. De lo contrario, el evento no llega al controlador de Blazor para su procesamiento en la clase [EventHandler] atributo personalizado de C#. Para obtener más información, vea Creación y activación de eventos (Event), en MDN Web Docs.

Ejemplo de evento de pegado del portapapeles personalizado

En el siguiente ejemplo se recibe un evento de pegado del portapapeles personalizado que incluye la hora de pegado y el texto pegado del usuario.

Declare un nombre personalizado (oncustompaste) para el evento y una clase .NET (CustomPasteEventArgs) para que contenga los argumentos de este evento:

CustomEvents.cs:

using Microsoft.AspNetCore.Components;

namespace BlazorSample.CustomEvents;

[EventHandler("oncustompaste", typeof(CustomPasteEventArgs), 
    enableStopPropagation: true, enablePreventDefault: true)]
public static class EventHandlers
{
}

public class CustomPasteEventArgs : EventArgs
{
    public DateTime EventTimestamp { get; set; }
    public string? PastedData { get; set; }
}

Agregue código JavaScript para proporcionar datos para la subclase EventArgs con el controlador anterior en un inicializador de JavaScript. En el ejemplo siguiente solo se controla el pegado de texto, pero se pueden usar API de JavaScript arbitrarias para tratar con los usuarios que pegan otros tipos de datos, como imágenes.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js:

Para una aplicación web de Blazor:

export function afterWebStarted(blazor) {
  blazor.registerCustomEventType('custompaste', {
    browserEventName: 'paste',
    createEventArgs: event => {
      return {
        eventTimestamp: new Date(),
        pastedData: event.clipboardData.getData('text')
      };
    }
  });
}

Para una aplicación de Blazor Server o Blazor WebAssembly:

export function afterStarted(blazor) {
  blazor.registerCustomEventType('custompaste', {
    browserEventName: 'paste',
    createEventArgs: event => {
      return {
        eventTimestamp: new Date(),
        pastedData: event.clipboardData.getData('text')
      };
    }
  });
}

En el ejemplo anterior, el marcador de posición {PACKAGE ID/ASSEMBLY NAME} del nombre de archivo representa el identificador de paquete o el nombre del ensamblado de la aplicación.

Nota:

Para la llamada a registerCustomEventType, use el parámetro blazor ( bminúsculas) proporcionado por el evento de inicio Blazor. Aunque el registro es válido cuando se usa el objeto Blazor (B mayúsculas), el enfoque preferido es usar el parámetro.

El código anterior, cuando se produce un evento paste nativo, indica al explorador que:

• Genere un evento custompaste.
• Proporcione los datos de los argumentos de eventos mediante la lógica personalizada indicada:
  • Para eventTimestamp, se crea una nueva fecha.
  • Para pastedData, se obtienen los datos del portapapeles como texto. Para obtener más información, consulte ClipboardEvent.clipboardData, en MDN Web Docs.

Las convenciones de los nombres de eventos difieren entre .NET y JavaScript:

• En .NET, los nombres de eventos tienen el prefijo "on".
• En JavaScript, los nombres de eventos no tienen prefijo.

En un componente Razor, asocie el controlador personalizado a un elemento.

CustomPasteArguments.razor:

@page "/custom-paste-arguments"
@using BlazorSample.CustomEvents

<label>
    Try pasting into the following text box:
    <input @oncustompaste="HandleCustomPaste" />
</label>

<p>
    @message
</p>

@code {
    private string? message;

    private void HandleCustomPaste(CustomPasteEventArgs eventArgs)
    {
        message = $"At {eventArgs.EventTimestamp.ToShortTimeString()}, " +
            $"you pasted: {eventArgs.PastedData}";
    }
}

Expresiones lambda

Las expresiones lambda se admiten como controladores de eventos delegados.

EventHandler4.razor:

@page "/event-handler-4"

<PageTitle>Event Handler 4</PageTitle>

<h1>Event Handler Example 4</h1>

<h2>@heading</h2>

<p>
    <button @onclick="@(e => heading = "New heading!!!")">
        Update heading
    </button>
</p>

@code {
    private string heading = "Initial heading";
}

A menudo resulta práctico cerrar los valores adicionales utilizando parámetros de C#, como al recorrer en iteración un conjunto de elementos. En el ejemplo siguiente se crean tres botones, cada uno de los cuales llama a UpdateHeading y pasa los datos siguientes:

• Un argumento de evento (MouseEventArgs) en e.
• El número de botón en buttonNumber.

EventHandler5.razor:

@page "/event-handler-5"

<PageTitle>Event Handler 5</PageTitle>

<h1>Event Handler Example 5</h1>

<h2>@heading</h2>

@for (var i = 1; i < 4; i++)
{
    var buttonNumber = i;

    <p>
        <button @onclick="@(e => UpdateHeading(e, buttonNumber))">
            Button #@i
        </button>
    </p>
}

@code {
    private string heading = "Select a button to learn its position";

    private void UpdateHeading(MouseEventArgs e, int buttonNumber)
    {
        heading = $"Selected #{buttonNumber} at {e.ClientX}:{e.ClientY}";
    }
}

La creación de un gran número de delegados de eventos en un bucle puede provocar un rendimiento de representación deficiente. Para obtener más información, consulte Procedimientos recomendados de rendimiento de Blazor en ASP.NET Core.

No use una variable de bucle directamente en una expresión lambda (como i en el ejemplo de bucle for anterior). de lo contrario, todas las expresiones lambda usarán la misma variable, con lo cual se usará el mismo valor en todas las expresiones lambda. Capture el valor de la variable en una variable local. En el ejemplo anterior:

• La variable de bucle i se asigna a buttonNumber.
• buttonNumber se usa en la expresión lambda.

Como alternativa, utilice un bucle foreach con Enumerable.Range, que no sufre el problema anterior:

@foreach (var buttonNumber in Enumerable.Range(1,3))
{
    <p>
        <button @onclick="@(e => UpdateHeading(e, buttonNumber))">
            Button #@buttonNumber
        </button>
    </p>
}

EventCallback

Un escenario común con componentes anidados consiste en ejecutar un método en un componente primario cuando se produce un evento de componente secundario. Un caso habitual es un evento onclick que se produce en el componente secundario. Para exponer eventos entre componentes, use un elemento EventCallback. Un componente primario puede asignar un método de devolución de llamada al elemento EventCallback de un componente secundario.

El siguiente componente Child indica cómo se configura el controlador onclick de un botón para recibir un elemento EventCallback delegado del elemento ParentComponent de la muestra. El elemento EventCallback se escribe con MouseEventArgs, que es adecuado para un evento onclick relativo a un dispositivo periférico.

Child.razor:

<p>
    <button @onclick="OnClickCallback">
        Trigger a Parent component method
    </button>
</p>

@code {
    [Parameter]
    public string? Title { get; set; }

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    [Parameter]
    public EventCallback<MouseEventArgs> OnClickCallback { get; set; }
}

El componente Parent establece el elemento EventCallback<TValue> (OnClickCallback) del elemento secundario en su método ShowMessage.

ParentChild.razor:

@page "/parent-child"

<PageTitle>Parent Child</PageTitle>

<h1>Parent Child Example</h1>

<Child Title="Panel Title from Parent" OnClickCallback="ShowMessage">
    Content of the child component is supplied by the parent component.
</Child>

<p>@message</p>

@code {
    private string? message;

    private void ShowMessage(MouseEventArgs e)
    {
        message = $"Blaze a new trail with Blazor! ({e.ScreenX}:{e.ScreenY})";
    }
}

Cuando el botón se selecciona en ChildComponent:

• Se llama al método ShowMessage del componente Parent. message se actualiza y se muestra en el componente Parent.
• No se requiere una llamada a StateHasChanged en el método de la devolución de llamada (ShowMessage). Se llama a StateHasChanged de forma automática para volver a representar el componente Parent, del mismo modo que los eventos secundarios desencadenan la nueva representación de los controladores de eventos que se ejecutan dentro del elemento secundario. Para más información, consulte Representación de componentes de Razor de ASP.NET Core.

Use EventCallback y EventCallback<TValue> para el control de eventos y el enlace de parámetros de componentes.

Se prefiere EventCallback<TValue> (fuertemente tipado) a EventCallback. EventCallback<TValue> proporciona comentarios de error mejorados cuando se usa un tipo inapropiado, lo que guía a los usuarios del componente hacia una implementación correcta. Como sucede con otros controladores de eventos de la interfaz de usuario, la especificación del parámetro de evento es opcional. Use EventCallback cuando no se pase ningún valor a la devolución de llamada.

EventCallback y EventCallback<TValue> permiten delegados asincrónicos. EventCallback tiene un establecimiento flexible de tipos y permite pasar cualquier argumento de tipo en InvokeAsync(Object). EventCallback<TValue> tiene un establecimiento inflexible de tipos y requiere pasar un argumento T en InvokeAsync(T) que se puede asignar a TValue.

Invoque EventCallback o EventCallback<TValue> con InvokeAsync y espere a Task:

await OnClickCallback.InvokeAsync({ARGUMENT});

En el ejemplo anterior, el marcador de posición {ARGUMENT} es un argumento opcional.

En el ejemplo primario y secundario siguiente se muestra la técnica.

Child2.razor:

<h3>Child2 Component</h3>

<button @onclick="TriggerEvent">Click Me</button>

@code {
    [Parameter]
    public EventCallback<string> OnClickCallback { get; set; }

    private async Task TriggerEvent()
    {
        await OnClickCallback.InvokeAsync("Blaze It!");
    }
}

ParentChild2.razor:

@page "/parent-child-2"

<PageTitle>Parent Child 2</PageTitle>

<h1>Parent Child 2 Example</h1>

<div>
    <Child2 OnClickCallback="(value) => { message1 = value; }" />
    @message1
</div>

<div>
    <Child2 OnClickCallback=
        "async (value) => { await Task.Delay(2000); message2 = value; }" /> 
    @message2
</div>

@code {
    private string message1 = string.Empty;
    private string message2 = string.Empty;
}

La segunda aparición del componente Child2 muestra una devolución de llamada asincrónica y el nuevo valor message2 se asigna y se representa con un retraso de dos segundos.

Bloqueo de acciones predeterminadas

Use el atributo de directiva @on{DOM EVENT}:preventDefault para evitar la acción predeterminada de un evento, donde el marcador de posición {DOM EVENT} es un evento DOM.

Si se selecciona una tecla en un dispositivo de entrada y el foco del elemento está en un cuadro de texto, un explorador muestra normalmente el carácter de la tecla en el cuadro de texto. En el ejemplo siguiente, el comportamiento predeterminado se evita mediante la especificación del atributo de directiva @onkeydown:preventDefault. Cuando el foco está en el elemento <input>, el contador se incrementa con la secuencia de teclas Mayús++. El carácter + no está asignado al valor del elemento <input>. Para más información sobre keydown, vea Evento MDN Web Docs: Document: keydown.

EventHandler6.razor:

@page "/event-handler-6"

<PageTitle>Event Handler 6</PageTitle>

<h1>Event Handler Example 6</h1>

<p>For this example, give the <code><input></code> focus.</p>

<p>
    <label>
        Count of '+' key presses: 
        <input value="@count" @onkeydown="KeyHandler" @onkeydown:preventDefault />
    </label>
</p>

@code {
    private int count = 0;

    private void KeyHandler(KeyboardEventArgs e)
    {
        if (e.Key == "+")
        {
            count++;
        }
    }
}

Especificar el atributo @on{DOM EVENT}:preventDefault sin un valor es equivalente a @on{DOM EVENT}:preventDefault="true".

Una expresión también es un valor permitido del atributo. En el ejemplo siguiente, shouldPreventDefault es un campo bool establecido en true o false:

<input @onkeydown:preventDefault="shouldPreventDefault" />

...

@code {
    private bool shouldPreventDefault = true;
}

Detención de la propagación de eventos

Use el atributo de directiva @on{DOM EVENT}:stopPropagation para detener la propagación de eventos en el ámbito Blazor. {DOM EVENT} es un marcador de posición para un evento DOM.

El efecto del atributo de directiva stopPropagation se limita al ámbito Blazor y no se extiende al DOM HTML. Los eventos deben propagarse a la raíz DOM HTML antes de que Blazor pueda actuar sobre ellos. Para obtener un mecanismo para evitar la propagación de eventos DOM HTML, considere el enfoque siguiente:

• Obtenga la ruta de acceso del evento llamando a Event.composedPath().
• Filtre los eventos en función de los destinos de eventos compuestos (EventTarget).

En el ejemplo siguiente, al activar la casilla se impide que los eventos de clic del elemento secundario <div> se propaguen al elemento principal <div>. Dado que los eventos de clic propagados normalmente activan el método OnSelectParentDiv, el hecho de seleccionar el segundo elemento secundario <div> hará que se muestre el mensaje <div> primario, a menos que la casilla esté activada.

EventHandler7.razor:

@page "/event-handler-7"

<PageTitle>Event Handler 7</PageTitle>

<h1>Event Handler Example 7</h1>

<div>
    <b>stopPropagation</b>: @stopPropagation
</div>

<div>
    <button @onclick="StopPropagation">
        Stop Propagation (stopPropagation = true)
    </button>
    <button @onclick="EnablePropagation">
        Enable Propagation (stopPropagation = false)
    </button>
</div>

<div class="m-1 p-1 border border-primary" @onclick="OnSelectParentDiv">
    <h3>Parent div</h3>

    <div class="m-1 p-1 border" @onclick="OnSelectChildDiv">
        Child div that never stops propagation to the parent div when 
        selected.
    </div>

    <div class="m-1 p-1 border" @onclick="OnSelectChildDiv" 
            @onclick:stopPropagation="stopPropagation">
        Child div that stops propagation when selected if 
        <b>stopPropagation</b> is <b>true</b>.
    </div>
</div>

<p>
    @message
</p>

@code {
    private bool stopPropagation = false;
    private string? message;

    private void StopPropagation() => stopPropagation = true;

    private void EnablePropagation() => stopPropagation = false;

    private void OnSelectParentDiv() =>
        message = $"The parent div was selected. {DateTime.Now}";

    private void OnSelectChildDiv() =>
        message = $"The child div was selected. {DateTime.Now}";
}

Foco en un elemento

Llame a FocusAsync en una referencia de elemento para centrar el foco en un elemento del código. En el ejemplo siguiente, seleccione el botón para centrar el foco en el elemento <input>.

EventHandler8.razor:

@page "/event-handler-8"

<PageTitle>Event Handler 8</PageTitle>

<h1>Event Handler Example 8</h1>

<p>Select the button to give the <code><input></code> focus.</p>

<p>
    <label>
        Input: 
        <input @ref="exampleInput" />
    </label>
    
</p>

<button @onclick="ChangeFocus">
    Focus the Input Element
</button>

@code {
    private ElementReference exampleInput;

    private async Task ChangeFocus()
    {
        await exampleInput.FocusAsync();
    }
}