Dołączanie kodu C# do zdarzeń DOM za pomocą procedur obsługi zdarzeń platformy Blazor

Większość elementów HTML uwidacznia zdarzenia, które są wyzwalane w przypadku wystąpienia czegoś znaczącego. Na przykład po zakończeniu ładowania strony użytkownik kliknie przycisk lub zmieni zawartość elementu HTML. Aplikacja może obsługiwać zdarzenie na kilka sposobów:

• Aplikacja może zignorować zdarzenie.
• Aplikacja może uruchomić program obsługi zdarzeń napisany w języku JavaScript w celu przetworzenia zdarzenia.
• Aplikacja może uruchomić program obsługi zdarzeń platformy Blazor napisany w języku C#, aby przetworzyć zdarzenie.

W tej lekcji uzyskasz szczegółowe informacje na temat trzeciej opcji; jak utworzyć program obsługi zdarzeń platformy Blazor w języku C#, aby przetworzyć zdarzenie.

Obsługa zdarzenia za pomocą platformy Blazor i języka C#

Każdy element w adiustacji HTML aplikacji Blazor obsługuje wiele zdarzeń. Większość z tych zdarzeń odpowiada zdarzeń DOM dostępnych w zwykłych aplikacjach internetowych, ale można również tworzyć zdarzenia zdefiniowane przez użytkownika, które są wyzwalane przez pisanie kodu. Aby przechwycić zdarzenie za pomocą platformy Blazor, należy napisać metodę języka C#, która obsługuje zdarzenie, a następnie powiązać zdarzenie z metodą za pomocą dyrektywy Blazor. W przypadku zdarzenia DOM dyrektywa Blazor ma taką samą nazwę jak równoważne zdarzenie HTML, takie jak @onkeydown lub @onfocus. Na przykład przykładowa aplikacja wygenerowana przy użyciu aplikacji serwera Blazor zawiera następujący kod na stronie Counter.razor . Na tej stronie jest wyświetlany przycisk. Gdy użytkownik wybierze @onclick przycisk, zdarzenie wyzwala metodę, IncrementCount która zwiększa licznik wskazujący liczbę kliknięć przycisku. Element <p> na stronie wyświetla wartość zmiennej licznika:

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Wiele metod obsługi zdarzeń ma parametr, który udostępnia dodatkowe informacje kontekstowe. Ten parametr jest znany jako EventArgs parametr. Na przykład zdarzenie przekazuje informacje o tym, który przycisk @onclick został kliknięty przez użytkownika, lub czy w momencie klikania nacisnął przycisk taki jak Ctrl czy Alt, w parametrze MouseEventArgs. Nie musisz podawać tego parametru podczas wywoływania metody. środowisko uruchomieniowe platformy Blazor dodaje je automatycznie. Ten parametr można wykonać w procedurze obsługi zdarzeń. Poniższy kod zwiększa licznik pokazany w poprzednim przykładzie o pięć, jeśli użytkownik naciska Ctrl w tym samym czasie, co kliknięcie przycisku:

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>


@code {
    private int currentCount = 0;

    private void IncrementCount(MouseEventArgs e)
    {
        if (e.CtrlKey) // Ctrl key pressed as well
        {
            currentCount += 5;
        }
        else
        {
            currentCount++;
        }
    }
}

Inne zdarzenia zapewniają różne EventArgs parametry. Na przykład @onkeypress zdarzenie przekazuje KeyboardEventArgs parametr wskazujący, który został naciśnięty przez użytkownika. W przypadku dowolnego zdarzenia DOM, jeśli nie potrzebujesz tych informacji, możesz pominąć EventArgs parametr z metody obsługi zdarzeń.

Omówienie obsługi zdarzeń w języku JavaScript i obsługi zdarzeń za pomocą platformy Blazor

Tradycyjna aplikacja internetowa używa języka JavaScript do przechwytywania i przetwarzania zdarzeń. Funkcja jest tworzona jako część elementu skryptu< HTML>, a następnie rozmieszczana w celu wywołania tej funkcji po wystąpieniu zdarzenia. W porównaniu z poprzednim przykładem platformy Blazor poniższy kod przedstawia fragment ze strony HTML, która zwiększa wartość i wyświetla wynik za każdym razem, gdy użytkownik wybierze przycisk Kliknij mnie . Kod korzysta z biblioteki jQuery w celu uzyskania dostępu do modelu DOM.

<p id="currentCount">Current count: 0</p>

<button class="btn btn-primary" onclick="incrementCount()">Click me</button>

<!-- Omitted for brevity -->

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script>
    var currentCount = 0;

    function incrementCount() {
        currentCount++;
        $('#currentCount').html('Current count:' + currentCount);
    }
</script>

Oprócz różnic składniowych w dwóch wersjach programu obsługi zdarzeń należy zwrócić uwagę na następujące różnice funkcjonalne:

• Język JavaScript nie prefiksuje nazwy zdarzenia z znakiem @; nie jest to dyrektywa Blazor.
• W kodzie platformy Blazor należy określić nazwę metody obsługi zdarzeń podczas dołączania jej do zdarzenia. W języku JavaScript piszesz instrukcję, która wywołuje metodę obsługi zdarzeń; należy określić nawiasy okrągłe i wszystkie wymagane parametry.
• Co najważniejsze, program obsługi zdarzeń języka JavaScript jest uruchamiany w przeglądarce na kliencie. Jeśli tworzysz aplikację serwera Blazor, program obsługi zdarzeń platformy Blazor jest uruchamiany na serwerze i aktualizuje przeglądarkę tylko za pomocą wszelkich zmian wprowadzonych w interfejsie użytkownika po zakończeniu obsługi zdarzeń. Ponadto mechanizm Blazor umożliwia programowi obsługi zdarzeń dostęp do danych statycznych udostępnianych między sesjami; model JavaScript nie. Jednak obsługa niektórych często występujących zdarzeń, takich jak @onmousemove może spowodować, że interfejs użytkownika stanie się powolny, ponieważ wymagają one rundy sieciowej na serwerze. Wolisz obsługiwać zdarzenia, takie jak te w przeglądarce, przy użyciu języka JavaScript.

Asynchroniczna obsługa zdarzeń

Domyślnie programy obsługi zdarzeń platformy Blazor są synchroniczne. Jeśli program obsługi zdarzeń wykonuje potencjalnie długotrwałą operację, taką jak wywoływanie usługi internetowej, wątek, na którym działa program obsługi zdarzeń, zostanie zablokowany do momentu zakończenia operacji. Taka sytuacja może prowadzić do niskiej reakcji w interfejsie użytkownika. Aby rozwiązać ten problem, można wyznaczyć metodę obsługi zdarzeń jako asynchroniczną. Użyj słowa kluczowego C# async . Metoda musi zwrócić Task obiekt. Następnie można użyć await operatora wewnątrz metody obsługi zdarzeń, aby zainicjować wszystkie długotrwałe zadania w osobnym wątku i zwolnić bieżący wątek do innych zadań. Po zakończeniu długotrwałego zadania program obsługi zdarzeń zostanie wznowione. W poniższym przykładzie pokazano procedurę obsługi zdarzeń, która uruchamia metodę czasochłonną asynchronicznie:

<button @onclick="DoWork">Run time-consuming operation</button>

@code {
    private async Task DoWork()
    {
        // Call a method that takes a long time to run and free the current thread
        var data = await timeConsumingOperation();

        // Omitted for brevity
    }
}

Ustawianie fokusu na element DOM za pomocą zdarzenia

Na stronie HTML użytkownik może karty między elementami, a fokus naturalnie podróżuje w kolejności, w jakiej elementy HTML pojawiają się na stronie. Czasami może być konieczne zastąpienie tej sekwencji i wymusić na użytkowniku wizytę określonego elementu.

Najprostszym sposobem wykonania tego zadania jest użycie FocusAsync metody . "Ta metoda jest metody instancyjną obiektu ElementReference." Element ElementReference powinien odwoływać się do elementu, do którego chcesz ustawić fokus. Należy wyznaczyć odwołanie do elementu z atrybutem @ref i utworzyć obiekt języka C# o tej samej nazwie w kodzie.

W poniższym przykładzie @onclick program obsługi zdarzeń dla <elementu przycisku> ustawia fokus na elemecie wejściowym<>. Procedura @onfocus obsługi zdarzeń elementu wejściowego<>wyświetla komunikat "Odebrano fokus", gdy element pobiera fokus. Element <wejściowy> jest przywołyyny za pośrednictwem zmiennej InputField w kodzie:

<button class="btn btn-primary" @onclick="ChangeFocus">Click me to change focus</button>
<input @ref=InputField @onfocus="HandleFocus" value="@data"/>

@code {
    private ElementReference InputField;
    private string data;

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

    private async Task HandleFocus()
    {
        data = "Received focus";
    }

Na poniższej ilustracji przedstawiono wynik po wybraniu przycisku przez użytkownika:

Pisanie wbudowanych procedur obsługi zdarzeń

Język C# obsługuje wyrażenia lambda. Wyrażenie lambda umożliwia utworzenie funkcji anonimowej. Wyrażenie lambda jest przydatne, jeśli masz prostą procedurę obsługi zdarzeń, której nie trzeba używać ponownie w innym miejscu na stronie lub składniku. W przykładzie liczby kliknięć początkowych pokazanych na początku tej lekcji możesz usunąć IncrementCount metodę i zamiast tego zastąpić wywołanie metody wyrażeniem lambda wykonującym to samo zadanie:

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="() => currentCount++">Click me</button>

@code {
    private int currentCount = 0;
}

Takie podejście jest również przydatne, jeśli chcesz podać inne argumenty dla metody obsługi zdarzeń. W poniższym przykładzie metoda HandleClick przyjmuje MouseEventArgs parametr w taki sam sposób, jak zwykły program obsługi zdarzeń kliknięcia, ale akceptuje również parametr ciągu. Metoda przetwarza zdarzenie kliknięcia tak jak poprzednio, ale także wyświetla komunikat, jeśli użytkownik naciśnie Ctrl . Wyrażenie lambda wywołuje metodę HandleCLick , przekazując MouseEventArgs parametr (mouseEvent) i ciąg.

@page "/counter"
@inject IJSRuntime JS

<h1>Counter</h1>

<p id="currentCount">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick='mouseEvent => HandleClick(mouseEvent, "Hello")'>Click me</button>

@code {
    private int currentCount = 0;

    private async Task HandleClick(MouseEventArgs e, string msg)
    {
        if (e.CtrlKey) // Ctrl key pressed as well
        {
            await JS.InvokeVoidAsync("alert", msg);
            currentCount += 5;
        }
        else
        {
            currentCount++;
        }
    }
}

Zastąpij domyślne akcje DOM dla zdarzeń

Kilka zdarzeń DOM ma domyślne akcje, które są uruchamiane po wystąpieniu zdarzenia, niezależnie od tego, czy istnieje program obsługi zdarzeń dostępny dla tego zdarzenia. Na przykład @onkeypress zdarzenie dla elementu < zawsze wyświetla znak odpowiadający naciśniętemu przez użytkownika klawiszowi, a następnie obsługuje to naciśnięcie. W następnym przykładzie @onkeypress zdarzenie jest używane do konwertowania danych wejściowych użytkownika na wielkie litery. Ponadto, jeśli użytkownik wpisze @ znak, program obsługi zdarzeń wyświetla alert:

<input value=@data @onkeypress="ProcessKeyPress"/>

@code {
    private string data;

    private async Task ProcessKeyPress(KeyboardEventArgs e)
    {
        if (e.Key == "@")
        {
            await JS.InvokeVoidAsync("alert", "You pressed @");
        }
        else
        {
            data += e.Key.ToUpper();
        }
    }
}

Jeśli uruchomisz ten kod i naciśniesz klawisz @, zostanie wyświetlony alert, ale znak @ zostanie również dodany do pola wejściowego. Dodanie @ znaku jest domyślną akcją zdarzenia.

Jeśli chcesz pominąć ten znak przed pojawieniem się w polu wejściowym, możesz zastąpić domyślną akcję atrybutem preventDefault zdarzenia w następujący sposób:

<input value=@data @onkeypress="ProcessKeyPress" @onkeypress:preventDefault />

Zdarzenie nadal jest uruchamiane, ale są wykonywane tylko akcje zdefiniowane przez program obsługi zdarzeń.

Niektóre zdarzenia w elemecie podrzędnym w modelu DOM mogą wyzwalać zdarzenia w elementach nadrzędnych. W poniższym przykładzie <element div> zawiera procedurę obsługi zdarzeń @onclick . Przycisk <> wewnątrz <elementu div> ma własną @onclick procedurę obsługi zdarzeń. <Ponadto element div> zawiera <element wejściowy>:

<div @onclick="HandleDivClick">
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
    <input value=@data @onkeypress="ProcessKeyPress" @onkeypress:preventDefault />
</div>

@code {
    private async Task HandleDivClick()
    {
        await JS.InvokeVoidAsync("alert", "Div click");
    }

    private async Task ProcessKeyPress(KeyboardEventArgs e)
    {
        // Omitted for brevity
    }

    private int currentCount = 0;

    private void IncrementCount(MouseEventArgs e)
    {
        // Omitted for brevity
    }
}

Gdy aplikacja zostanie uruchomiona, jeśli użytkownik kliknie dowolny element (lub puste miejsce) w obszarze zajętym <przez element div> , metoda HandleDivClick zostanie uruchomiona i wyświetli komunikat. Jeśli użytkownik wybierze przycisk Click me, metoda IncrementCount zostanie uruchomiona, a następnie HandleDivClick; zdarzenie @onclick propaguje się w górę drzewa DOM. <Jeśli element div> był częścią innego elementu, który również obsłużył @onclick zdarzenie, program obsługi zdarzeń również zostanie uruchomiony i tak dalej, do katalogu głównego drzewa DOM. Można ograniczyć tę liczbę zdarzeń w górę z stopPropagation atrybutem zdarzenia, jak pokazano poniżej:

<div @onclick="HandleDivClick">
    <button class="btn btn-primary" @onclick="IncrementCount" @onclick:stopPropagation>Click me</button>
    <!-- Omitted for brevity -->
</div>

Używanie klasy EventCallback do obsługi zdarzeń między składnikami

Strona platformy Blazor może zawierać co najmniej jeden składnik platformy Blazor, a składniki mogą być zagnieżdżone w relacji nadrzędny-podrzędny. Zdarzenie w składniku podrzędnym może wyzwolić metodę obsługi zdarzeń w składniku nadrzędnym przy użyciu elementu EventCallback. Wywołanie zwrotne odwołuje się do metody w składniku nadrzędnym. Składnik podrzędny może uruchomić metodę, wywołując wywołanie zwrotne. Ten mechanizm jest podobny do użycia elementu , delegate aby odwołać się do metody w aplikacji języka C#.

Wywołanie zwrotne może przyjmować jeden parametr. EventCallback jest typem ogólnym. Parametr typu określa typ argumentu przekazanego do wywołania zwrotnego.

Rozważmy na przykład następujący scenariusz. Chcesz utworzyć składnik o nazwie TextDisplay, który umożliwia użytkownikowi wprowadzanie ciągu wejściowego i przekształcanie tego ciągu w jakiś sposób. Możesz przekonwertować go na wielkie litery, małe litery, wielkie i małe litery, przefiltrować znaki lub wykonać inny typ przekształcenia. Jednak podczas pisania kodu dla TextDisplay składnika nie wiadomo, jaki będzie proces przekształcania. Zamiast tego chcesz odroczyć tę operację do innego składnika. Poniższy kod przedstawia TextDisplay składnik. Udostępnia on ciąg wejściowy w postaci elementu wejściowego<>, który umożliwia użytkownikowi wprowadzanie wartości tekstowej.

@* TextDisplay component *@
@using WebApplication.Data;

<p>Enter text:</p>
<input @onkeypress="HandleKeyPress" value="@data" />

@code {
    [Parameter]
    public EventCallback<KeyTransformation> OnKeyPressCallback { get; set; }

    private string data;

    private async Task HandleKeyPress(KeyboardEventArgs e)
    {
        KeyTransformation t = new KeyTransformation() { Key = e.Key };
        await OnKeyPressCallback.InvokeAsync(t);
        data += t.TransformedKey;
    }
}

Składnik TextDisplay używa EventCallback obiektu o nazwie OnKeyPressCallback. Kod w metodzie HandleKeypress wywołuje wywołanie zwrotne. Procedura @onkeypress obsługi zdarzeń jest uruchamiana przy każdym naciśnięciu i wywołaniu HandleKeypress metody . Metoda HandleKeypress tworzy KeyTransformation obiekt przy użyciu naciśnięty przez użytkownika i przekazuje ten obiekt jako parametr do wywołania zwrotnego. Typ KeyTransformation jest prostą klasą z dwoma polami:

namespace WebApplication.Data
{
    public class KeyTransformation
    {
        public string Key { get; set; }
        public string TransformedKey { get; set; }
    }
}

Pole key zawiera wartość wprowadzoną przez użytkownika, a TransformedKey pole przechowuje przekształconą wartość klucza po przetworzeniu.

W tym przykładzie EventCallback obiekt jest parametrem składnika, a jego wartość jest dostarczana podczas tworzenia składnika. Składnik o nazwie TextTransformer wykonuje tę akcję:

@page "/texttransformer"
@using WebApplication.Data;

<h1>Text Transformer - Parent</h1>

<TextDisplay OnKeypressCallback="@TransformText" />

@code {
    private void TransformText(KeyTransformation k)
    {
        k.TransformedKey = k.Key.ToUpper();
    }
}

Składnik TextTransformer jest stroną platformy Blazor, która tworzy wystąpienie TextDisplay składnika. OnKeypressCallback Wypełnia parametr odwołaniem do TransformText metody w sekcji kodu strony. Metoda TransformText przyjmuje KeyTransformation obiekt podany jako argument i wypełnia TransformedKey właściwość wartością znajdującą się we Key właściwości przekonwertowanej na wielkie litery. Na poniższym diagramie przedstawiono przepływ sterowania, gdy użytkownik wprowadza wartość do <pola wejściowego> w składniku TextDisplay wyświetlanym przez TextTransformer stronę:

Piękno tego podejścia polega na tym, że można użyć TextDisplay składnika z dowolną stroną, która zapewnia wywołanie zwrotne dla parametru OnKeypressCallback . Istnieje całkowite rozdzielenie między wyświetlaczem a przetwarzaniem. Możesz przełączyć metodę TransformText dla dowolnego innego wywołania zwrotnego zgodnego z podpisem EventCallback parametru w składniku TextDisplay .

Wywołanie zwrotne można połączyć bezpośrednio z procedurą obsługi zdarzeń bez użycia metody pośredniej, jeśli wywołanie zwrotne jest wpisywane przy użyciu odpowiedniego EventArgs parametru. Na przykład składnik podrzędny może odwoływać się do wywołania zwrotnego, który może obsługiwać zdarzenia myszy, takie jak @onclick następujące:

<button @onclick="OnClickCallback">
    Click me!
</button>

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

W tym przypadku EventCallback parametr przyjmuje parametr typu, więc można go określić jako procedurę MouseEventArgs obsługi dla @onclick zdarzenia.