ASP.NET AJAX Client Life-Cycle Events
Introduction
A Microsoft ASP.NET AJAX page raises the same server life-cycle events as an ASP.NET 2.0 Web page and also raises client life-cycle events. The client events enable you to customize the UI for both postbacks and for asynchronous postbacks (partial-page updates). The client events also help you manage custom script components during the lifetime of the page in the browser.
Microsoft ASP.NET AJAX有与ASP.NET 2.0 Web page 相同的事件触发生命周期，同时也可以触发客户端生命周期中的事件。客户端事件可以使你针对postbacks 和 asynchronous postbacks 去定制UI。在浏览器的页面周期中，客户端事件有助于你去管理脚本组件
The client events are raised by classes in the Microsoft AJAX Library. These classes are automatically instantiated when a page contains ASP.NET AJAX server controls. The client classes provide APIs that enable you to bind to events and to provide handlers for those events. Because the Microsoft AJAX Library is browser independent, the code you write for your handlers works the same in all supported browsers.
客户端事件可以由 Microsoft AJAX Library中的类触发。这些类自动实例化，当页面中包含ASP.NET AJAX服务器端控件时。客户端的类提供了API接口，使你可以去绑定事件并且提供了这些事件的句柄。因为 Microsoft AJAX Library 是与浏览器独立的，所以你写的处理代码也应该对所有的浏览器进行支持。
The key event for initial requests (GET requests) and synchronous postbacks is the load event of the Application instance. When script in a load event handler runs, all scripts and components have been loaded and are available. When partial-page rendering with UpdatePanel controls is enabled, the key client events are the events of the PageRequestManager class. These events enable you to handle many common scenarios. These include the ability to cancel postbacks, to give precedence to one postback over another, and to animate UpdatePanel controls when their content is refreshed.
对于初使化请求（Get请求）和 同步回传的关键事件是Application实例的Load事件。 当脚本在Load事件中运行的时候，所有的组件和脚本已经被加载并且处于有效状态。当UpdatePanel控件进行局部刷新有效时，关键的事件是pageRequestManager中的事件。这些事件可以使你处理很多一般性的场景。它些包括cancel postback, 指定优先级一个postback 高于另一个postback。或当进行更新操作时对内容进行一些特效处理。
Client events are useful whether you are creating pages or writing components. If you are a page developer, you can provide custom script that is called when the page loads and unloads in the browser.
For more information about the server life-cycle events, see ASP.NET Page Life Cycle Overview.
无论你是创建页面还是写脚本组件， 客户端事件是非常有用的，如果你是一个页面的开发都，你可以提供定制的脚本在页面的load or unload事件在浏览器中被调用
Client Classes
The two main Microsoft AJAX Library classes that raise events during the client life cycle of an ASP.NET AJAX Web page are the Application and PageRequestManager classes.
The Application class is instantiated in the browser when the page contains a ScriptManager control. The Application class resembles the Page server control, which derives from the Control class, but provides additional functionality for raising server events. Similarly, the Application class derives from the Sys.Component class, but raises client life-cycle events that you can handle.
两个主要的Microsoft AJAX Library 类Application and PageRequestManager类在ASP.NET AJAX Web page页面客户端生命周期中触发。
当页面中包含ScriptManager控件时，Application 类被自动初使化。Application类相似于派生于Control的服务器控件（它提供了额外的功能来处理服务器端事件），Application也派生于Sys.Component类，触发你可以处理的客户端事件，
If a page contains a ScriptManager control and one or more UpdatePanel controls, the page can perform partial-page updates (if partial-page rendering is enabled and supported in the browser). In that case, an instance of the PageRequestManager class is automatically available in the browser. The PageRequestManager class raises client events that are specific to asynchronous postbacks. For details about partial-page rendering, see Partial-Page Rendering Overview.
如果页面包含一个ScriptManager和多个UpdatePanel，则页面可以执行局部更新操作。PageRequestManager 在进行局部更新页面中自动是有效的。PageRequestManager 触发特定的异步回传事件。
Adding Handlers for Client Events
To add or remove handlers for events raised by the Application and PageRequestManager classes, use the add_eventname and remove_eventname methods of those classes. The following example shows how to add a handler named MyLoad to the init event of the Application object.
添加客户端句柄
使用add_eventname and remove_eventname 方法来添加或移除Application 和PageRequestManager类的事件句柄。
CS
Sys.Application.add_init(MyInit);
function MyInit(sender) {
}
Sys.Appplication.remove_init(MyInit);
VB
Sys.Application.add_init(MyInit);
function MyInit(sender) {
}
Sys.Appplication.remove_init(MyInit);
This example shows just the syntax of the add_eventname and remove_eventname methods. Details about what you can do with specific events are provided later in this topic.
这个例子Demo 了添加和移除事件句柄的语法，在后面我们将详细的说明
Handling the Application Load and Unload Events
To handle the load and unload events of the Application object, you do not have to explicitly bind a handler to the event. Instead, you can create functions that use the reserved names pageLoad and pageUnload. The following example shows how to add a handler for the load event of the Application object by using this approach.
对于Application 的load and unload事件的句柄，你不需要明确的绑定这些事件的句柄，取而代这的是，你可以创建一个函数（它个函数使用了保留字），下面的例子进行了详细的说明
CS
function pageLoad(sender, args) {
}
VB
function pageLoad(sender, args) {
}
Events for Other Client Classes
This topic describes only the events that are raised by the Application and PageRequestManager classes. The Microsoft AJAX Library also contains classes for adding, clearing, and removing handlers for DOM element events. These classes include the following:
这个主题说明了由Application and PageRequestManager触发的事件，Microsoft AJAX Library 也包含了相关的方法来操作DOM元素的事件，如下所示。
-
The Sys.UI.DomEvent.addHandler method or the shortcut $addHandler.
-
The Sys.UI.DomEvent.clearHandlers method or the shortcut $clearHandlers.
-
The Sys.UI.DomEvent.removeHandler method or the shortcut $removeHandler.
Events raised by DOM elements are not discussed in this topic.
Client Events of the Application and PageRequestManager Classes
The following table lists client events of the Application and PageRequestManager classes that you can handle in AJAX ASP.NET-enabled pages. The order in which the events are raised is described later in this topic.
|
Event |
Description |
|---|---|
|
Raised after all scripts have been loaded but before any objects are created. If you are writing a component, the init event gives you a point in the life cycle to add your component to the page. The component can then be used by other components or by script later in the page life cycle. If you are a page developer, you should use the load event instead of the init event for most scenarios. The init event is raised only one time when the page is first rendered. Subsequent partial-page updates do not raise the init event. | |
|
Raised after all scripts have been loaded and all objects in the application that are created by using $create are initialized. The load event is raised for all postbacks to the server, which includes asynchronous postbacks. If you are a page developer, you can create a function that has the name pageLoad, which automatically provides a handler for the load event. The pageLoad handler is called after any handlers that have been added to the load event by the add_load method. The load event takes an eventargs parameter, which is an Sys.ApplicationLoadEventArgs object. You can use the event arguments to determine whether the page is being refreshed as a result of a partial-page update and what components were created since the previous load event was raised. | |
|
Raised before all objects are disposed and before the browser window's window.unload event occurs. If you are a page developer, you can create a function that has the name pageUnload, which automatically provides a handler for the unload event. The pageUnload event is called just before the page is unloaded from the browser. During this event, you should free any resources that your code is holding. | |
|
Potentially raised when a property of a component changes. The Application object inherits this event from the Component class. This event is raised only if a component developer has called the Sys.Component.raisePropertyChange method in a property set accessor. For more information, see Defining Custom Component Properties and Raising PropertyChanged Events. The propertyChanged event takes an eventargs parameter, which is a Sys.applicationLoadEventArgs object. | |
|
Raised when the Application instance is disposed. The Application object inherits this event from the Component class. | |
|
Raised before an asynchronous request starts. You can use this event to cancel a postback, such as to give precedence to another asynchronous postback. The initializeRequest event takes an eventargs parameter, which is a Sys.WebForms.InitializeRequestEventArgs object. This object makes available the element that caused the postback and the underlying request object. InitializeRequestEventArgs also exposes a cancel property. If you set cancel to true, the new postback is canceled. | |
|
Raised before an asynchronous postback starts and the postback is sent to the server. If there is a postback already processing, it is stopped (by using the abortPostBack method). You can use this event to set request headers or to begin an animation on the page to indicate that the request is in process. The beginRequest event takes an eventargs parameter, which is a Sys.WebForms.BeginRequestEventArgs object. This object makes available the element that caused the postback and the underlying request object. | |
|
Raised after the response from the server to an asynchronous postback is received, but before any content on the page is updated. You can use this event to provide a custom transition effect for updated content. The pageLoading event takes an eventargs parameter, which is an Sys.WebForms.PageLoadingEventArgs object. This object makes available information about what panels will be deleted and updated as a result of the most recent asynchronous postback. | |
|
Raised after all content on the page is refreshed, as a result of either a synchronous or an asynchronous postback. For synchronous postbacks, panels can only be created, but for asynchronous postbacks, panels can be both created and updated. You can use this event to manage a custom transition effect for updated content. The pageLoaded event takes an eventargs parameter, which is an Sys.WebForms.PageLoadedEventArgs object. This object makes available information about which panels were updated and created in the most recent postback. | |
|
Raised after the response for an asynchronous postback is processed and the page is updated, or during the processing of the response if there is an error. If an error occurs, the page is not updated. Use this event to provide customized error notification to users or to log errors. The endRequest event takes an eventargs parameter, which is a Sys.WebForms.EndRequestEventArgs object. This object makes available information about errors that have occurred and whether the error was handled. It also makes available the response object. |
Event Order Example
The following example shows the client events that are raised on a page that includes two UpdatePanel controls, one nested inside the other. You will notice a difference between clicking the button in the parent panel and clicking the button in the nested panel. The button in the parent panel causes the parent panel to be updated and the nested panel to be deleted and recreated. The button in the nested panel causes just the nested panel to be updated.
下面的
Event Order for Common Scenarios
The order of events depends on what controls are used on the page and what type of request is made (initial request, postback, or asynchronous postback). This section describes the order of events for several common scenarios.
Initial Request
During the initial request for the page, a limited number of client events are raised. Assume the following scenario for the initial request:
-
The page contains a ScriptManager control, and the control's SupportsPartialRendering and EnablePartialRendering property are both true.
-
The request is a GET request.
-
A response from the server is returned successfully.
The following client events occur, in this order:
-
The initial request is sent to the server.
-
The response is received by the client.
-
The Application instance raises the init event.
-
The Application instance raises the load event.
The init event of the Application instance is raised only one time for the life of the page in the browser. It is not raised for subsequent asynchronous postbacks. During an initial request, no PageRequestManager events are raised.
Asynchronous Postback
An asynchronous postback sends some page data to the server, receives a response, and updates a part of the page. Assume the following scenario for an asynchronous postback:
-
The page contains a ScriptManager control, and the control's SupportsPartialRendering and EnablePartialRendering properties are both true.
-
The page contains an UpdatePanel control, and the control's ChildrenAsTriggers property is true.
-
A button inside the UpdatePanel control initiates an asynchronous postback.
-
A response from the server is returned successfully.
The following client events occur, in this order:
-
The button inside the UpdatePanel is clicked, which initiates an asynchronous postback.
-
The PageRequestManager instance raises the initializeRequest event.
-
The PageRequestManager instance raises the beginRequest event.
-
The request is sent to the server.
-
The response is received by the client.
-
The PageRequestManager instance raises the pageLoading event.
-
The PageRequestManager instance raises the pageLoaded event.
-
The Application instance raises the load event.
-
The PageRequestManager instance raises the endRequest event.
For more information, see Working with PageRequestManager Events.
Note that the load event of the Application instance is raised after the PageRequestManagerpageLoaded event and before its endRequest event.
Multiple Asynchronous Postbacks
Multiple asynchronous postbacks can occur when users initiate a new request before a previously initiated request has finished processing on the server or in the browser. Assume the following scenario for multiple asynchronous postbacks:
-
The page contains a ScriptManager control and the control's SupportsPartialRendering and EnablePartialRendering property are both true.
-
The page contains an UpdatePanel control.
-
A button inside the UpdatePanel control that initiates an asynchronous postback is clicked two times. The second click occurs while the server is processing the request initiated by the first click.
-
A response to the first request is returned successfully from the server.
The following client events occur, in this order:
-
A button inside the UpdatePanel is clicked, which initiates an asynchronous postback.
-
The PageRequestManager instance raises the initializeRequest event.
-
The PageRequestManager instance raises the beginRequest event.
-
The request is sent to the server.
-
The button is clicked again, which initiates a second asynchronous postback.
-
The PageRequestManager instance raises the initializeRequest event for the second button click.
-
The PageRequestManager instance raises the endRequest event for the first button click.
-
The PageRequestManager instance raises the beginRequest event for the second button click.
-
The request initiated by the second click is sent to the server.
-
The response is received for the second click.
-
The PageRequestManager instance raises the pageLoading event.
-
The PageRequestManager instance raises the pageLoaded event.
-
The Application instance raises the load event.
-
The PageRequestManager instance raises the endRequest event.
The default behavior of asynchronous postbacks is that the most recent asynchronous postback takes precedence. If two asynchronous postbacks occur in sequence, and if the first postback is still being processed in the browser, the first postback is canceled. If the first postback has been sent to the server, the server processes the second request when it arrives and does not return the first request. For information about how to give precedence to a specific asynchronous postback, see Giving Precedence to a Specific Asynchronous Postback.
Browsing Away from a Page
When the user browses away from a page, the current page is unloaded from the browser and you can handle the unload event to free resources. Assume the following scenario for browsing away from a page:
-
The page contains a ScriptManager control and the control's SupportsPartialRendering and EnablePartialRendering property are both true.
-
The target page exists.
The following client events are raised, in this order:
-
The request for new page is initiated.
-
The response for the new page is received by the browser.
-
The Application instance raises the unload event.
-
The new page is displayed.
If there is an error in the request for the new page, the unload event is still raised, but the new page is not displayed.