ASP.NET Core Blazor 事件處理

本文說明 Blazor 的事件處理功能，包括事件引數類型、事件回呼，以及管理預設瀏覽器事件。

委派事件處理常式

使用 @on{DOM EVENT}="{DELEGATE}"Razor 語法在 Razor 元件標記中指定委派事件處理常式：

• {DOM EVENT} 預留位置是 DOM 事件 (例如 click)。
• {DELEGATE} 預留位置是 C# 委派事件處理常式。

針對事件處理：

• Blazor Web App 中的委派事件處理常式只會在採用互動式轉譯模式的元件中呼叫。 本文中的範例假設應用程式會在應用程式的根元件中全域採用互動式轉譯模式，通常是 App 元件。 如需詳細資訊，請參閱 ASP.NET Core Blazor 轉譯模式。
• 支援可傳回 Task 的非同步委派事件處理常式。
• 委派事件處理常式會自動觸發 UI 轉譯，因此不需要手動呼叫 StateHasChanged。
• 已記錄例外狀況。

下列程式碼範例：

• 在 UI 中選取按鈕時，呼叫 UpdateHeading 方法。
• 在 UI 中變更核取方塊時，呼叫 CheckChanged 方法。

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

在下列範例中，UpdateHeading：

• 會在選取按鈕時以非同步方式呼叫。
• 在更新標題之前等候兩秒。

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

內建事件引數

對於支援事件引數類型的事件，只有在方法中使用事件種類時，才需要在事件方法定義中指定事件參數。 在下列範例中，MouseEventArgs 使用於 ReportPointerLocation 方法來設定訊息文字，以便當使用者在 UI 中選取按鈕時報告滑鼠座標。

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 如下列表格所示。

Event	類別	DOM 附註
剪貼簿	ClipboardEventArgs
拖曳	DragEventArgs	DataTransfer 和 DataTransferItem 可保留拖曳的項目資料。 使用 JS Interop 搭配 HTML 拖放 API，在 Blazor 應用程式中實作拖放。
錯誤	ErrorEventArgs
Event	EventArgs	EventHandlers 可保留屬性，以設定事件名稱與事件引數類型之間的對應。
焦點	FocusEventArgs	不包含對 relatedTarget 的支援。
輸入	ChangeEventArgs
鍵盤	KeyboardEventArgs
滑鼠	MouseEventArgs
Mouse pointer	PointerEventArgs
滑鼠滾輪	WheelEventArgs
進度	ProgressEventArgs
觸控	TouchEventArgs	TouchPoint 代表觸控式裝置上的單一接觸點。

如需詳細資訊，請參閱以下資源：

• ASP.NET Core 參考來源中的 EventArgs 類別 (dotnet/aspnetcore main 分支)

  注意

  .NET 參考來源的文件連結通常會載入存放庫的預設分支，這表示下一版 .NET 的目前開發。 若要選取特定版本的標籤，請使用 [切換分支或標籤] 下拉式清單。 如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。

• EventHandlers 可保留屬性，以設定事件名稱與事件引數類型之間的對應。

自訂事件引數

Blazor 支援自訂事件引數，可讓您透過自訂事件將任意資料傳遞至 .NET 事件處理常式。

一般設定

具有自訂事件引數的自訂事件通常會使用下列步驟來啟用。

在 JavaScript 中，定義函式，以便從來源事件建置自訂事件引數物件：

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

event 參數是 DOM 事件 (MDN 文件)。

在 JavaScript 初始設定式中，向上述處理常式註冊自訂事件。 為 browserEventName 提供適當的瀏覽器事件名稱，本節所示的範例是針對使用者介面中按鈕選取項目的 click。

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js ({PACKAGE ID/ASSEMBLY NAME} 預留位置是應用程式的套件識別碼或組件名稱)：

針對 Blazor Web App：

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

針對 Blazor Server 或 Blazor WebAssembly 應用程式：

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

對 registerCustomEventType 的呼叫只會在指令碼中對每個事件執行一次。

若要呼叫 registerCustomEventType，請使用 Blazor 啟動事件所提供的 blazor 參數 (小寫 b)。 雖然在使用 Blazor 物件 (大寫 B) 時註冊有效，但建議的方法是使用參數。

自訂事件名稱 (上例中的 customevent) 不得與保留的 Blazor 事件名稱相符。 保留名稱可以在 Blazor 架構參考來源中找到 (請參閱對 registerBuiltInEventType 函式的呼叫)。

注意

.NET 參考來源的文件連結通常會載入存放庫的預設分支，這表示下一版 .NET 的目前開發。 若要選取特定版本的標籤，請使用 [切換分支或標籤] 下拉式清單。 如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。

定義事件引數的類別：

namespace BlazorSample.CustomEvents;

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

藉由為自訂事件新增 [EventHandler] 屬性註釋，以連接自訂事件與事件引數：

• 為了讓編譯器找到 [EventHandler] 類別，必須將其放入 C# 類別檔案 (.cs)，使其成為一般最上層類別。
• 將此類別標示為 public。
• 此類別不需要成員。
• 此類別「必須」稱為 "EventHandlers"，才能由 Razor 編譯器找到。
• 將此類別放在應用程式專屬的命名空間底下。
• 將 命名空間匯入至使用事件的 Razor 元件 (.razor)。

using Microsoft.AspNetCore.Components;

namespace BlazorSample.CustomEvents;

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

在一或多個 HTML 元素上註冊事件處理常式。 存取委派處理常式方法中從 JavaScript 傳入的資料：

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

如果 IntelliSense 無法辨識 @oncustomevent 屬性，請確定元件或 _Imports.razor 檔案包含包含 @using 陳述式，其適用於包含 EventHandler 類別的命名空間。

每當在 DOM 上引發自訂事件時，就會使用從 JavaScript 傳遞的資料來呼叫事件處理常式。

如果您嘗試引發自訂事件，則 bubbles 必須藉由將其值設定為 true 來啟用。 否則，事件不會觸達處理至 C# 自訂 [EventHandler] 屬性類別的 Blazor 處理常式。 如需詳細資訊，請參閱 MDN Web Docs：事件反昇。

自訂剪貼簿貼上事件範例

下列範例會接收自訂剪貼簿貼上事件，其中包含貼上的時間和使用者貼上的文字。

宣告事件的自訂名稱 (oncustompaste) 和 .NET 類別 (CustomPasteEventArgs)，以保存此事件的事件引數：

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

新增 JavaScript 程式碼，以在 JavaScript 初始設定式中使用上述處理常式提供 EventArgs 子類別的資料。 下列範例只會處理貼上文字，但您可使用任意 JavaScript API 來處理貼上其他資料類型的使用者，例如影像。

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

針對 Blazor Web App：

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

針對 Blazor Server 或 Blazor WebAssembly 應用程式：

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

在上述範例中，檔案名稱的 {PACKAGE ID/ASSEMBLY NAME} 預留位置代表應用程式的套件識別碼或組件名稱。

注意

若要呼叫 registerCustomEventType，請使用 Blazor 啟動事件所提供的 blazor 參數 (小寫 b)。 雖然在使用 Blazor 物件 (大寫 B) 時註冊有效，但建議的方法是使用參數。

當原生 paste 事件發生時，上述程式碼會告知瀏覽器：

• 引發 custompaste 事件。
• 使用所述的自訂邏輯提供事件引數資料：
  • 針對 eventTimestamp，建立新的日期。
  • 針對 pastedData，以文字的形式取得剪貼簿資料。 如需詳細資訊，請參閱 MDN Web Docs：ClipboardEvent.clipboardData。

.NET 和 JavaScript 之間的事件名稱慣例不同：

• 在 .NET 中，事件名稱前面會加上 "on"。
• 在 JavaScript 中，事件名稱沒有前置詞。

在 Razor 元件中，將自訂處理常式附加至元素。

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 運算式

支援 Lambda 運算式作為委派事件處理常式。

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

使用 C# 方法參數關閉其他值通常很方便，例如在逐一查看一組元素時。 下列範例會建立三個按鈕，每個按鈕都會呼叫 UpdateHeading 並傳遞下列資料：

• e 中的事件引數 (MouseEventArgs)。
• 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}";
}

在迴圈中建立大量事件委派可能會導致轉譯效能不佳。 如需詳細資訊，請參閱 ASP.NET Core Blazor 效能最佳做法。

避免直接在 Lambda 運算式中使用迴圈變數，例如上述 for 迴圈範例中的 i。 否則，所有 Lambda 運算式都會使用相同的變數，這會導致在所有 Lambda 中使用相同的值。 擷取區域變數中的變數值。 在前述範例中:

• 迴圈變數 i 會指派給 buttonNumber。
• buttonNumber 會用於 Lambda 運算式中。

或者，將 foreach 迴圈與 Enumerable.Range 搭配使用，此做法不會因上述問題而受影響：

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

EventCallback

當子系元件事件發生時，巢狀元件的常見案例會執行父代元件的方法。 子系元件中發生的 onclick 事件是常見的使用案例。 若要跨元件公開事件，請使用 EventCallback。 父代元件可以將回呼方法指派給子系元件的 EventCallback。

下列 Child 元件示範如何設定按鈕的 onclick 處理常式，以從範例的 ParentComponent 接收 EventCallback 委派。 EventCallback 的型別為 MouseEventArgs，這適用於來自周邊裝置的 onclick 事件。

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

父元件會將子系的 EventCallback<TValue> （OnClickCallback） 設定為其 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})";
}

在 ChildComponent 中選取按鈕時：

• 就會呼叫 Parent 元件的 ShowMessage 方法。 message 會更新並顯示在 Parent 元件中。
• 回呼的方法中不需要呼叫 StateHasChanged (ShowMessage)。 StateHasChanged 會自動呼叫來重新轉譯 Parent 元件，就像子系事件在子系內執行的事件處理常式中觸發元件重新轉譯一樣。 如需詳細資訊，請參閱 ASP.NET Core Razor 元件轉譯。

使用 EventCallback 和 EventCallback<TValue> 進行事件處理及繫結元件參數。

偏好強型別 EventCallback<TValue>，而不是 EventCallback。 EventCallback<TValue> 會在使用不適當的類型時，提供增強的錯誤意見反應，引導元件的使用者進行正確的實作。 與其他 UI 事件處理常式類似，指定事件參數是選擇性的。 若沒有任何傳遞至回呼的值，請使用 EventCallback。

EventCallback 和 EventCallback<TValue> 都允許非同步委派。 EventCallback 為弱型別，允許在 InvokeAsync(Object) 中傳遞任何型別引數。 EventCallback<TValue> 為強型別，需要在可指派給 TValue 的 InvokeAsync(T) 中傳遞 T 引數。

使用 InvokeAsync 叫用 EventCallback 或 EventCallback<TValue>，並等候 Task：

await OnClickCallback.InvokeAsync({ARGUMENT});

在上述範例中，{ARGUMENT} 預留位置是選擇性引數。

下列父子式範例展示此技術。

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

第二個出現的 Child2 元件示範非同步回呼，而新的 message2 值會在有兩秒延遲的情況下指派及轉譯。

防止預設動作

使用 @on{DOM EVENT}:preventDefault 指示詞屬性來防止事件的預設動作，其中 {DOM EVENT} 預留位置是 DOM 事件。

在輸入裝置上選取按鍵，而元素焦點位於文字方塊時，瀏覽器通常會在文字方塊中顯示按鍵的字元。 在下列範例中，指定 @onkeydown:preventDefault 指示詞屬性來防止預設行為。 當焦點位於 <input> 元素時，計數器會隨著按鍵序列 Shift++ 遞增。 + 字元不會指派給 <input> 元素的值。 如需 keydown 的詳細資訊，請參閱 MDN 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++;
        }
    }
}

指定沒有值的 @on{DOM EVENT}:preventDefault 屬性相當於 @on{DOM EVENT}:preventDefault="true"。

運算式也是屬性允許的值。 在下列範例中，shouldPreventDefault 是設定為 true 或 false 的 bool 欄位：

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

...

@code {
    private bool shouldPreventDefault = true;
}

停止事件傳播

使用 @on{DOM EVENT}:stopPropagation 指示詞屬性來停止 Blazor 範圍內的事件傳播。 {DOM EVENT} 是 DOM 事件的預留位置。

stopPropagation 指示詞屬性的效果僅限於 Blazor 範圍，而且不會延伸至 HTML DOM。 事件必須先傳播至 HTML DOM 根目錄，Blazor 才能對其採取行動。 如需防止 HTML DOM 事件傳播的機制，請考慮下列方法：

• 呼叫 Event.composedPath() 以取得事件的路徑。
• 根據組成的 事件目標 (EventTarget) 篩選事件。

在下列範例中，選取核取方塊可防止從第二個子系 <div> 傳播 Click 事件至父代 <div>。 由於傳播的點選事件通常會引發 OnSelectParentDiv 方法，因此除非已選取核取方塊，否則選取第二個子系 <div> 會導致父代 <div> 訊息出現。

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

將焦點放在元素

在元素參考上呼叫 FocusAsync，以將焦點放在程式碼中的元素。 在下列範例中，選取按鈕以將焦點放在 <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();
    }
}