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.
IsAjaxCallForPage方法

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.A child AjaxPanel automatically "inherits" the ExcludeFlags of its parent AjaxPanel.
设定Asp.Net的MagicAjax控件的 ExcludeFlags 属性。一个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. A control belongs to the AjaxZone that is its immediate parent.
AjaxZone 能包含其他的 AjaxZones 。控件隶属于它的父控件的 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";