MagicAjax.NET Framework 是一套能大幅簡化 ASP.NET Ajax 開發的元件框架。以下整理其編程與控制項的核心用法。
頁面的執行週期會依 PageStore Mode 設定而有明顯差異。在預設的 'NoStore' 模式下,執行週期如同 PostBack。你可以透過 MagicAjaxContext.Current.IsAJaxCallForPage 方法的返回值,來判斷目前是 PostBack 還是 AjaxCall。
另外還有 MagicAjaxContext.Current.IsAJaxCall 屬性,當它為 true 時代表此 http 請求由 AjaxCall 引發;但官方建議改用 IsAJaxCallForPage 進行判斷。若頁面是因 AjaxCall 期間發生 Server.Transfer 而建立,IsAJaxCallForPage 會回傳 false,讓頁面得以作為一般請求執行。
若想在 MagicAjax 送回客戶端的 JavaScript 之外,一併送出自訂的 JavaScript,可使用 AjaxCallHelper 的靜態方法。例如:
private void Button1_Click(object sender, System.EventArgs e){
AjaxCallHelper.WriteAlert("Button1 was clicked.");
}
可利用 AjaxCallHelper.SetAjaxCallTimerInterval 方法,設定一個會定期觸發 AjaxCall 的頁面層級計時器。你可以在初始頁面請求或 AjaxCall 期間呼叫它;若傳入 0,則計時器停用。
private void Page_Load(object sender, System.EventArgs e){
if (!IsPostBack){
// 每 10 秒刷新一次
MagicAjax.AjaxCallHelper.SetAjaxCallTimerInterval(10000);
}
}
這是 MagicAjax 框架的核心控制項。放在 AjaxPanel 內的所有控制項,其 PostBack 功能都會被 Ajax callback(AjaxCall)取代。AjaxPanel 的用法類似 ASP.NET 的 Panel,內容可在設計器中檢視,也能設定所有 WebControl 屬性、變更 Visible 等。
其 AjaxCallConnection 屬性可設為:
ExcludeFlags 屬性可決定哪些表單元素在 AjaxCall 期間不送到伺服器,藉此降低流量。子 AjaxPanel 會繼承父 AjaxPanel 的 ExcludeFlags,但無法送出已被父層排除的元素。
此外,AjaxPanel 定義了獨立的「html 佔位符」:只有內容變動的佔位符才會被送回客戶端。因此,將頁面切分成較多、較小的 AjaxPanel,能有效減少傳輸量。例如把 table 放進 AjaxPanel 後改動其中一格,整個 table 的 HTML 都會被送出;但若為每個儲存格各加一個 AjaxPanel,就只會送出變動儲存格的內容。
本質上是將 AjaxLocalScope 屬性設為 true 的 AjaxPanel。當 AjaxCall 由 AjaxZone 內的控制項觸發時,只有該區域內的表單元素會被送到伺服器,且只更新該區域的 AjaxPanel,有助於降低流量、加快回應,適合用於 UserControl 這類獨立區塊。
用來攔截某控制項的用戶端事件。EventName 設為要攔截的事件(如 "focus"、"change"),ControlID 設為目標控制項的 ID。AjaxCall 是否觸發取決於 ClientEventTrigger 的位置,而非 ControlID 控制項的位置。
攔截內部控制項的 KeyPress、KeyDown、KeyUp 事件,其中 KeyPress 在所有瀏覽器上皆採 IE 行為(輸入字元或按下 Enter 時觸發)。
讓頁面與使用者控制項繼承自 AjaxPage、AjaxUserControl 並非必要,僅為方便而提供。它們會暴露 MagicAjax 儲存的頁面事件,並提供呼叫 IsAJaxCallForPage 的 IsAJaxCall 屬性。
僅建議用於 Session/Cache PageStore 模式。在此模式下,ASP.NET 的 HtmlAnchor 與 HtmlImage 會在 AjaxCall 期間遺失 href 與 src 屬性,可以這兩個控制項替代。
這些屬性既可直接寫入控制項標籤,也能透過程式碼設定,其值與功能可在 AjaxCall 期間動態變更。