ASP.NET AJAX 客户端生命周期事件

翻译：Valens原文：http://ajax.asp.net/docs/overview/AJAXClientEvents.aspx欢迎大家提出意见，我会积极进行修改的！Introduction【介绍】;微软Ajax提出了与ASP.NET;2.0页面服务器端生命周期事件相似的客户端生命周期事件。这些客户端事件使得我们能为传统回送和异步回送（部分页面刷新）都能定制自己的用户界面。它们还可以在整个页面生命周期期间帮助你管理和使用自定义的脚本。这些客户端事件在微软的AJAX;Libray的类中都被提出来了（我们可以在AJAX;Libray的类中找到它们）。当加载一个带有AJAX服务器控件时，这些类都会自动地实例化(instantiated?)。这些类提供了一些APIs以便我们能够将事件绑定到事件提供处理程序。并且AJAX;Library是独立于浏览器的，所以你写的代码可以工作在所有支持的浏览器。关键的事件是初始化请求和异步回送的应用程序实例的;load;事件。当脚本在加载处理事件运行时，所有的脚本和组件都已经被加载并且是可用的。当使用了;UpdatePanel;控件部分页面刷新时，所有客户端事件中最关键的就是;PageRequestManager;类。这些客户端事件使得你能够实现某些场景。比如包括了：;撤销回送，为一个回送设置更高的优先级，还可以使;UpdatePanel;在刷新的时候交互得更好。这些事件对于我们创建页面或写组件都有很大的帮助。如果你是一个网页开发人员，你可以为页面在加载和卸载时使用定制的脚本。向了解更多服务器端生命周期事件，可以参考;ASP.NET;Page;Life;Cycle;Overview.Client;Classes【客户端类】在微软AJAX类库中提出了在AJAX网页的客户端生命周期中两个很主要的类：;Application;类和;PageRequestManager;类。当浏览器请求一个有包含有;ScriptManager;控件的页面时，Application;类就实例化了。Application;类和服务器端的;Page;控件类似，也是继承自;Control;类，不过却额外附加了一些功能（相比服务端事件）。类似的，;Application;继承了;Sys.COmponent;类，除此，还提供了很多在客户端生命周期期间内的可操作事件。如果一个页面包含了一个;ScriptManager，并且还存在了一个或更多的;UpdatePanel;控件，那么这个页面就可以实现部分更新的效果了。如果是那样的话，一个;PageRequestManager;类的实例对浏览器是可用的了。PageRequestManager;提供的客户端事件都是关于异步回送的。更多关于生成部分页面的细节请参考：Partial-Page;Rendering;Overview.Adding;Handlers;for;Client;Events【为客户端事件增加Handler】现在通过使用;Application;和;PageRequestManager;类中的;add_eventname;和;reomve_eventname;方法来添加或移除事件。下面这个例子展示了如何添加一个操作(handler)名为;MyLoad;到;Application;对象的;init;事件。Sys.Application.add_init(MyInit);function;MyInit(sender);{}Sys.Appplication.remove_init(MyInit);注释；这个例子只是展示了使用;add_eventname;和;remove_eventname;方法的语法。更多关于使用这个事件的细节将在后面的主题提供。Handling;the;Application;Load;and;Unload;Events【操作Application的加载和卸载事件】要操作;Application;对象的;load;和;unload;事件，不需要显示地绑定到一个操作事件。相反地，你可以直接使用保留关键字;pageLoad;和;pageUnload;来创建一个函数。下面这个例子展示了如何为;Application;的;load;事件添加一个操作。function;pageLoad(sender,;args);{}Events;for;Other;Client;Classes【其它客户端类】这个主题仅仅描述由;Application;和;PageRequestManager;类提供的事件。微软的AJAX类库还包括了以下的类用于;DOM;元素事件的添加、清除和移除。这些类包括了：有;Sys.UI.DomEvent.addHandler;方法或简短写法;$addHandler.有;Sys.UI.DomEvent.clearHandlers;方法或简短写法;$clearHandlers.有;Sys.UI.DomEvent.removeHandler;方法或简短写法;$removeHandler.有关;DOM;原理提供的事件不是本主题讨论的。Client;Events;of;the;Application;and;PageRequestManager;Classes【Application和PageRequestManager类的客户端事件】下面的表格列出了你可以在;AJAX;的;ASP.NET;页面使用的;Application;和;PageRequestManager;类的客户端事件。事件发生的顺序将在稍后的主题中进行讨论。Event（事件名称）Description（描述）init;Event;[初始化事件]在所有脚本被加载后，在任何一个对象被创建之前引发该事件。如果你打算写一个组件（脚本），init;事件提供了一个在生命周期内添加组件（脚本）到页面的点。该组件可以被其它在生命周期内的脚本调用。如果你是一个网页开发人员，在大多数的情况之下，建议用;load;事件来替代;init;事件来处理。init;事件只在页面开始生成时创建一次。后来的部分页面刷新将不会引发;init;事件。load;Event;[加载事件]该事件在所有脚本被加载后，并且由使用;$create;初始化的所有程序对象被创建后引发。该事件将被所有回送到服务器引发，这些回送也包括异步的回送。如果你是网页开发人员，你可以创建一个名为;pageLoad;的函数，该函数是由加载事件本身提供的。该;pageLoad;操作（handler）是在任何一个通过;add_load;方法被添加到;load;事件的操作后可以调用。load;事件需要一个;Sys.ApplicationLoadEventArgs;对象作为;eventargs;参数。你可以通过该参数来决定页面是否需要显示部分刷新，还可以决定哪些组件应当在上一个引发;load;事件后被创建。unload;Event;[卸载事件]在所有对象被释放之前，在浏览器的;window.unload;事件发生之前被引发。你可以通过系统自身提供的一个名为;pageUnload;的函数来处理卸载事件。pageUnload;事件是在页面在浏览器中卸载时调用。在该事件发生期间，我们应当释放由代码占用的全部资源。propertyChanged;Event;[属性改变事件]当某组件的属性发生改变时引发。应用程序对象是从;Component;类那里继承了这个事件。该事件仅在开发人员在设置一个属性值的时候调用了;Sys.Component.raisePropertyChange;方法而引发的。更多信息请查看;Defining;Custom;Component;Properties;and;Raising;PropertyChanged;Events.属性改变事件需要一个;Sys.applicationLoadEventArgs;对象作为;eventargs;参数。disposing;Event;[释放事件]该事件是在应用程序实例被释放时引发的。应用程序对象从;Component;类继承了该事件。initializeRequest;Event;[初始化请求事件]该事件发生在一个异步请求开始时。你可以通过使用该事件来取消一个传统的回送，例如让一个异步回送获得优先。初始化请求事件需要一个;Sys.WebForms.InitializeRequestEventArgs;对象提供的;eventargs;参数。该对象提供了那些引起回送和暗藏的（underlying）请求的对象的有用的元素。该事件还暴露了;cancel;属性。如果你设置;cancel;值为;true，一个新的回送将被撤销。beginRequest;Event;[开始请求事件]该事件是在一个回送到服务器的异步回送开始前引发。如果当前已经存在了一个回送进程，则会被停止(by;using;the;abortPostBack;method)。你可以使用该事件来设置请求的头部或显示一个有趣的（animation）提示在页面中，表示该请求正在进行中。该事件需要一个;Sys.WebForms.BeginRequestEventArgs;对象作为;eventargs;参数。该对象提供了引起回送的和暗藏的（underlying）请求对象的有用的元素。pageLoading;Event;[页面正在加载事件]当确定一个异步回送被服务器端接收后，在页面任何内容被更新前引发。可以使用该事件来为需要更新的内容提供一个定制过渡效果。该事件需要一个;Sys.WebForms.PageLoadingEventArgs;对象作为;eventargs;参数。该对象提供了最近的异步回送返回的结果关于哪些;panels;会被删除和更新的有用的信息。pageLoaded;Event[页面加载完成事件]在页面所有内容被一个同步或异步回送结果刷新之后引发。在同步回送时，panels;只能被创建，但在异步回送时，panels;可以被创建和更新。可以通过使用该事件来管理一个为需要更新的内容定制的变化效果。该事件需要一个;Sys.WebForms.PageLoadedEventArgs;对象作为;eventargs;参数。该对象提供了关于最近回送时的那些;panels;被更新和创建的有用的信息。endRequest;Event;[结束请求事件]在响应了完成一个异步回送和页面被更新后，或在请求过程中发生了错误后引发。如果发生了某个错误，页面将不会被更新。通过使用这个事件来提供一个定制的错误提示给访问者或登记到错误日志。该事件需要一个;Sys.WebForms.EndRequestEventArgs;对象作为;eventargs;参数。该对象提供了有关被引发的错误和错误是否被处理的一些有用的信息。它还提供了有关相应对象的可用的信息。Event;Order;Example;【事件顺序的例子】下面的这个例子展示了在一个存在有两个嵌套的;UpdatePanel;控件的页面的客户端事件将被如何引发。请注意点击父;panel;中的按钮的和内嵌的;panel;中按钮的区别。在父;panel;中的按钮将引起父;panel;的更新，和嵌在其中的;panel;将被删除并重新创建。内嵌;panel;的按钮仅引起内嵌;panel;的更新。页面代码：1<%@;Page;Language="C#";%>23<!DOCTYPE;html;PUBLIC;"-//W3C//DTD;XHTML;1.0;Transitional//EN";4;"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">56<script;runat="server">78</script>910<html;xmlns="http://www.w3.org/1999/xhtml";>11<head;runat="server">12;<title>Client;Event;Example</title>13;<style;type="text/css">14;#OuterPanel;{;width:;600px;;height:;200px;;border:;2px;solid;blue;;}15;#NestedPanel;{;width:;596px;;height:;60px;;border:;2px;solid;green;;16;margin-left:5;px;;margin-right:5px;;margin-bottom:5px;}17;</style>18</head>19<body>20;<form;id="form1";runat="server">21;<div>22;<asp:ScriptManager;ID="ScriptManager1";runat="server">23;<Scripts>24;<asp:ScriptReference;Path="ClientEventTest.js";/>25;</Scripts>26;</asp:ScriptManager>27;<asp:UpdatePanel;ID="OuterPanel";UpdateMode="Conditional";runat="server">28;<ContentTemplate>29;Postbacks;from;inside;the;outer;panel;and;inner;panel;are30;asynchronous;postbacks.;PRM;=;Sys.WebForms.PageRequestManager.;APP;=;Sys.Application.3132;<br;/><br;/>33;<asp:Button;ID="OPButton1";Text="Outer;Panel;Button";runat="server";/>34;Last;updated;on35;<%=;DateTime.Now.ToString();%>36;<br;/><br;/>3738;<asp:UpdatePanel;ID="NestedPanel";UpdateMode="Conditional";runat="server">39;<ContentTemplate>40;<asp:Button;ID="NPButton1";Text="Nested;Panel;1;Button";runat="server";/>41;Last;updated;on42;<%=;DateTime.Now.ToString();%>43;<br;/>44;</ContentTemplate>45;</asp:UpdatePanel>46;</ContentTemplate>47;</asp:UpdatePanel>4849;<input;type="button";onclick="Clear();";value="Clear";/>5051;<asp:Button;ID="FullPostBack";runat="server";Text="Full;Postback";/>52;<a;href="Test'>http://www.microsoft.com">Test;Window;Unload</a>53;<br;/>54;<span;id="ClientEvents"></span>;55;</div>56;</form>57</body>58</html>59脚本代码：1//;Hook;up;Application;event;handlers.2var;app;=;Sys.Application;3app.add_load(ApplicationLoad);4app.add_init(ApplicationInit);5app.add_disposing(ApplicationDisposing);6app.add_unload(ApplicationUnload);789//;Application;event;handlers;for;component;developers.10function;ApplicationInit(sender);{11;var;prm;=;Sys.WebForms.PageRequestManager.getInstance();12;if;(!prm.get_isInAsyncPostBack())13;{14;prm.add_initializeRequest(InitializeRequest);15;prm.add_beginRequest(BeginRequest);16;prm.add_pageLoading(PageLoading);17;prm.add_pageLoaded(PageLoaded);18;prm.add_endRequest(EndRequest);19;}20;$get('ClientEvents').innerHTML;=;"APP::;Application;init.;<br/>";21}22function;ApplicationLoad(sender,;args);{23;$get('ClientEvents').innerHTML;=;"APP::;Application;load.;";24;$get('ClientEvents').innerHTML;=;"(isPartialLoad;=;";args.get_isPartialLoad();")<br/>";25}26function;ApplicationUnload(sender);{27;alert('APP::;Application;unload.');28}29function;ApplicationDisposing(sender);{30;$get('ClientEvents').innerHTML;=;"APP::;Application;disposing.;<br/>";31;32}33//;Application;event;handlers;for;page;developers.34function;pageLoad();{35;$get('ClientEvents').innerHTML;=;"PAGE::;Load.<br/>";36}3738function;pageUnload();{39;alert('Page::;Page;unload.');40}4142//;PageRequestManager;event;handlers.43function;InitializeRequest(sender,;args);{44;$get('ClientEvents').innerHTML;=;"<hr/>";45;$get('ClientEvents').innerHTML;=;"PRM::;Initializing;async;request.<br/>";;46}47function;BeginRequest(sender,;args);{48;$get('ClientEvents').innerHTML;=;"PRM::;Begin;processing;async;request.<br/>";49}50function;PageLoading(sender,;args);{51;$get('ClientEvents').innerHTML;=;"PRM::;Loading;results;of;async;request.<br/>";52;var;updatedPanels;=;printArray("PanelsUpdating",;args.get_panelsUpdating());53;var;deletedPanels;=;printArray("PanelsDeleting",;args.get_panelsDeleting());54;55;var;message;=;"-->";updatedPanels;"<br/>-->";deletedPanels;"<br/>";56;57;document.getElementById("ClientEvents").innerHTML;=;message;58}59function;PageLoaded(sender,;args);{60;$get('ClientEvents').innerHTML;=;"PRM::;Finished;loading;results;of;async;request.<br/>";61;var;updatedPanels;=;printArray("PanelsUpdated",;args.get_panelsUpdated());62;var;createdPanels;=;printArray("PaneslCreated",;args.get_panelsCreated());63;64;var;message;=;"-->";updatedPanels;"<br/>-->";createdPanels;"<br/>";65;66;document.getElementById("ClientEvents").innerHTML;=;message;67}68function;EndRequest(sender,;args);{69;$get('ClientEvents').innerHTML;=;"PRM::;End;of;async;request.<br/>";70}7172//;Helper;functions.73function;Clear()74{75;$get('ClientEvents').innerHTML;=;"";76}77function;printArray(name,;arr)78{79;var;panels;=;name;'=';arr.length;80;if(arr.length;>;0)81;{82;panels;=;"(";83;for(var;i;=;0;;i;<;arr.length;;i;)84;{85;panels;=;arr[i].id;',';86;}87;panels;=;panels.substring(0,;panels.length;-;1);88;panels;=;")";89;}90;return;panels;91}92运行效果;查看代码;Event;Order;for;Common;Scenarios【一般事件发生顺序】事件触发顺序还是要看在页面中使用了什么控件和发生了什么类型的请求（初始化请求，传统回送或是异步回送）。这部分将描述几种常见情景的事件请求顺序。Initial;Request;【初始化请求】在一个页面初始化请求过程中，少量的客户端事件被引发。假设下面就是初始化请求的情景。・;页面包括一个;ScriptManager;控件，并且该控件的;SupportsPartialRendering;和;EnablePartialRendering;属性都为;true。・;请求是;GET;类型；・;服务器能正常响应。下面是客户端事件发生的顺序：1、初始化请求发生给服务器。2、客户端接收到响应。3、Application;实例引发;init;事件。4、Application;实例引发;load;事件。初始化事件仅在整个页面生命周期过程中的应用程序实例化时发生一次。它不会被后来的异步回送所引发。在初始化请求（注意是请求）期间，没有任何的;PageRequestManager;事件被引发。Asynchronous;Postback;【异步回送】一个异步回送发送了一些页面数据到服务器，并接收一个服务器端的响应，然后刷新页面的一部分。假定下面一个异步回送的场景：・;页面包括一个;ScriptManager;控件，并且该控件的;SupportsPartialRendering;和;EnablePartialRendering;属性都为;true。・;页面存在一个;UpdatePanel;控件，并且改控件的;ChildrenAsTriggers;属性值为;true。・;在;UpdatePanel;里面有一个按钮用于引发异步回送。・;成功地从服务器端获得响应。下面是客户端事件发生的顺序：1、点击;UpdatePanel;控件中的按钮时，引起了一个异步回送。2、PageRequestManager;实例引发了;initializeRequest;事件。3、PageRequestManager;实例引发了;beginRequest;事件。4、请求被发送到服务器。5、客户端接收到了响应。6、PageRequestManager;实例引发了;pageLoading;事件。7、PageRequestManager;实例引发了;pageLoaded;事件。8、Application;实例引发了;load;事件。9、PageRequestManager;实例引发了;endRequest;事件。请注意应用程序的;load;事件在;PageRequestManager;的;pageLoaded;事件之后，和;endRequest;事件之前。Multiple;Asynchronous;Postbacks;【多个异步回送】当之前的一个请求正在服务器端或浏览器中运行时，用户又发送了一个新的请求时，则发生了多个异步回送。假设下面的场景描述了多个异步回送的情况。・;页面包括一个;ScriptManager;控件，并且该控件的;SupportsPartialRendering;和;EnablePartialRendering;属性都为;true。・;页面包含一个;UpdatePanel;控件。・;在;UpdatePanel;中有一个引发异步回送的按钮控件被点击两次。第二次的点击发生在服务器端正在处理第一次点击发起的请求。・;获得了从服务器端返回的对第一次请求的响应。下面是客户端事件发生的顺序：1、点击;UpdatePanel;中的按钮引发了一次异步回送。2、PageRequestManager;实例引发了;initializeRequest;事件。3、PageRequestManager;实例引发了;beginRequest;事件。4、请求被发送到服务器。5、客户端接收到了响应。6、按钮被再次点击，引发了第二次异步回送。7、PageRequestManager;实例为第二次点击引发了;initializeRequest;事件。8、PageRequestManager;实例为第二次点击引发了;beginRequest;事件。9、第二次点击的请求北伐扫到了服务器。10、客户端接收到了第二次点击的响应。11、PageRequestManager;实例引发了;pageLoading;事件。12、PageRequestManager;实例引发了;pageLoaded;事件。13、Application;实例引发了;load;事件。14、PageRequestManager;实例引发了;endRequest;事件。默认的异步回送行为是最近发生的异步回送优先级较高。如果两个异步回送按顺序发生，并且第一个异步回送仍在浏览器处理中，则第一个回送被取消了。如果第一个回送已被发送到了服务器端，则服务器在第二个请求到来之前是不会返回第一个请求的。更多关于如何为异步回送设置优先级的详情请参考;Giving;Precedence;to;a;Specific;Asynchronous;Postback.Browsing;Away;from;a;Page;【浏览其它页】当用户从一个页面访问其它页面时，当前的页面会从浏览器中卸载，因此你可以操作;unload;事件来释放资源。假定下面模拟了这一场景。・;页面包括一个;ScriptManager;控件，并且该控件的;SupportsPartialRendering;和;EnablePartialRendering;属性都为;true。・;目标页面存在。下面是客户端事件发生的顺序：1、发动一个请求新页面的请求。2、浏览器获得请求新页面的响应。3、Application;实例引发;unload;事件。4、显示了新页面。如果在请求新页面时发生了错误，unload;事件依然会被引发，但是新页面不会被显示出来。