BlazorObsługa zdarzeń ASP.NET CoreASP.NET Core Blazor event handling

Razor składniki zapewniają funkcje obsługi zdarzeń.Razor components provide event handling features. Dla atrybutu elementu HTML o nazwie @on{EVENT} (na przykład @onclick ) z wartością typu delegata Razor składnik traktuje wartość atrybutu jako procedurę obsługi zdarzeń.For an HTML element attribute named @on{EVENT} (for example, @onclick) with a delegate-typed value, a Razor component treats the attribute's value as an event handler.

Poniższy kod wywołuje metodę, UpdateHeading gdy przycisk zostanie wybrany w interfejsie użytkownika:The following code calls the UpdateHeading method when the button is selected in the UI:

<button class="btn btn-primary" @onclick="UpdateHeading">
    Update heading
</button>

@code {
    private void UpdateHeading(MouseEventArgs e)
    {
        ...
    }
}

Poniższy kod wywołuje metodę, CheckChanged gdy pole wyboru zostanie zmienione w interfejsie użytkownika:The following code calls the CheckChanged method when the check box is changed in the UI:

<input type="checkbox" class="form-check-input" @onchange="CheckChanged" />

@code {
    private void CheckChanged()
    {
        ...
    }
}

Procedury obsługi zdarzeń mogą również być asynchroniczne i zwracać Task .Event handlers can also be asynchronous and return a Task. Nie ma potrzeby ręcznego wywoływania StateHasChanged.There's no need to manually call StateHasChanged. Wyjątki są rejestrowane, gdy wystąpią.Exceptions are logged when they occur.

W poniższym przykładzie UpdateHeading jest wywoływana asynchronicznie po wybraniu przycisku:In the following example, UpdateHeading is called asynchronously when the button is selected:

<button class="btn btn-primary" @onclick="UpdateHeading">
    Update heading
</button>

@code {
    private async Task UpdateHeading(MouseEventArgs e)
    {
        await ...
    }
}

Typy argumentów zdarzeńEvent argument types

W przypadku niektórych zdarzeń dozwolone są typy argumentów zdarzeń.For some events, event argument types are permitted. Określanie parametru zdarzenia w definicji metody zdarzenia jest opcjonalne i wymagane tylko wtedy, gdy typ zdarzenia jest używany w metodzie.Specifying an event parameter in an event method definition is optional and only necessary if the event type is used in the method. W poniższym przykładzie MouseEventArgs argument zdarzenia jest używany w ShowMessage metodzie do ustawiania tekstu komunikatu:In the following example, the MouseEventArgs event argument is used in the ShowMessage method to set message text:

private void ShowMessage(MouseEventArgs e)
{
    messageText = $"The mouse is at coordinates: {e.ScreenX}:{e.ScreenY}";
}

Obsługiwane EventArgs są przedstawione w poniższej tabeli.Supported EventArgs are shown in the following table.

ZdarzenieEvent KlasaClass Zdarzenia i uwagi dotyczące modelu DOMDOM events and notes
SchowekClipboard ClipboardEventArgs oncut, oncopy, onpasteoncut, oncopy, onpaste
PrzeciągnąćDrag DragEventArgs ondrag, ondragstart, ondragenter, ondragleave, ondragover, ondrop, ondragendondrag, ondragstart, ondragenter, ondragleave, ondragover, ondrop, ondragend

DataTransfer i DataTransferItem przytrzymaj przeciągane dane elementu.DataTransfer and DataTransferItem hold dragged item data.

Zaimplementuj przeciąganie i upuszczanie w Blazor aplikacjach przy użyciu usługi js Interop z interfejsem API przeciągania i upuszczania w formacie HTML.Implement drag and drop in Blazor apps using JS interop with HTML Drag and Drop API.
ErrorError ErrorEventArgs onerror
ZdarzenieEvent EventArgs OgólneGeneral
onactivate, onbeforeactivate, onbeforedeactivate, ondeactivate, onfullscreenchange, onfullscreenerror, onloadeddata, onloadedmetadata, onpointerlockchange, onpointerlockerror, onreadystatechange, onscrollonactivate, onbeforeactivate, onbeforedeactivate, ondeactivate, onfullscreenchange, onfullscreenerror, onloadeddata, onloadedmetadata, onpointerlockchange, onpointerlockerror, onreadystatechange, onscroll

SchowekClipboard
onbeforecut, onbeforecopy, onbeforepasteonbeforecut, onbeforecopy, onbeforepaste

Dane wejścioweInput
oninvalid, onreset, onselect, onselectionchange, onselectstart, onsubmitoninvalid, onreset, onselect, onselectionchange, onselectstart, onsubmit

MediaMedia
oncanplay, oncanplaythrough, oncuechange, ondurationchange, onemptied, onended, onpause, onplay, onplaying, onratechange, onseeked, onseeking, onstalled, onstop, onsuspend, ontimeupdate, ontoggle, onvolumechange, onwaitingoncanplay, oncanplaythrough, oncuechange, ondurationchange, onemptied, onended, onpause, onplay, onplaying, onratechange, onseeked, onseeking, onstalled, onstop, onsuspend, ontimeupdate, ontoggle, onvolumechange, onwaiting

EventHandlers przechowuje atrybuty, aby skonfigurować mapowania między nazwami zdarzeń i typami argumentów zdarzeń.EventHandlers holds attributes to configure the mappings between event names and event argument types.
UkierunkowanieFocus FocusEventArgs onfocus, onblur, onfocusin, onfocusoutonfocus, onblur, onfocusin, onfocusout

Nie obejmuje obsługi dla relatedTarget .Doesn't include support for relatedTarget.
Dane wejścioweInput ChangeEventArgs onchange, oninputonchange, oninput
KlawiaturaKeyboard KeyboardEventArgs onkeydown, onkeypress, onkeyuponkeydown, onkeypress, onkeyup
MyszMouse MouseEventArgs onclick, oncontextmenu, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseoutonclick, oncontextmenu, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout
Wskaźnik myszyMouse pointer PointerEventArgs onpointerdown, onpointerup, onpointercancel, onpointermove, onpointerover, onpointerout, onpointerenter, onpointerleave, ongotpointercapture, onlostpointercaptureonpointerdown, onpointerup, onpointercancel, onpointermove, onpointerover, onpointerout, onpointerenter, onpointerleave, ongotpointercapture, onlostpointercapture
Kółka myszyMouse wheel WheelEventArgs onwheel, onmousewheelonwheel, onmousewheel
PostępProgress ProgressEventArgs onabort, onload, onloadend, onloadstart, onprogress, ontimeoutonabort, onload, onloadend, onloadstart, onprogress, ontimeout
DotykTouch TouchEventArgs ontouchstart, ontouchend, ontouchmove, ontouchenter, ontouchleave, ontouchcancelontouchstart, ontouchend, ontouchmove, ontouchenter, ontouchleave, ontouchcancel

TouchPoint reprezentuje pojedynczy punkt kontaktu na urządzeniu z wrażliwym dotknięciem.TouchPoint represents a single contact point on a touch-sensitive device.
ZdarzenieEvent KlasaClass Zdarzenia i uwagi dotyczące modelu DOMDOM events and notes
SchowekClipboard ClipboardEventArgs oncut, oncopy, onpasteoncut, oncopy, onpaste
PrzeciągnąćDrag DragEventArgs ondrag, ondragstart, ondragenter, ondragleave, ondragover, ondrop, ondragendondrag, ondragstart, ondragenter, ondragleave, ondragover, ondrop, ondragend

DataTransfer i DataTransferItem przytrzymaj przeciągane dane elementu.DataTransfer and DataTransferItem hold dragged item data.

Zaimplementuj przeciąganie i upuszczanie w Blazor aplikacjach przy użyciu usługi js Interop z interfejsem API przeciągania i upuszczania w formacie HTML.Implement drag and drop in Blazor apps using JS interop with HTML Drag and Drop API.
ErrorError ErrorEventArgs onerror
ZdarzenieEvent EventArgs OgólneGeneral
onactivate, onbeforeactivate, onbeforedeactivate, ondeactivate, onfullscreenchange, onfullscreenerror, onloadeddata, onloadedmetadata, onpointerlockchange, onpointerlockerror, onreadystatechange, onscrollonactivate, onbeforeactivate, onbeforedeactivate, ondeactivate, onfullscreenchange, onfullscreenerror, onloadeddata, onloadedmetadata, onpointerlockchange, onpointerlockerror, onreadystatechange, onscroll

SchowekClipboard
onbeforecut, onbeforecopy, onbeforepasteonbeforecut, onbeforecopy, onbeforepaste

Dane wejścioweInput
oninvalid, onreset, onselect, onselectionchange, onselectstart, onsubmitoninvalid, onreset, onselect, onselectionchange, onselectstart, onsubmit

MediaMedia
oncanplay, oncanplaythrough, oncuechange, ondurationchange, onemptied, onended, onpause, onplay, onplaying, onratechange, onseeked, onseeking, onstalled, onstop, onsuspend, ontimeupdate, onvolumechange, onwaitingoncanplay, oncanplaythrough, oncuechange, ondurationchange, onemptied, onended, onpause, onplay, onplaying, onratechange, onseeked, onseeking, onstalled, onstop, onsuspend, ontimeupdate, onvolumechange, onwaiting

EventHandlers przechowuje atrybuty, aby skonfigurować mapowania między nazwami zdarzeń i typami argumentów zdarzeń.EventHandlers holds attributes to configure the mappings between event names and event argument types.
UkierunkowanieFocus FocusEventArgs onfocus, onblur, onfocusin, onfocusoutonfocus, onblur, onfocusin, onfocusout

Nie obejmuje obsługi dla relatedTarget .Doesn't include support for relatedTarget.
Dane wejścioweInput ChangeEventArgs onchange, oninputonchange, oninput
KlawiaturaKeyboard KeyboardEventArgs onkeydown, onkeypress, onkeyuponkeydown, onkeypress, onkeyup
MyszMouse MouseEventArgs onclick, oncontextmenu, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseoutonclick, oncontextmenu, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout
Wskaźnik myszyMouse pointer PointerEventArgs onpointerdown, onpointerup, onpointercancel, onpointermove, onpointerover, onpointerout, onpointerenter, onpointerleave, ongotpointercapture, onlostpointercaptureonpointerdown, onpointerup, onpointercancel, onpointermove, onpointerover, onpointerout, onpointerenter, onpointerleave, ongotpointercapture, onlostpointercapture
Kółka myszyMouse wheel WheelEventArgs onwheel, onmousewheelonwheel, onmousewheel
PostępProgress ProgressEventArgs onabort, onload, onloadend, onloadstart, onprogress, ontimeoutonabort, onload, onloadend, onloadstart, onprogress, ontimeout
DotykTouch TouchEventArgs ontouchstart, ontouchend, ontouchmove, ontouchenter, ontouchleave, ontouchcancelontouchstart, ontouchend, ontouchmove, ontouchenter, ontouchleave, ontouchcancel

TouchPoint reprezentuje pojedynczy punkt kontaktu na urządzeniu z wrażliwym dotknięciem.TouchPoint represents a single contact point on a touch-sensitive device.

Więcej informacji można znaleźć w następujących zasobach:For more information, see the following resources:

Wyrażenia lambdaLambda expressions

Wyrażenia lambda mogą być również używane:Lambda expressions can also be used:

<button @onclick="@(e => Console.WriteLine("Hello, world!"))">Say hello</button>

Często wygodnie jest blisko dodatkowych wartości, na przykład podczas iteracji na zestawie elementów.It's often convenient to close over additional values, such as when iterating over a set of elements. Poniższy przykład tworzy trzy przyciski, z których każdy wywołuje UpdateHeading przekazanie argumentu zdarzenia ( MouseEventArgs ) i jego numer przycisku ( buttonNumber ), po wybraniu w interfejsie użytkownika:The following example creates three buttons, each of which calls UpdateHeading passing an event argument (MouseEventArgs) and its button number (buttonNumber) when selected in the UI:

<h2>@message</h2>

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

    <button class="btn btn-primary"
            @onclick="@(e => UpdateHeading(e, buttonNumber))">
        Button #@i
    </button>
}

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

    private void UpdateHeading(MouseEventArgs e, int buttonNumber)
    {
        message = $"You selected Button #{buttonNumber} at " +
            $"mouse position: {e.ClientX} X {e.ClientY}.";
    }
}

Uwaga

Nie używaj zmiennej Loop bezpośrednio w wyrażeniu lambda, na przykład i w powyższym for przykładzie pętli.Do not use a loop variable directly in a lambda expression, such as i in the preceding for loop example. W przeciwnym razie ta sama zmienna jest używana przez wszystkie wyrażenia lambda, które w wyniku używają tej samej wartości we wszystkich lambdach.Otherwise, the same variable is used by all lambda expressions, which results in use of the same value in all lambdas. Zawsze Przechwytuj wartość zmiennej w zmiennej lokalnej, a następnie użyj jej.Always capture the variable's value in a local variable and then use it. W poprzednim przykładzie zmienna Loop i jest przypisana do buttonNumber .In the preceding example, the loop variable i is assigned to buttonNumber.

EventCallbackEventCallback

Typowym scenariuszem ze składnikami zagnieżdżonymi jest uruchomienie metody składnika nadrzędnego, gdy wystąpi zdarzenie składnika podrzędnego.A common scenario with nested components is the desire to run a parent component's method when a child component event occurs. onclickZdarzenie występujące w składniku podrzędnym jest wspólnym przypadkiem użycia.An onclick event occurring in the child component is a common use case. Aby uwidocznić zdarzenia między składnikami, użyj EventCallback .To expose events across components, use an EventCallback. Składnik nadrzędny może przypisać metodę wywołania zwrotnego do składnika podrzędnego EventCallback .A parent component can assign a callback method to a child component's EventCallback.

ChildComponentW aplikacji przykładowej ( Components/ChildComponent.razor ) pokazano, jak onclick program obsługi przycisku został skonfigurowany tak, aby otrzymać EventCallback delegata z przykładu ParentComponent .The ChildComponent in the sample app (Components/ChildComponent.razor) demonstrates how a button's onclick handler is set up to receive an EventCallback delegate from the sample's ParentComponent. EventCallbackTyp ma wartość MouseEventArgs , która jest odpowiednia dla onclick zdarzenia z urządzenia peryferyjnego:The EventCallback is typed with MouseEventArgs, which is appropriate for an onclick event from a peripheral device:

<div class="panel panel-default">
    <div class="panel-heading">@Title</div>
    <div class="panel-body">@ChildContent</div>

    <button class="btn btn-primary" @onclick="OnClickCallback">
        Trigger a Parent component method
    </button>
</div>

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

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

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

ParentComponentUstawia element podrzędny EventCallback<TValue> ( OnClickCallback ) na jego ShowMessage metodę.The ParentComponent sets the child's EventCallback<TValue> (OnClickCallback) to its ShowMessage method.

Pages/ParentComponent.razor:Pages/ParentComponent.razor:

@page "/ParentComponent"

<h1>Parent-child example</h1>

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

<p><b>@messageText</b></p>

@code {
    private string messageText;

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

Gdy przycisk zostanie wybrany w ChildComponent :When the button is selected in the ChildComponent:

  • ParentComponent ShowMessage Metoda jest wywoływana.The ParentComponent's ShowMessage method is called. messageText jest aktualizowany i wyświetlany w ParentComponent .messageText is updated and displayed in the ParentComponent.
  • Wywołanie StateHasChanged nie jest wymagane w metodzie wywołania zwrotnego ( ShowMessage ).A call to StateHasChanged isn't required in the callback's method (ShowMessage). StateHasChanged jest automatycznie wywoływana w celu odrenderowania ParentComponent elementu, podobnie jak zdarzenia podrzędne wyzwala ponowne renderowanie składnika w obsłudze zdarzeń, które są wykonywane w ramach elementu podrzędnego.StateHasChanged is called automatically to rerender the ParentComponent, just as child events trigger component rerendering in event handlers that execute within the child. Aby uzyskać więcej informacji, zobacz BlazorRenderowanie składników ASP.NET Core.For more information, see BlazorRenderowanie składników ASP.NET Core.

EventCallback i EventCallback<TValue> Zezwalaj na asynchroniczne Delegaty.EventCallback and EventCallback<TValue> permit asynchronous delegates. EventCallback jest słabo wpisywany i umożliwia przekazanie dowolnego argumentu typu w InvokeAsync(Object) .EventCallback is weakly typed and allows passing any type argument in InvokeAsync(Object). EventCallback<TValue> jest silnie wpisana i wymaga przekazania T argumentu w elemencie InvokeAsync(T) , który można przypisać do TValue .EventCallback<TValue> is strongly typed and requires passing a T argument in InvokeAsync(T) that's assignable to TValue.

<ChildComponent 
    OnClickCallback="@(async () => { await Task.Yield(); messageText = "Blaze It!"; })" />

Wywołaj EventCallback lub EventCallback<TValue> z InvokeAsync i await Task :Invoke an EventCallback or EventCallback<TValue> with InvokeAsync and await the Task:

await OnClickCallback.InvokeAsync(arg);

Używaj EventCallback i EventCallback<TValue> dla parametrów składnika Obsługa zdarzeń i powiązania.Use EventCallback and EventCallback<TValue> for event handling and binding component parameters.

Preferuj silnie wpisaną EventCallback<TValue> wartość EventCallback .Prefer the strongly typed EventCallback<TValue> over EventCallback. EventCallback<TValue> zapewnia lepszą opinię o błędach dla użytkowników składnika.EventCallback<TValue> provides better error feedback to users of the component. Podobnie jak w przypadku innych programów obsługi zdarzeń interfejsu użytkownika, określenie parametru zdarzenia jest opcjonalne.Similar to other UI event handlers, specifying the event parameter is optional. Użyj EventCallback w przypadku braku wartości przekazywania do wywołania zwrotnego.Use EventCallback when there's no value passed to the callback.

Zapobiegaj akcjom domyślnymPrevent default actions

Użyj @on{EVENT}:preventDefault atrybutu dyrektywy, aby zapobiec domyślnej akcji dla zdarzenia.Use the @on{EVENT}:preventDefault directive attribute to prevent the default action for an event.

Po wybraniu klucza na urządzeniu wejściowym, gdy fokus elementu znajduje się w polu tekstowym, przeglądarka zwykle wyświetla znak klucza w polu tekstowym.When a key is selected on an input device and the element focus is on a text box, a browser normally displays the key's character in the text box. W poniższym przykładzie zachowanie domyślne jest blokowane przez określenie @onkeypress:preventDefault atrybutu dyrektywy.In the following example, the default behavior is prevented by specifying the @onkeypress:preventDefault directive attribute. Licznik jest zwiększany, a + klucz nie jest przechwytywany do <input> wartości elementu:The counter increments, and the + key isn't captured into the <input> element's value:

<input value="@count" @onkeypress="KeyHandler" @onkeypress:preventDefault />

@code {
    private int count = 0;

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

Określanie @on{EVENT}:preventDefault atrybutu bez wartości jest równoważne @on{EVENT}:preventDefault="true" .Specifying the @on{EVENT}:preventDefault attribute without a value is equivalent to @on{EVENT}:preventDefault="true".

Wartość atrybutu może również być wyrażeniem.The value of the attribute can also be an expression. W poniższym przykładzie shouldPreventDefault bool pole jest ustawione na jedną true lub false :In the following example, shouldPreventDefault is a bool field set to either true or false:

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

Zatrzymaj propagację zdarzeńStop event propagation

Użyj @on{EVENT}:stopPropagation atrybutu dyrektywy, aby zatrzymać propagację zdarzeń.Use the @on{EVENT}:stopPropagation directive attribute to stop event propagation.

W poniższym przykładzie, zaznaczając pole wyboru, uniemożliwiają klikanie zdarzeń z drugiego elementu podrzędnego <div> od propagowania do obiektu nadrzędnego <div> :In the following example, selecting the check box prevents click events from the second child <div> from propagating to the parent <div>:

<label>
    <input @bind="stopPropagation" type="checkbox" />
    Stop Propagation
</label>

<div @onclick="OnSelectParentDiv">
    <h3>Parent div</h3>

    <div @onclick="OnSelectChildDiv">
        Child div that doesn't stop propagation when selected.
    </div>

    <div @onclick="OnSelectChildDiv" @onclick:stopPropagation="stopPropagation">
        Child div that stops propagation when selected.
    </div>
</div>

@code {
    private bool stopPropagation = false;

    private void OnSelectParentDiv() => 
        Console.WriteLine($"The parent div was selected. {DateTime.Now}");
    private void OnSelectChildDiv() => 
        Console.WriteLine($"A child div was selected. {DateTime.Now}");
}

Skupienie się na elemencieFocus an element

Wywołaj FocusAsync odwołanie do elementu , aby skoncentrować się na elemencie w kodzie:Call FocusAsync on an element reference to focus an element in code:

<input @ref="exampleInput" />

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

@code {
    private ElementReference exampleInput;

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