Manipulação de eventos do ASP.NET Core Blazor

Este artigo explica os recursos de manipulação de eventos do Blazor, incluindo tipos de argumento de evento, retornos de chamada de evento e gerenciamento de eventos padrão do navegador.

Delegar manipuladores de eventos

Especifique manipuladores de eventos atribuídos na marcação de componente Razor com sintaxe @on{DOM EVENT}="{DELEGATE}"Razor:

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

Para manipulação de evento:

• Os manipuladores de eventos delegados nos Blazor Web Apps só são chamados em componentes que adotam um modo de renderização interativo. Os exemplos deste artigo consideram que o aplicativo adota um modo de renderização interativo globalmente no componente raiz do aplicativo, que costuma ser o componente App. Para obter mais informações, consulte ASP.NET Core Blazor modos de renderização.
• Os manipuladores de eventos assíncronos atribuídos que retornam Task são compatíveis.
• Os manipuladores de eventos atribuídos disparam automaticamente uma renderização da interface do usuário, portanto, não é necessário chamar StateHasChangedmanualmente.
• Todas 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 integrados

Para eventos que são compatíveis a um tipo de argumento de evento, a especificação de um parâmetro de evento na definição do método de evento só será necessária 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}";
}

EventArgs compatíveis são mostrados na tabela a seguir.

evento	Classe	Notas do DOM
Área de Transferência	ClipboardEventArgs
Arrastar	DragEventArgs	DataTransfer e DataTransferItem mantêm os dados do item arrastados. Implemente arrastar e soltar nos aplicativos Blazor usando a interoperabilidade JS com a 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 evento.
Foco	FocusEventArgs	Não inclui suporte para relatedTarget.
Entrada	ChangeEventArgs
Teclado	KeyboardEventArgs
Mouse	MouseEventArgs
Ponteiro do mouse	PointerEventArgs
Botão de rolagem do mouse	WheelEventArgs
Progresso	ProgressEventArgs
Toque	TouchEventArgs	TouchPoint representa um único ponto de contato em um dispositivo sensível ao toque.

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

• Classes EventArgs na fonte de referência ASP.NET Core (branch main dotnet/aspnetcore)

  Observação

  Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira 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 evento.

Argumentos de evento personalizados

O Blazor é compatível com argumentos de evento personalizados, que permitem transmitir dados arbitrários a manipuladores de eventos do .NET com eventos personalizados.

Configuração geral

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

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

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

O parâmetro event é um Evento DOM (documentação do MDN).

Registre o evento personalizado com o manipulador anterior em um inicializador JavaScript. Forneça o nome do evento do navegador apropriado para browserEventName, que, no 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 espaço reservado {PACKAGE ID/ASSEMBLY NAME} é a ID do pacote ou o nome do assembly do aplicativo):

Para um Blazor Web App:

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

Para um aplicativo 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 ( bem letras minúsculas) fornecido pelo evento de início Blazor. Embora o registro seja válido ao usar o objeto Blazor (B maiúsculo), a abordagem preferencial é 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 o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira 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;}
}

Conecte o evento personalizado com os argumentos de evento adicionando uma anotação de atributo [EventHandler]para o evento personalizado:

• Para que o compilador localize a classe [EventHandler], ela deve ser colocada em um arquivo de classe C# (.cs), tornando-a uma classe normal de nível superior.
• 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) em que 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 transmitidos do JavaScript no método de manipulador atribuído:

@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 do JavaScript.

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

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

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

Informe 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 com o manipulador anterior em um inicializador JavaScript. O exemplo a seguir trata apenas da colagem de texto, mas você pode usar APIs de JavaScript arbitrárias para lidar com usuários que colam outros tipos de dados, como imagens.

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

Para um Blazor Web App:

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

Para um aplicativo 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 arquivo representa a ID do pacote ou o nome do assembly do aplicativo.

Observação

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

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

• Gere um evento custompaste.
• Forneça os dados de argumentos de evento usando a lógica personalizada informada:
  • Para eventTimestamp, crie uma nova data.
  • Para 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 de eventos são prefixados com "on".
• No 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

As expressões lambda são compatíveis como manipulador de eventos atribuído.

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

Em geral, é conveniente fechar valores adicionais usando parâmetros de método C#, como ao iterar sobre um conjunto de elementos. O exemplo a seguir cria três botões, cada um dos quais chama UpdateHeading e transmite 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}";
}

A criação de um grande número de delegados de eventos em um loop pode causar baixo desempenho de renderização. Para obter mais informações, confira Melhores Práticas do ASP.NET CoreBlazor.

Evite usar uma variável de loop diretamente em uma expressão lambda, como i no exemplo de loop for anterior. Caso contrário, a mesma variável será usada por todas as expressões lambda, o que resulta no uso do mesmo valor em todos os 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 foreach com Enumerable.Range, que não tem o 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 é a execução de um método em um componente pai quando ocorre um evento em um 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 a um EventCallback do componente filho.

O componente Child a seguir mostra como o manipulador onclick de um botão é configurado para receber um delegado EventCallback de ParentComponent do exemplo. O EventCallback é digitado 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 filho EventCallback<TValue> (OnClickCallback) para seu ShowMessage método.

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 Parent do componente ShowMessage é chamado. message é atualizado e exibido no componente Parent.
• Não é exigida uma chamada para StateHasChanged no método de retorno de chamada (ShowMessage). StateHasChanged é chamado automaticamente para uma nova renderização no componente Parent, assim como eventos filhos acionam uma nova renderização de componente em manipuladores de eventos que são executados no filho. Para saber mais, consulte Renderização de componentes de Razor no ASP.NET Core.

Use EventCallback e EventCallback<TValue> para tratamento de eventos e parâmetros de componente de associação.

Prefira o fortemente tipado EventCallback<TValue> em vez de EventCallback. EventCallback<TValue> fornece comentários de erro aprimorados quando um tipo inadequado é usado, orientando os usuários do componente para a implementação correta. Semelhante a outros manipuladores de eventos de interface do usuário, a especificação do parâmetro de evento é opcional. Use EventCallback quando não houver nenhum valor transmitido para o retorno de chamada.

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

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

await OnClickCallback.InvokeAsync({ARGUMENT});

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

O exemplo a seguir de pai-filho 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íncrona 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, em que o espaço reservado {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 o eventoMDN 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 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;
}

Interromper propagação de eventos

Use o atributo de diretiva @on{DOM EVENT}:stopPropagation para interromper a propagação de eventos no 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 DOM HTML. Os eventos devem se propagar para a raiz DOM HTML antes que Blazor possa agir. Para um mecanismo para impedir a propagação de eventos DOM HTML, leve em conta a seguinte abordagem:

• Obter o caminho do evento chamando Event.composedPath().
• Filtrar eventos com base nos destinos de eventos compostos (EventTarget).

No exemplo a seguir, se você marcar a caixa de seleção, impedirá que eventos de clique de <div> do segundo filho se propaguem para o <div> do pai. Como eventos de clique propagados normalmente disparam o método OnSelectParentDiv, a seleção de <div> do segundo filho resulta na mensagem pai <div> que aparece, a menos que a caixa de seleção esteja selecionada.

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 em um elemento

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