反昇事件

ASP.NET 網頁架構提供稱為事件反昇的技術，允許子控制項在其 Containment 階層架構中向上傳播事件。事件反昇讓事件能夠從控制項階層架構中較便利的位置被引發，並且允許將事件處理常式附加至原始控制項，以及公開反昇的事件的控制項。

事件反昇被資料繫結控制項 (Repeater、DataList 和 DataGrid) 用來將子控制項 (在項目樣板內) 引發的命令事件公開為最上層事件。雖然 .NET Framework 中的 ASP.NET 伺服器控制項針對命令事件 (其事件資料類別衍生自 CommandEventArgs 的事件) 來使用事件反昇，伺服器控制項上定義的任何事件都可以被反昇。

控制項可以透過兩個繼承自基底類別 System.Web.UI.Control 的方法來參與事件反昇。這些方法為 OnBubbleEvent 和 RaiseBubbleEvent。下列程式碼示範這些方法的簽名碼 (Signature)。

protected virtual bool OnBubbleEvent(
   object source,
   EventArgs args
);
protected void RaiseBubbleEvent(
   object source,
   EventArgs args 
);
[Visual Basic]
Overridable Protected Function OnBubbleEvent( _
   ByVal source As Object, _
   ByVal args As EventArgs _
) As Boolean
Protected Sub RaiseBubbleEvent( _
   ByVal source As Object, _
   ByVal args As EventArgs _
)

RaiseBubbleEvent 的實作由 Control 提供，並且不能被覆寫。RaiseBubbleEvent 循階層架構將事件資料向上傳送至控制項的父代 (Parent)。若要處理或引發反昇的事件，控制項必須覆寫 OnBubbleEvent 方法。

控制項若有事件反昇給它，要做下列三件事的其中之一。

• 它不做任何事，此時事件會自動反昇上它的父代。

• 它做某種處理，並繼續反昇事件。若要達成這點，控制項必須覆寫 OnBubbleEvent，並從 OnBubbleEvent 叫用 RaiseBubbleEvent。下列程式片段 (取自樣板化的資料繫結控制項範例) 會在檢查事件引數的型別之後的反昇事件。

  protected override bool OnBubbleEvent(object source, EventArgs e) {
              if (e is CommandEventArgs) {
                  // Adds information about an Item to the  
                  // CommandEvent.
                  TemplatedListCommandEventArgs args =
                      new TemplatedListCommandEventArgs(this, source, (CommandEventArgs)e);
                  RaiseBubbleEvent(this, args);
                  return true;
              }
              return false;
          }
  [Visual Basic]
  Protected Overrides Function OnBubbleEvent(source As Object, e As EventArgs) As Boolean
     If TypeOf e Is CommandEventArgs Then
        ' Adds information about an Item to the  
        ' CommandEvent.
        Dim args As New TemplatedListCommandEventArgs(Me, source, CType(e, CommandEventArgs))
        RaiseBubbleEvent(Me, args)
        Return True
     End If
     Return False
  End Function
  

• 它會停止事件的反昇，並引發和 (或) 處理事件。事件的引發牽涉叫用分派事件至接聽項 (Listener) 的方法。若要引發反昇事件，控制項必須覆寫 OnBubbleEvent 來叫用引發反昇事件的 OnEventName 方法。引發反昇事件的控制項通常將反昇的事件公開為最上層事件。下列程式片段 (取自樣板化的資料繫結控制項範例) 會引發反昇的事件。

  protected override bool OnBubbleEvent(object source, EventArgs e) {
      bool handled = false;
  
      if (e is TemplatedListCommandEventArgs) {
          TemplatedListCommandEventArgs ce = (TemplatedListCommandEventArgs)e;
  
          OnItemCommand(ce);
          handled = true;
      }
      return handled;
  }
  [Visual Basic]
  Protected Overrides Function OnBubbleEvent(source As Object, e As EventArgs) As Boolean
     Dim handled As Boolean = False
  
     If TypeOf e Is TemplatedListCommandEventArgs Then
        Dim ce As TemplatedListCommandEventArgs = CType(e, TemplatedListCommandEventArgs)
  
        OnItemCommand(ce)
        handled = True
     End If
     Return handled
  End Function
  

如需示範事件反昇的範例，請參閱事件反昇控制項範例和樣板化的資料繫結控制項範例。

注意 雖然啟用事件反昇 OnBubbleEvent 的方法遵循引發事件方法的標準 .NET Framework 命名模式，但卻沒有名為 BubbleEvent 的事件。反昇的事件在停止事件反昇的控制項中被公開為的最上層事件。例如，DataList 控制項將其樣板中控制項的 Command 事件公開為 ItemCommand 事件。也要注意 .NET Framework 中 OnEventName 事件的標準簽章具有一個引數 (protected void OnEventName (EventArgs e))。然而，OnBubbleEvent 具有兩個引數，因為事件源自控制項之外；第二個引數提供來源。

討論到目前為止示範了控制項可以如何回應反昇至其事件。下面的章節將示範如何撰寫定義反昇事件的控制項。

定義反昇的事件

如果您要您的控制項啟用其所定義事件的事件反昇，控制項必項從引發事件的 OnEventName 方法中叫用 RaiseBubbleEvent。控制項裡面不需進行額外工作。下列程式片段示範定義啟用反昇的 Command 事件的控制項。

protected virtual void OnCommand(CommandEventArgs e) {
            CommandEventHandler handler = (CommandEventHandler)Events[EventCommand];
            if (handler != null)
                handler(this,e);

            // The Command event is bubbled up the control hierarchy.
            RaiseBubbleEvent(this, e);
        } 
[Visual Basic]
Protected Overridable Sub OnCommand(e As CommandEventArgs)
   Dim handler As CommandEventHandler = CType(Events(EventCommand), CommandEventHandler)
   If Not (handler Is Nothing) Then
      handler(Me, e)
   End If 
   ' The Command event is bubbled up the control hierarchy.
   RaiseBubbleEvent(Me, e)
End Sub

注意 事件反昇並不限於命令事件。您可以使用這裡說明的機制來反昇任何事件。

請參閱

事件反昇控制項範例 | 樣板化的資料繫結控制項範例