MagicAjax 使用介紹(翻譯+轉貼)

     本人的英文水平不高，翻譯中有錯的地方請指出。翻譯的不對的地方請見笑。
        主要是讓自己看的，所以知道是那個意思就是了。詞不達意的地方肯定會有不少。

Usage
用法

Table of Contents
目錄

Programming
設計

Handling an AjaxCall
操作 AjaxCall

Setting an Ajax refresh timer
設定Ajax定時重新整理

Controls
控制項

AjaxPanel
AjaxZone
ClientEventTrigger
KeyClientEventWrapper
AjaxPage and AjaxUserControl
AjaxHtmlAnchor and AjaxHtmlImage

MagicAjax attributes for ASP.NET controls
ASP.NET 控制項的 MagicAjax 屬性

Programming
設計

Handling an AjaxCall
AjaxCall操作

 

Depending on the PageStore Mode configuration option, the page's execution cycle will differ significantly (see Configuration Options).
依賴於頁面的Store狀態的選項, 頁面的執行循環將會不一致.(見到結構選項)

 For the default 'NoStore' mode, the page's execution cycle will be the same as a PostBack.
 對於預設值 'NoStore' 狀態，頁面的執行循環將會是等同於 PostBack 。

 You can distinguish if a PostBack or an AjaxCall occured, by checking the return value of the MagicAjaxContext.Current.
 你通過檢查 MagicAjaxContext.Current 的傳回值，能夠區分是通過 PostBack 或 AjaxCall來操作的。

IsAjaxCallForPage method.

Note:
注意:

 There is a MagicAjaxContext.Current.IsAjaxCall property that is true if the http request was originated by an AjaxCall, but the recommended method of checking whether an AjaxCall was invoked is by using IsAjaxCallForPage.
當MagicAjaxContext.Current.IsAjaxCall屬性如果為真,如果http請求通過ajaxCall開始了,但是檢查 AjaxCall 是否被調用的被推薦的方法是由使用 IsAjaxCallForPage屬性決定 。

 If the page is created because of a Server.
 因為頁面是在伺服器端產生。

Transfer call that occured during an AjaxCall, IsAjaxCallForPage will return false so that your page can execute as a normal page request.
發生在AjaxCall頁面轉移期間，IsAjaxCallForPage屬性將會返回"false"以便你的網頁能運行正常的請求。

The AjaxPage.IsAjaxCall property, that makes a call to IsAjaxCallForPage, is provided for convenience (see AjaxPage).
AjaxPage.IsAjaxCall 屬性,那作一個呼叫符號給 IsAjaxCallForPage, 被方便提供.(見到 AjaxPage)

MagicAjax sends javascript code to the client as a response to an AjaxCall.
MagicAjax 的AjaxCall通過Response發送 javascript 代碼到用戶端。

 If you want to send your custom javascript along with MagicAjax's, you can use the static functions of AjaxCallHelper.
 如果你想要連同 MagicAjax's 一起送你的自訂的javascript,你可以使用 AjaxCallHelper 的靜態方法。

 For example:
 舉例來說:

private void Button1_Click(object sender, System.EventArgs e)

{

AjaxCallHelper.WriteAlert ("Button1 was clicked.");

}

--------------------------------------------------------------------------------

Setting an Ajax refresh timer
設定 Ajax 定時重新整理

You can use the AjaxCallHelper.SetAjaxCallTimerInterval method to set a page wide timer that will invoke AjaxCalls at the intervals that you define.
你能使用 AjaxCallHelper.SetAjaxCallTimerInterval 方法設定頁將會在你定義的間隔喚起 AjaxCalls 的寬定時器。

 You can call it either at the initial page request or during an AjaxCall to initiate it or change the interval value.
 你也能在調用它的請求頁面開始之前或在 AjaxCall 期間改變定時器的值。

 If you call it with an interval value of zero, the timer will deactivate.
 如果你設定它的值為零，則定時器將不起作用。

Example:
例子:

private void Page_Load(object sender, System.EventArgs e)
{
if (!IsPostBack)
{

// Ajax refresh every 10 seconds
//Ajax 每 10 秒重新整理一下
MagicAjax.AjaxCallHelper.SetAjaxCallTimerInterval(10000);
}
}

Controls
控制項

 

AjaxPanel

This is the core control of the MagicAjax framework.
這是 MagicAjax 架構的核心控制項。

 
 The PostBack functionality of all the controls that are inside an AjaxPanel will be replaced by an AJAX callback (AjaxCall), unless defined otherwise.
 所有在 AjaxPanel 裡的控制項 PostBack 功能將會被一個 AJAX 回調 (AjaxCall) 代替, 除非以別的方式定義。

 AjaxPanel works like the ASP.NET Panel, its contents are visible on the designer, you can set all the WebControl attributes to it, change its Visible property etc.
 AjaxPanel 就如同ASP.NET的Panel一樣工作，在設計時，在它裡面的控制項是可見的,你能設定它的所有 WebControl 屬性, 改變它的可見度等等

 

Its AjaxCallConnection property can be set to:
它的 AjaxCallConnection 屬效能被設定成:

Asynchronous (Default)
非同步 (預設)

  The AjaxCall will be invoked in the background
  AjaxCall 將會在後台調用

Synchronous
同步的

  The client's browser will wait for the AjaxCall to finish
  客戶的瀏覽器將會等 AjaxCall調用完成

None
沒有

  Controls inside the AjaxPanel will invoke a normal PostBack
  AjaxPanel 裡的控制項將會使用正常的 PostBack

 

Its ExcludeFlags property determines which form elements should be excluded from posting to the server during an AjaxCall, thus reducing the AjaxCall traffic.
它的 ExcludeFlags屬性決定哪一個表單元素應該在 AjaxCall 期間不被發送到伺服器,如此減少 AjaxCall 通訊量。

 It sets the ExcludeFlags MagicAjax ASP.NET control attribute.
 設定Asp.Net的MagicAjax控制項的 ExcludeFlags 屬性。

 A child AjaxPanel automatically "inherits" the ExcludeFlags of its parent AjaxPanel.
 一個AjaxPanel的衍生類別將自動地 " 繼承 " 它的父類AjaxPanel的ExcludeFlags 。

 The child can mark more form elements to exclude through its ExcludeFlags property but it cannot send to the server form elements that have been marked for exclusion by its parent AjaxPanel.
 當有很多的表單元素時，可以通過設定 ExcludeFlags 屬性來排除它是否發送給伺服器，而且它不能夠發送在其父類中已經做了標記的表單元素給伺服器。

 

In order to reduce the amount of html needed to send to client, AjaxPanel defines individual 'html holders'.
為了要減少被需要對客戶送的 html 的數量， AjaxPanel 定義個體 'html 持有人' 。

 If the html of a holder changes during an AjaxCall, MagicAjax sends the whole html of the holder so that it can be reflected to the client's browser.

 如果用戶端的 html 在 AjaxCall 期間被改變, MagicAjax 將發送整個用戶端的 html，以便它能及時反映到客戶的瀏覽器。

 Every immediate WebControl child of an AjaxPanel is considered a separate holder, and one extra holder is defined for the literal and HtmlControls content of the AjaxPanel.

 AjaxPanel 的每一直接子類的WebControl都被是一個獨立的持有人，而且一個額外的持有人被定義為AjaxPanel的Literal的和 HtmlControls AjaxPanel。

 Thus, if the html of a WebControl, that is enclosed inside an AjaxPanel, changes, only the html of the particular WebControl will be sent to the client.

 因此, 如果 WebControl 的 html,那在 AjaxPanel ，變化裡被附上,只有特別的 WebControl 的 html 將會被送給客戶。

 

An AjaxPanel (child AjaxPanel) that is inside another AjaxPanel (parent AjaxPanel), define its html holders separately from its parent.
內部的另外 AjaxPanel(父AjaxPanel) 的 AjaxPanel( 子AjaxPanel),從它的父母分開的定義它的 html 持有人。

 The parent AjaxPanel will ignore the html of the child AjaxPanel;only the child AjaxPanel will be responsible for reflecting its holders on the client.
 父類的AjaxPanel將不理睬子類的AjaxPanel的html; 只有子類的 AjaxPanel將會負責處理子類的用戶端請求。

 Thus, you can reduce the traffic of AjaxCalls, by adding many AjaxPanels that define more and smaller html holders.
 因此，你能減少 AjaxCalls 的通訊資料量,由此可以增加並定義許多小的AjaxPanel的Html容器。

 For example, if you put a table inside an AjaxPanel and change one of its cells during an AjaxCall, the complete html of the table is going to be sent to the client.
 舉例來說，如果你在AjaxPanle中放入了一張表並在AjaxCall 期間改變了其中的一儲存格的內容,則表的全部 html 將被發送用戶端。

On the other hand, if you add an AjaxPanel for each cell, only the html of the contents of the changed cell will be sent to the client.
 另一方面，如果你在每個儲存格內放入一個AjaxPanel,則只有被改變的儲存格的內容的 html 將被送給用戶端。

 

In order to monitor the traffic of AjaxCalls that your page is producing, you can enable the tracing configuration option.
為了要檢測你自己的頁面上 AjaxCalls 產生的流量,你能夠使追蹤選項。

--------------------------------------------------------------------------------

AjaxZone

 

It's an AjaxPanel that has the MagicAjax attribute AjaxLocalScope set to true.
AjaxZone其實是AjaxPanel的MagicAjax屬性AjaxLocalScope設為true的ajaxPanel。

 It is provided for convenience and readability.
它提供方便性和易讀性。

 When an AjaxCall is invoked from a control inside an AjaxZone, only the values of the form elements that are contained inside this AjaxZone will be sent to the server and the server will check for changes and "reflect" only the AjaxPanels that are inside the AjaxZone.

 當AjaxZone 裡的控制項調用AjaxCall的時候, 只有包含這 AjaxZone裡的元素的值將會被發送伺服器和伺服器端的將只檢查在AjaxZone裡的AjaxPanels的表單元素的變化。

 This helps reduce the Ajax traffic and speed up a bit the server's response.
 這將有助於減少 Ajax 通訊量並可以快速反應伺服器的反饋。

 It's intented for isolated and independent portions of a page, like UserControls.
頁的隔離和獨立部分, 像 UserControls。

An AjaxZone can contain other AjaxZones.
AjaxZone 能包含其他的 AjaxZones 。

 A control belongs to the AjaxZone that is its immediate parent.
 控制項隸屬於它的父控制項的 AjaxZone 。

--------------------------------------------------------------------------------

ClientEventTrigger

Captures a client event of a control.
取得控制項的一個用戶端事件。

 The EventName property must be set to the client event (i.e. "focus", "change", etc.) and the ControlID property must be set to the ID of the control whose event you want to capture.
 事件名稱屬性必須被設定成客戶事件 (也就是 " 焦點 " ， " 變化 ", 等等)而且 ControlID屬性一定要設定證你想捕獲的用戶端事件的控制項的ID。

 The AjaxCall that will be invoked is dependent at the ClientEventTrigger's placement, not the placement of ControlID's control.
 AjaxCall的調用將是依賴的在 ClientEventTrigger's 的放置而不是 ControlID's 的控制項放置。

 For example, if the ClientEventTrigger is inside an AjaxPanel an AjaxCall will be invoked even if the ControlID's control is not inside an AjaxPanel.
 舉例來說，如果 ClientEventTrigger 在 AjaxPanel 裡 AjaxCall 將會被調用即使 ControlID's 的控制項不在 AjaxPanel 裡。

 The ClientEventTrigger must be inside the same NamingContainer (i.e. UserControl) as the ControlID's control.
 ClientEventTrigger 一定如同 ControlID's 的一般 NamingContainer(也就如 UserControl) 的控制項。

--------------------------------------------------------------------------------

KeyClientEventWrapper

Captures the KeyPress, KeyDown, and KeyUp client events of its inner controls.
取得控制項的 KeyPress ， KeyDown 和 KeyUp 客戶事件。

 The KeyPress event has the IE behaviour across all browsers (invoked when a character is typed or Enter is pressed).
 KeyPress 事件通過過所有的瀏覽器的 IE 行為。 ( 調用當一個在打字的時候鍵入的下壓類型)

--------------------------------------------------------------------------------

AjaxPage 和 AjaxUserControl

Making your pages and usercontrols inherit from AjaxPage and AjaxUserControl is not required;they're provided only for convenience.
建立你的頁面和 usercontrols可以從 AjaxPage 和 AjaxUserControl 繼承,但這不是必須的; 他們只被為了方便才提供。

 They expose the MagicAjax's stored page events (see Session/Cache PageStore modes) and provide the IsAjaxCall property that makes a call to MagicAjaxContext.Current.IsAjaxCallForPage.
 他們公布MagicAjax的儲存頁事件 (見Session/Cache PageStore modes) 和提供作一個MagicAjax的IsAjaxCall的屬性MagicAjaxContext.Current.IsAjaxCallForPage.。

 
--------------------------------------------------------------------------------

AjaxHtmlAnchor 和 AjaxHtmlImage

 

These controls are intented to be used only for the Session/Cache PageStore modes.
這些控制項只用在PageStore為Session/Cache的頁面模式。

 When these modes are selected, ASP.NET's HtmlAnchor and HtmlImage loose their href and src attributes during an AjaxCall.
當這些模式被選擇的時候,ASP.NET's 的 HtmlAnchor 和 HtmlImage 的 href 和 src 在 AjaxCall 期間將丟失。

AjaxHtmlAnchor and AjaxHtmlImage can be used in their place.
AjaxHtmlAnchor 和 AjaxHtmlImage 能被用於這些地方。

--------------------------------------------------------------------------------

MagicAjax attributes for ASP.NET controls
ASP.NET 控制項的 MagicAjax 屬性

 

You can add special attributes to ASP.NET controls that define how they will be handled by MagicAjax:
你能把特別的屬性加入 ASP.NET控制項中來定義他們將會如何被 MagicAjax 處理:

 

AjaxCall ("Async" or "Sync" or "None")
AjaxCall(" 非同步" 或 " 同步 " 或 " 沒有")

If you add the AjaxCall attribute with "Async"/"Sync" value to a control that has PostBack functionality (i.e. Button, LinkButton, CheckBox, etc.) the PostBack functionality of the control will be replaced by AJAX functionality, even if it is not contained inside an AjaxPanel.

如果你把AjaxCall的屬性和其值" Async"/" Sync " 加入到有PostBack 功能的控制項(如按鈕,選擇框等),此控制項的PostBack功能將會被 AJAX 功能代替,即使它不被包含在 AjaxPanel 容器裡。

 If you add the AjaxCall attribute with "None" value to a control that is inside an AjaxPanel, the control will perform a PostBack instead of an AjaxCall.
 如果你給在AjaxPanel內的控制項增加 AjaxCall 屬性和其值"None"， 對在 AjaxPanel 裡的控制評價,控制項將會使用 PostBack功能AjaxCall功能 。

 By adding the AjaxCall attribute, you override the AjaxCallConnection property of its parent AjaxPanel (if the AjaxPanel is set to Asynchronous, you can add AjaxCall with "sync" value to a control to make it perform a synchronous AjaxCall).
 通過增加 AjaxCall 屬性，你重寫它及其父類的 AjaxPanel 的 AjaxCallConnection 屬性。 (如果 AjaxPanel 被設定成非同步,你能在控制項啟動並執行同時添加 " 同步 " 的 AjaxCall 值)

 The effect of the AjaxCall attribute is applied to all the children of the control, so if you add it to a plain ASP.NET Panel, all the controls that are contained inside this Panel will get the effect of the AjaxCall attribute.

 AjaxCall 屬性效果適用於控制項的所有子類，因此，如果你簡單地把它加入到ASP.NET 面板,所有包含在這面板內部的控制項將會得到 AjaxCall 屬性的效果。

 

ExcludeFromPost ("true" or "false")

When an AjaxCall is invoked, the client sends the values of the form elements to the server as POST data.
當 AjaxCall 被調用的時候,客戶表單的元素的值將Post給伺服器。

If there is a control that is used only to display information and not to get input from the user, you can add the ExcludeFromPost attribute with "true" value and the value of this control will not be sent to the server.
如果這個控制項僅僅是用來顯示資料而且不需要讓使用者輸入資訊, 你給這個控制項的ExcludeFromPost屬性設為true,則這個控制項的值將不會發送到伺服器。

For example, if your page contains a readonly TextBox that is used to display chat messages, sending its contents for every AjaxCall is unnecessary traffic;you can avoid it by using the ExcludeFromPost attribute.

舉例來說，如果你的頁面中的唯讀文字框用來顯示資訊，則AjaxCall 發送它的內容是不必要的通訊; 你能通過使用 ExcludeFromPost 屬性來避免發送它的相關資訊。

 

AjaxLocalScope ("true" or "false")

Makes the control behave like an AjaxZone.
製作的控制項將有如 AjaxZone 一樣的行為表現。

ExcludeFlags (expression---運算式)

Determines which form elements will be excluded from posting to server during an AjaxCall.
決定哪些表單元素將會在 AjaxCall 的伺服器端執行期間被排除在外。

 These form elements will be excluded when an AjaxCall is invoked from the control or one of its children.
 當 AjaxCall從它的控制項或它的子控制項之一被調用的時候，這些表單元素將會被排除。

 It should be set to an arithmetic expression that has an integer as a result.
它設定了一個完整的數學表達應該能得到一個完整的結果。

 The javascript constants excfViewState, excfFingerprints, excfUserHidden, excfAllHidden, excfFormElements, excfAllElements can be used for convenience.

 javascript 常數 excfViewState ， excfFingerprints ， excfUserHidden ， excfAllHidden ， excfFormElements,excfAllElements 能方便的使用。

 

Example:
例子:

<asp:button excludeflags="excfFormElements | excfViewState" .....>

All the attributes can be added inside the control's tag statement or by code.
所有的屬效能在控制項的標籤陳述裡被增加或在後台代碼中添加。

 Their values, and consequently their function, can be changed during an AjaxCall.
 他們的值和他們的功能,能在 AjaxCall 期間被改變。

Example:
例子:

Button1.Attributes["ajaxcall"] = "async";