ASP.NET Core Blazor - gestão de eventos

Este artigo explica as funcionalidades de manipulação de eventos do Blazor, incluindo tipos de argumento de evento, callbacks de eventos e gestão de eventos padrão do navegador.

Delegar manipuladores de eventos

Especifique manipuladores de eventos delegados na marcação de componentes Razor utilizando a sintaxe @on{DOM EVENT}="{DELEGATE}"Razor.

• O marcador {DOM EVENT} é um evento DOM (por exemplo, click).
• O espaço reservado {DELEGATE} é o manipulador de eventos de delegado C#.

Para manipulação de eventos:

• Os manipuladores de eventos delegados em Blazor Web Apps são chamados apenas em componentes que adotam um modo de renderização interativo. Os exemplos ao longo deste artigo pressupõem que o aplicativo adota um modo de renderização interativo globalmente no componente raiz do aplicativo, normalmente o componente App. Para obter mais informações, consulte modos de renderização do ASP.NET Core Blazor.
• Os manipuladores de eventos delegados assíncronos que retornam um Task (async Task) são suportados por Blazor e adotados nos exemplos de documentação de Blazor Web App e Blazor WebAssembly.
• Os manipuladores de eventos delegados acionam automaticamente uma renderização da interface do usuário, portanto, não há necessidade de chamar manualmente StateHasChanged.
• As exceções são registradas.

O seguinte código:

• Chama o método UpdateHeading quando o botão é selecionado na interface do usuário.
• Chama o método CheckChanged quando a caixa de seleção é alterada na interface do usuário.

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 change {DateTime.Now}";
}

No exemplo a seguir, UpdateHeading:

• É chamado de forma assíncrona quando o botão é selecionado.
• Aguarda dois segundos antes de atualizar o título.

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 evento internos

Para eventos que suportam um tipo de argumento de evento, especificar um parâmetro de evento na definição de método de evento só é necessário se o tipo de evento for usado no método. No exemplo a seguir, MouseEventArgs é usado no método ReportPointerLocation para definir o texto da mensagem que relata as coordenadas do mouse quando o usuário seleciona um botão na interface do usuário.

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

Os EventArgs suportados são mostrados na tabela a seguir.

Evento	Classe	Notas DOM
Área de transferência	ClipboardEventArgs
Arraste	DragEventArgs	DataTransfer e DataTransferItem contêm os dados do item arrastado. Implemente o recurso de arrastar e soltar em aplicativos Blazor usando JS de interoperabilidade com API de arrastar e soltar HTML.
Erro	ErrorEventArgs
Evento	EventArgs	EventHandlers contém atributos para configurar os mapeamentos entre nomes de eventos e tipos de argumento de eventos.
Foco	FocusEventArgs	Não inclui suporte para relatedTarget.
Entrada	ChangeEventArgs
Teclado	KeyboardEventArgs
Rato	MouseEventArgs
Ponteiro do rato	PointerEventArgs
Roda do mouse	WheelEventArgs
Progressos	ProgressEventArgs
Toque	TouchEventArgs	TouchPoint representa um único ponto de contacto num dispositivo sensível ao toque.

Para obter mais informações, consulte os seguintes recursos:

• EventArgs classes na fonte de referência do ASP.NET Core (ramificação dotnet/aspnetcore main)

  Observação

  Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

• EventHandlers contém atributos para configurar os mapeamentos entre nomes de eventos e tipos de argumento de eventos.

Argumentos de evento personalizados

Blazor oferece suporte a argumentos de evento personalizados, que permitem que você passe dados arbitrários para manipuladores de eventos .NET com eventos personalizados.

Configuração geral

Eventos personalizados com argumentos de evento personalizados geralmente são habilitados com as etapas a seguir.

Em JavaScript, defina uma função para criar o objeto de argumento de evento personalizado a partir do evento de origem:

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

O parâmetro event é um DOM Event.

Registre o evento personalizado com o manipulador anterior em um inicializador JavaScript . Forneça o nome apropriado do evento do navegador para browserEventName, que, para o exemplo mostrado nesta seção, é click para uma seleção de botão na interface do usuário.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js (o marcador {PACKAGE ID/ASSEMBLY NAME} é a ID do pacote ou o nome do assembly da aplicação):

Para uma Blazor Web App:

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

Para uma aplicação Blazor Server ou Blazor WebAssembly:

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

A chamada para registerCustomEventType é executada em um script apenas uma vez por evento.

Para a chamada para registerCustomEventType, use o parâmetro blazor (letra minúscula b) fornecido pelo evento de início Blazor. Embora o registro seja válido ao usar o objeto Blazor (maiúsculas B), a abordagem preferida é usar o parâmetro.

O nome do evento personalizado, customevent no exemplo anterior, não deve corresponder a um nome de evento Blazor reservado. Os nomes reservados podem ser encontrados na fonte de referência da estrutura Blazor (consulte as chamadas para a função registerBuiltInEventType).

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Defina uma classe para os argumentos de evento:

namespace BlazorSample.CustomEvents;

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

Associe o evento personalizado aos argumentos do evento adicionando uma anotação de atributo [EventHandler] ao evento personalizado.

• Para que o compilador encontre a classe [EventHandler], ela deve ser colocada em um arquivo de classe C# (.cs), tornando-a uma classe de nível superior normal.
• Marque a classe public.
• A classe não requer membros.
• A classe deve ser chamada de "EventHandlers" para ser encontrada pelo compilador Razor.
• Coloque a classe em um namespace específico para seu aplicativo.
• Importe o namespace para o componente Razor (.razor) onde o evento é usado.

using Microsoft.AspNetCore.Components;

namespace BlazorSample.CustomEvents;

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

Registre o manipulador de eventos em um ou mais elementos HTML. Acesse os dados que foram passados do JavaScript no método do manipulador 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;
    }
}

Se o atributo @oncustomevent não for reconhecido pelo IntelliSense, verifique se o componente ou o arquivo _Imports.razor contém uma instrução @using para o namespace que contém a classe EventHandler.

Sempre que o evento personalizado é acionado no DOM, o manipulador de eventos é chamado com os dados transmitidos pelo JavaScript.

Se você estiver tentando disparar um evento personalizado, bubbles deverá ser habilitado definindo seu valor como true. Caso contrário, o evento não alcançará o manipulador de Blazor para processamento na classe atributo personalizado de[EventHandler] do C#. Para obter mais informações, consulte MDN Web Docs: Event borbulhando.

Exemplo de evento de colagem personalizada da área de transferência

O exemplo a seguir recebe um evento de colagem personalizado da área de transferência que inclui a hora em que a colagem ocorre e o texto colado do usuário.

Declare um nome personalizado (oncustompaste) para o evento e uma classe .NET (CustomPasteEventArgs) para manter os argumentos de evento para 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; }
}

Adicione código JavaScript para fornecer dados para a subclasse EventArgs usando o controlador anterior num inicializador JavaScript . O exemplo a seguir lida apenas com a colagem de texto, mas você pode usar APIs JavaScript arbitrárias para lidar com usuários colando outros tipos de dados, como imagens.

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

Para uma Blazor Web App:

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

Para uma aplicação Blazor Server ou Blazor WebAssembly:

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

No exemplo anterior, o espaço reservado {PACKAGE ID/ASSEMBLY NAME} do nome do ficheiro representa a ID do pacote ou o nome do assembly da aplicação.

Observação

Para a chamada de registerCustomEventType, use o parâmetro blazor (em minúsculas b) fornecido pelo evento de início Blazor. Embora o registro seja válido ao usar o objeto Blazor (maiúsculas B), a abordagem preferida é usar o parâmetro.

O código anterior informa ao navegador que, quando ocorre um evento paste nativo:

• Levante um evento custompaste.
• Forneça os dados de argumentos de evento usando a lógica personalizada indicada:
  • Para o eventTimestamp, crie uma nova data.
  • Para o pastedData, obtenha os dados da área de transferência como texto. Para obter mais informações, consulte MDN Web Docs: ClipboardEvent.clipboardData.

As convenções de nome de evento diferem entre .NET e JavaScript:

• No .NET, os nomes dos eventos são prefixados com "on".
• Em JavaScript, os nomes de eventos não têm um prefixo.

Em um componente Razor, anexe o manipulador personalizado a um 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}";
    }
}

Expressões lambda

expressões do Lambda são suportadas como manipulador de eventos delegado.

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

Muitas vezes é conveniente usar parâmetros de método C# para fechar valores adicionais, como quando se itera sobre um conjunto de elementos. O exemplo a seguir cria três botões, cada um dos quais chama UpdateHeading e passa os seguintes dados:

• Um argumento de evento (MouseEventArgs) em e.
• O número do botão em 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}";
}

Criar um grande número de delegados de eventos em um loop pode causar um desempenho de renderização insatisfatório. Para obter mais informações, consulte ASP.NET Core Blazor práticas recomendadas de desempenho.

Evite usar uma variável de loop diretamente em uma expressão lambda, como i no exemplo de loop de for anterior. Caso contrário, a mesma variável é usada por todas as expressões lambda, o que resulta no uso do mesmo valor em todas as lambdas. Capture o valor da variável em uma variável local. No exemplo anterior:

• A variável de loop i é atribuída a buttonNumber.
• buttonNumber é usado na expressão lambda.

Como alternativa, use um loop de foreach com Enumerable.Range, que não sofre do problema anterior:

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

EventCallback

Um cenário comum com componentes aninhados é executar um método no componente pai quando ocorre um evento no componente filho. Um evento onclick que ocorre no componente filho é um caso de uso comum. Para expor eventos entre componentes, use um EventCallback. Um componente pai pode atribuir um método de retorno de chamada ao EventCallbackde um componente filho.

O componente Child a seguir demonstra como o manipulador de um botão onclick é configurado para receber um delegado EventCallback do ParentComponentdo exemplo. O EventCallback é escrito com MouseEventArgs, que é apropriado para um evento onclick de um 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; }
}

O componente pai define o EventCallback<TValue> da criança (OnClickCallback) para seu 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})";
}

Quando o botão é selecionado no ChildComponent:

• O método ShowMessage do componente Parent é chamado. message é atualizado e exibido no componente Parent.
• Uma chamada para StateHasChanged não é necessária na função de callback (ShowMessage). StateHasChanged é chamado automaticamente para renderizar novamente o componente Parent, assim como os eventos filho acionam a rerenderização do componente em manipuladores de eventos que são executados dentro do filho. Para obter mais informações, consulte renderização de componentes do ASP.NET CoreRazor.

Use EventCallback e EventCallback<TValue> para manipulação de eventos e parâmetros de componentes de ligação.

Prefira o EventCallback<TValue> fortemente tipado em vez de EventCallback. EventCallback<TValue> fornece feedback de erro aprimorado quando um tipo inadequado é usado, orientando os usuários do componente para a implementação correta. Semelhante a outros manipuladores de eventos da interface do usuário, especificar o parâmetro de evento é opcional. Use EventCallback caso não seja passado nenhum valor para o callback.

EventCallback e EventCallback<TValue> permitem delegados assíncronos. EventCallback é digitado fracamente e permite passar qualquer argumento de tipo em InvokeAsync(Object). EventCallback<TValue> é fortemente tipado e requer passar um argumento T em InvokeAsync(T) que seja atribuível a TValue.

Invoque um EventCallback ou EventCallback<TValue> com InvokeAsync e aguarde o Task:

await OnClickCallback.InvokeAsync({ARGUMENT});

No exemplo anterior, o espaço reservado {ARGUMENT} é um argumento opcional.

O exemplo pai-filho a seguir demonstra a 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;
}

A segunda ocorrência do componente Child2 demonstra um retorno de chamada assíncrono e o novo valor message2 é atribuído e renderizado com um atraso de dois segundos.

Impedir ações padrão

Use o atributo de diretiva @on{DOM EVENT}:preventDefault para impedir a ação padrão de um evento, onde o marcador {DOM EVENT} é um evento DOM .

Quando uma chave é selecionada em um dispositivo de entrada e o foco do elemento está em uma caixa de texto, um navegador normalmente exibe o caractere da chave na caixa de texto. No exemplo a seguir, o comportamento padrão é impedido especificando o atributo de diretiva @onkeydown:preventDefault. Quando o foco está no elemento <input>, o contador aumenta com a sequência de teclas Shift++. O caractere + não é atribuído ao valor do elemento <input>. Para obter mais informações sobre keydown, consulte MDN Web Docs: Document: keydown evento.

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 o atributo @on{DOM EVENT}:preventDefault sem um valor é equivalente a @on{DOM EVENT}:preventDefault="true".

Uma expressão também é um valor permitido do atributo. No exemplo a seguir, shouldPreventDefault é um campo bool definido como true ou false:

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

...

@code {
    private bool shouldPreventDefault = true;
}

Parar a propagação de eventos

Use o atributo @on{DOM EVENT}:stopPropagation directive para interromper a propagação de eventos dentro do escopo Blazor. {DOM EVENT} é um espaço reservado para um evento DOM .

O efeito do atributo de diretiva stopPropagation é limitado ao escopo Blazor e não se estende ao HTML DOM. Os eventos devem se propagar para a raiz HTML DOM antes que Blazor possa agir sobre eles. Para obter um mecanismo para impedir a propagação de eventos HTML DOM, considere a seguinte abordagem:

• Obtenha o caminho do evento chamando Event.composedPath().
• Filtre eventos com base nos alvos de eventos compostos (EventTarget).

No exemplo a seguir, marcar a caixa de seleção impede que eventos de clique do segundo <div> filho se propaguem para o <div>pai. Como os eventos de clique propagados normalmente disparam o método OnSelectParentDiv, ao selecionar o segundo filho <div>, a mensagem do pai <div> aparece, a menos que a caixa de seleção esteja marcada.

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

Focar um elemento

Chame FocusAsync em um elemento de referência para focar um elemento no código. No exemplo a seguir, selecione o botão para focar o 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();
    }
}