在 ASP.NET AJAX 中,Sys.WebForms.PageRequestManager 提供了掛接非同步回傳生命週期事件的機制。本文說明如何為請求加上開始與結束的事件處理常式,並附完整可運行的範例。
Sys.WebForms.PageRequestManager.instance.add_beginRequest(beginRequestHandler) Sys.WebForms.PageRequestManager.instance.remove_beginRequest(beginRequestHandler)
參數 beginRequestHandler 指定在請求開始之前要呼叫的函式。寫法如下:
Sys.WebForms.PageRequestManager.getInstance()
.add_beginRequest(BeginRequestHandler);
function BeginRequestHandler(sender, args)
{
// 這裡放你想做的事
}
函式的參數 args 是 Sys.WebForms.BeginRequestEventArgs 類別的實例,它包含兩個成員:
postBackElement 屬性——取得觸發回傳的 HTML 元素:var elem = args.get_postBackElement();
request 屬性——取得當前請求的實例物件:var request = args.get_request();
回傳值是 Sys.Net.WebRequest 類型的實例,這裡不深入說明,有興趣的讀者可自行查閱更多資料。
Sys.WebForms.PageRequestManager.instance.add_endRequest(endRequestHandler) Sys.WebForms.PageRequestManager.instance.remove_endRequest(endRequestHandler)
參數 endRequestHandler 指定在請求結束之後要呼叫的函式:
Sys.WebForms.PageRequestManager.getInstance()
.add_endRequest(EndRequestHandler);
function EndRequestHandler(sender, args)
{
// 你想加入的程式碼
}
參數 args 是 Sys.WebForms.EndRequestEventArgs 類別的實例。利用它可以取得請求期間發生的例外,以及請求回傳的 response 物件。
用 Visual Studio 2005 建立一個 ASP.NET AJAX-Enabled 網站,Default.aspx 的內容如下:
<%@ Page Language="C#" AutoEventWireup="true"
CodeFile="Default.aspx.cs" Inherits="_Default"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
<title>PageRequestManager beginRequest Example</title>
<style type="text/css">
body { font-family: Tahoma; }
div.AlertStyle
{
background-color: #FFC080;
top: 95%;
left: 1%;
height: 20px;
position: absolute;
visibility: hidden;
}
</style>
</head>
<body>
<form id="form1" runat="server">
<div><asp:ScriptManager ID="ScriptManager1" runat="server" />
<script type="text/javascript" language="javascript">
Sys.WebForms.PageRequestManager.getInstance()
.add_beginRequest(BeginRequestHandler);
Sys.WebForms.PageRequestManager.getInstance()
.add_endRequest(EndRequestHandler);
function BeginRequestHandler(sender, args)
{
var elem = args.get_postBackElement();
ActivateAlertDiv('visible', 'AlertDiv',
elem.value + '被單擊, 正在獲取系統時間');
}
function EndRequestHandler(sender, args)
{
ActivateAlertDiv('hidden', 'AlertDiv', '');
}
function ActivateAlertDiv(visstring, elem, msg)
{
var adiv = $get(elem);
adiv.style.visibility = visstring;
adiv.innerHTML = msg;
}
</script>
<asp:UpdatePanel ID="UpdatePanel1"
UpdateMode="Conditional" runat="Server">
<ContentTemplate>
<asp:Panel ID="Panel1" runat="server"
GroupingText="Update Panel">
最後一次更新時間:
<%= DateTime.Now.ToString()%>.
<br />
<asp:Button runat="server" ID="Button1"
Text="第一個按鈕" OnClick="ProcessClick_Handler" />
<asp:Button runat="server" ID="Button2"
Text="第二個按鈕" OnClick="ProcessClick_Handler" />
</asp:Panel>
</ContentTemplate>
</asp:UpdatePanel>
<div id="AlertDiv" class="AlertStyle">
</div></div></form></body>
</html>
Default.aspx.cs 的程式碼:
using System;
using System.Web;
using System.Web.UI;
public partial class _Default : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
}
protected void ProcessClick_Handler(object sender, EventArgs e)
{
System.Threading.Thread.Sleep(2000);
}
}
程式中刻意用 Thread.Sleep(2000) 拖慢伺服器回應,目的是讓「等待中」的狀態肉眼可見。真實專案裡請求通常幾十毫秒就回來了,你根本看不到提示訊息閃現——這也是為什麼做非同步回饋時,人為的延遲反而有助於驗證效果。
幾個實作細節值得注意。AlertStyle 這個 div 用 position: absolute 疊在頁面底部,初始 visibility: hidden;BeginRequestHandler 把它設為 visible 並寫入提示文字,EndRequestHandler 再設回 hidden。這是一組標準的「非同步進行中」視覺回饋模式。
另外,BeginRequestHandler 用 args.get_postBackElement() 取得觸發回傳的按鈕,再讀它的 value 顯示在訊息中——這樣使用者就知道是哪個操作正在處理。要注意的是,postBackElement 可能是按鈕,也可能是其他觸發回傳的元素,並非所有元素都有意義的 value,實務上應該做防禦性判斷。
最後,事件常式的註冊位置很關鍵。範例把它放在 ScriptManager 之後的 script 區塊中直接執行,這能確保 Sys.WebForms.PageRequestManager 已載入。若改放到 pageLoad 或 DOM ready 之後,反而可能因為時序問題而註冊失敗——這是非同步回根本質上就是「狀態會跑在你前面」的技術,處理事件時時時都要把時序放在心上。