ASP.NET Core Blazor händelsehantering

Den här artikeln beskriver Blazorfunktioner för händelsehantering, inklusive typer av händelseargument, återanrop av händelser och hantering av standardwebbläsare.

Delegera händelsehanterare

Ange delegerade händelsehanterare i Razor komponentmarkering med @on{DOM EVENT}="{DELEGATE}"Razor syntax:

• Platshållaren {DOM EVENT} är en DOM-händelse (till exempel click).
• Platshållaren {DELEGATE} är C#-delegerad händelsehanterare.

För händelsehantering:

• Delegera händelsehanterare i Blazor Web Apps anropas endast i komponenter som använder ett interaktivt återgivningsläge. Exemplen i den här artikeln förutsätter att appen använder ett interaktivt återgivningsläge globalt i appens rotkomponent, vanligtvis den App komponenten. Mer information finns i ASP.NET Core Blazor återgivningslägen.
• Asynkrona delegerade händelsehanterare som returnerar en Task (async Task) stöds av Blazor och används av dokumentationsexempel från Blazor Web App och Blazor WebAssembly.
• Händelsehanterare som använder delegering utlöser automatiskt en UI-rendering, så du behöver inte anropa StateHasChangedmanuellt.
• Undantag loggas.

Följande kod:

• Anropar metoden UpdateHeading när knappen väljs i användargränssnittet.
• Anropar metoden CheckChanged när kryssrutan ändras i användargränssnittet.

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

I följande exempel UpdateHeading:

• Anropas asynkront när knappen väljs.
• Väntar två sekunder innan rubriken uppdateras.

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

Inbyggda händelseargument

För händelser som stöder en händelseargumenttyp är det bara nödvändigt att ange en händelseparameter i händelsemetoddefinitionen om händelsetypen används i metoden. I följande exempel används MouseEventArgs i metoden ReportPointerLocation för att ange meddelandetext som rapporterar muskoordinaterna när användaren väljer en knapp i användargränssnittet.

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

Stödda EventArgs visas i följande tabell.

Evenemang	Klass	DOM-anteckningar
Urklipp	ClipboardEventArgs
Dra	DragEventArgs	DataTransfer och DataTransferItem innehåller data för dragna objekt. Implementera dra-och-släpp i Blazor-appar med JS interop med HTML-dra-och-släpp-API.
Fel	ErrorEventArgs
Evenemang	EventArgs	EventHandlers innehåller attribut för att konfigurera mappningarna mellan händelsenamn och händelseargumenttyper.
Fokus	FocusEventArgs	Innehåller inte stöd för relatedTarget.
Indata	ChangeEventArgs
Tangentbord	KeyboardEventArgs
Mus	MouseEventArgs
Muspekaren	PointerEventArgs
Musrull	WheelEventArgs
Framsteg	ProgressEventArgs
Beröring	TouchEventArgs	TouchPoint representerar en enda kontaktpunkt på en beröringskänslig enhet.

Mer information finns i följande resurser:

• EventArgs klasser i referenskällan ASP.NET Core (dotnet/aspnetcore main branch)

  Anmärkning

  Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

• EventHandlers innehåller attribut för att konfigurera mappningarna mellan händelsenamn och händelseargumenttyper.

Argument för anpassad händelse

Blazor stöder anpassade händelseargument som gör att du kan skicka godtyckliga data till .NET-händelsehanterare med anpassade händelser.

Allmän konfiguration

Anpassade händelser med anpassade händelseargument aktiveras vanligtvis med följande steg.

I JavaScript definierar du en funktion för att skapa det anpassade händelseargumentobjektet från källhändelsen:

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

Parametern event är en DOM-händelse.

Registrera den anpassade händelsen med föregående händelsehanterare i en JavaScript-initialisator. Ange lämpligt webbläsarhändelsenamn för browserEventName, som för det exempel som visas i det här avsnittet är click för en knappmarkering i användargränssnittet.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js (platshållaren för {PACKAGE ID/ASSEMBLY NAME} är appens paket-ID eller sammansättningsnamn):

För en Blazor Web App:

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

För en Blazor Server- eller Blazor WebAssembly-app:

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

Anropet till registerCustomEventType utförs bara i ett skript en gång per händelse.

För anropet till registerCustomEventTypeanvänder du parametern blazor (i gemener b) som tillhandahålls av starthändelsen Blazor. Även om registreringen är giltig när du använder Blazor-objektet (versaler B), är den bästa metoden att använda parametern.

Det anpassade händelsenamnet, customevent i föregående exempel, får inte matcha ett reserverat Blazor händelsenamn. De reserverade namnen finns i referenskällan Blazor framework (se anropen till funktionen registerBuiltInEventType).

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Definiera en klass för händelseargumenten:

namespace BlazorSample.CustomEvents;

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

Koppla ihop den anpassade händelsen med händelseargumenten genom att lägga till en [EventHandler]-attribut-anmerkning för den anpassade händelsen:

• För att kompilatorn ska kunna hitta klassen [EventHandler] måste den placeras i en C#-klassfil (.cs), vilket gör den till en normal toppnivåklass.
• Markera klassen public.
• Klassen kräver inte medlemmar.
• Klassen måste kallas "EventHandlers" för att kunna hittas av Razor kompilatorn.
• Placera klassen under ett namnområde som är specifikt för din app.
• Importera namnområdet till den Razor komponent (.razor) där händelsen används.

using Microsoft.AspNetCore.Components;

namespace BlazorSample.CustomEvents;

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

Registrera händelsehanteraren på ett eller flera HTML-element. Få åtkomst till de data som skickades från JavaScript i ombudshanterarmetoden:

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

Om attributet @oncustomevent inte känns igen av IntelliSensekontrollerar du att komponenten eller filen _Imports.razor innehåller en @using-instruktion för namnområdet som innehåller klassen EventHandler.

När den anpassade händelsen utlöses på DOM anropas händelsehanteraren med data som skickas från JavaScript.

Om du försöker utlösa en anpassad händelse måste bubbles aktiveras genom att värdet anges till true. Annars når händelsen inte Blazor-hanteraren för bearbetning till det anpassade C#-[EventHandler]-attributet-klassen. Mer information finns i MDN Web Docs: Event bubbling.

Exempel på klistra in-händelse för anpassat urklipp

I följande exempel hanteras en anpassad inklistringshändelse för urklipp som inkluderar tiden för inklistringen och den text som användaren har klistrat in.

Deklarera ett anpassat namn (oncustompaste) för händelsen och en .NET-klass (CustomPasteEventArgs) för att lagra händelseargumenten för den här händelsen:

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

Lägg till JavaScript-kod för att ange data för EventArgs-underklassen med föregående hanterare i en JavaScript-initierare. I följande exempel hanteras endast klistrad text, men du kan använda godtyckliga JavaScript-API:er för att hantera användare som klistrar in andra typer av data, till exempel bilder.

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

För en Blazor Web App:

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

För en Blazor Server- eller Blazor WebAssembly-app:

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

I föregående exempel representerar {PACKAGE ID/ASSEMBLY NAME} platshållare för filnamnet paket-ID:t eller sammansättningsnamnet för appen.

Anmärkning

För anropet till registerCustomEventTypeanvänder du parametern blazor (gemener b) som tillhandahålls av starthändelsen Blazor. Även om registreringen är giltig när du använder Blazor-objektet (versaler B), är den föredragna metoden att använda parametern.

Föregående kod anger för webbläsaren att när en intern paste händelse inträffar:

• Skapa en custompaste händelse.
• Ange data för händelseargument med den anpassade logiken som anges:
  • För eventTimestampskapar du ett nytt datum.
  • Hämta urklippsdata som text för pastedData. Mer information finns i MDN Web Docs: ClipboardEvent.ClipboardData.

Konventionerna för händelsenamn skiljer sig mellan .NET och JavaScript:

• I .NET prefixas händelsenamn med "on".
• I JavaScript har händelsenamn inte något prefix.

Koppla den anpassade hanteraren till ett element i en Razor komponent.

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

Lambda-uttryck

Lambda-uttryck stöds som delegerad händelsehanterare.

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

Det är ofta praktiskt att stänga över ytterligare värden med hjälp av C#-metodparametrar, till exempel när du itererar över en uppsättning element. I följande exempel skapas tre knappar som var och en anropar UpdateHeading och skickar följande data:

• Ett händelseargument (MouseEventArgs) i e.
• Knappnumret på 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}";
}

Att skapa ett stort antal händelsedelegater i en loop kan orsaka dåliga renderingsprestanda. För mer information, se bästa praxis för prestanda i ASP.NET Core Blazor.

Undvik att använda en loopvariabel direkt i ett lambda-uttryck, till exempel i i föregående for loopexempel. I annat fall används samma variabel av alla lambda-uttryck, vilket resulterar i användning av samma värde i alla lambdas. Avbilda variabelns värde i en lokal variabel. I föregående exempel:

• Loopvariabeln i tilldelas till buttonNumber.
• buttonNumber används i lambda-uttrycket.

Du kan också använda en foreach-loop med Enumerable.Range, som inte lider av föregående problem:

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

EventCallback

Ett vanligt scenario med kapslade komponenter är att köra en metod i en överordnad komponent när en underordnad komponenthändelse inträffar. En onclick händelse som inträffar i den underordnade komponenten är ett vanligt användningsfall. Om du vill exponera händelser mellan komponenter använder du en EventCallback. En överordnad komponent kan koppla en återanropsmetod till en underordnad komponents EventCallback.

Följande Child-komponent demonstrerar hur en knapps onclick-hanterare konfigureras för att ta emot en EventCallback delegate från exempel ParentComponent. EventCallback skrivs med MouseEventArgs, vilket är lämpligt för en onclick händelse från en kringutrustningsenhet.

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

Den överordnade komponenten anger den underordnade EventCallback<TValue> (OnClickCallback) till dess ShowMessage-metod.

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

När knappen är markerad i ChildComponent:

• Parent komponentens ShowMessage-metod anropas. message uppdateras och visas i komponenten Parent.
• Ett anrop till StateHasChanged krävs inte i återanropsmetoden (ShowMessage). StateHasChanged anropas automatiskt för att återskapa komponenten Parent, precis som underordnade händelser utlöser komponentrerendering i händelsehanterare som körs inom det underordnade objektet. För mer information, se ASP.NET Core Razor komponentåtergivning.

Använd EventCallback och EventCallback<TValue> för händelsehantering och bindning av komponentparametrar.

Föredra de starkt typade EventCallback<TValue> framför EventCallback. EventCallback<TValue> ger förbättrad feedback om fel när en olämplig typ används, vilket vägleder användare av komponenten mot korrekt implementering. Precis som andra UI-händelsehanterare är det valfritt att ange händelseparametern. Använd EventCallback när inget värde skickas till återanropet.

EventCallback och EventCallback<TValue> tillåter asynkrona delegeringar. EventCallback är svagt typat och tillåter att alla typer av argument överföras i InvokeAsync(Object). EventCallback<TValue> är starkt typat och kräver att du passerar ett T argument i InvokeAsync(T) som är tilldelbart till TValue.

Anropa en EventCallback eller EventCallback<TValue> med InvokeAsync och vänta på Task:

await OnClickCallback.InvokeAsync({ARGUMENT});

I föregående exempel är platshållaren {ARGUMENT} ett valfritt argument.

Följande exempel på förälder-barn visar tekniken.

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

Den andra förekomsten av komponenten Child2 visar ett asynkront återanrop och det nya message2-värdet tilldelas och renderas med en fördröjning på två sekunder.

Förhindra standardåtgärder

Använd attributet @on{DOM EVENT}:preventDefault-direktiv för att förhindra standardåtgärden för en händelse, där platshållaren {DOM EVENT} är en DOM-händelse.

När en nyckel har valts på en indataenhet och elementfokus ligger på en textruta, visar en webbläsare normalt nyckelns tecken i textrutan. I följande exempel förhindras standardbeteendet genom att ange attributet @onkeydown:preventDefault direktiv. När fokus ligger på elementet <input> ökar räknaren med nyckelsekvensen Skift++. Tecknet + tilldelas inte det värde som <input>-elementet har. Mer information om keydownfinns i MDN Web Docs: Document: keydown händelse.

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

Att ange attributet @on{DOM EVENT}:preventDefault utan värde motsvarar @on{DOM EVENT}:preventDefault="true".

Ett uttryck är också ett tillåtet värde för attributet. I följande exempel är shouldPreventDefault ett bool fält inställt på antingen true eller false:

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

...

@code {
    private bool shouldPreventDefault = true;
}

Stoppa händelsespridning

Använd attributet @on{DOM EVENT}:stopPropagation-direktiv för att stoppa händelsespridning inom Blazor omfång. {DOM EVENT} är en platshållare för en DOM-händelse.

stopPropagation-direktivattributets effekt är begränsad till Blazor-omfånget och sträcker sig inte till HTML DOM. Händelser måste spridas till HTML DOM-roten innan Blazor kan agera på dem. Om du vill ha en mekanism för att förhindra HTML DOM-händelsespridning bör du överväga följande metod:

• Hämta händelsens sökväg genom att anropa Event.composedPath().
• Filtrera händelser baserat på de sammansatta händelsemålen (EventTarget).

Om du markerar kryssrutan i följande exempel förhindras klickhändelser från den andra underordnade <div> från att spridas till den överordnade <div>. Eftersom klickhändelser normalt sprids och utlöser OnSelectParentDiv-metoden, resulterar valet av den andra underordnade <div> i att det överordnade <div>-meddelandet visas, om inte kryssrutan är markerad.

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

Fokusera ett element

Anropa FocusAsync på en -elementreferens för att fokusera ett element i kod. I följande exempel väljer du knappen för att fokusera <input>-elementet.

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