prototype.js1.5.0开发者手册 译文+添加注释(四)关于ajax类的

本人辛苦翻译的,转载或引用请短信通知下,谢谢!

prototype.js1.5.0开发者手册 2007-09-22 by lin49940本人为学习的目的而翻译的

 

目录                                                      

11. Ajax 对象

        Ajax.Responders 对象

        Ajax.Base 类

        Ajax.Request 类

        options 参数对象

        Ajax.Updater 类

        Ajax.PeriodicalUpdater 类

 

top

Ajax 对象                                                                               

这个类是其他许多提供 AJAX 功能的类的基类和命名空间.

属性	类型	类别	描述
activeRequestCount	Number	instance	正在处理中的 AJAX 请求的数量

方法	类别	参数	描述
getTransport()	instance	(none)	返回一个新的 XMLHttpRequest 对象

top

Ajax.Responders 对象

继承 Enumerable

这个对象封装一个对象列表, 这些对象当跟Ajax有关系的事件发生时将被调用.  例如, 如果你想为Ajax操作设置一个全局异常处理程序, 你能用这个对象做到这点.

属性	类型	类别	描述
responders	Array	instance	被登记 AJAX 事件通知的对象列表

方法	类别	参数	描述
register(responderToAdd)	instance	responderToAdd: object with methods that will be called. 带有将被调用的方法的对象	在responderToAdd参数中,被传入的对象应该包含命名像AJAX事件(比如 onCreate, onComplete, onException, 等等)的方法. 当相应的事件发生时,所有被登记的对象中,如果有包含对应事件名的方法的对象,这个对象的方法将被调用.
unregister(responderToRemove)	instance	responderToRemove: object to be removed from the list.	在responderToRemove参数中, 被传入的对象将从已登记的对象列表中移除.
dispatch(callback, request, transport, json)	instance	callback: name of the AJAX event being reported, AJAX事件名, request: the Ajax.Request object responsible for the event, 负责事件的Ajax.Request对象, transport: the XMLHttpRequest object that carried (or is carrying) the AJAX call,已携带(或正携带)AJAX 请求的XMLHttpRequest对象, json: the X-JSON header of the response (if present), 响应的X-JSON头(如果存在)	遍历已登记的对象列表,查找带有在callback参数中指定方法的对象,然后每个查找到的对象的指定方法被调用, 这些方法会传入其他3个参数. 如果AJAX响应包含一个含有JSON内容的X-JSON HTTP头, 那它将被执行, 并传入到json参数中. 如果时onException事件, transport参数将被异常代替,而json参数将不被传入.

top

Ajax.Base 类

这个类被用作其他大部分在Ajax对象中定义的类的基类.

方法	类别	参数	描述
setOptions(options)	instance	options: AJAX options	设定AJAX操作想要的选项(options).
responseIsSuccess()	instance	(none)	返回 true 如果AJAX操作成功,否则为 false
responseIsFailure()	instance	(none)	与 responseIsSuccess() 相反。

top

Ajax.Request 类

继承 Ajax.Base

封装 AJAX 操作 

属性	类型	类别	描述
Events	Array	static	在AJAX操作中所有可能报告的事件/状态的列表. 这个列表包括: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 和 'Complete.'
transport	XMLHttpRequest	instance	携带AJAX操作的 XMLHttpRequest 对象。
url	String	instance	呼应 该请求 的目标URL

方法	类别	参数	描述
[ctor](url, options)	constructor 构造器,构造函数	url: the url to be fetched, 请求的url, options: AJAX options, AJAX 选项	创建这个对象的一个实例，它将在给定的选项下访问指定的url。 重要：如果选择的url受到浏览器的安全设置，他会一点作用也不起。 很多情况下，浏览器不会请求与当前页面不同主机(域名)的url。 你最好只使用本地url来避免限制用户配置他们的浏览器(谢谢Clay)
evalJSON()	instance	(none)	这个方法显然不会被外部调用。它在Ajax响应中含有X-JSON HTTP头时用于内部调用执行这些内容。
evalResponse()	instance	(none)	这也方法显然不会被外部调用，如果Ajax响应含有一个值为text/javascript的Cotent-Type头，那么这个方法就用被调用执行响应体。
header(name)	instance	name: HTTP header name, HTTP头的名	得到 AJAX 响应的任何HTTP头的内容. 这个方法只能在 AJAX 命令完成后调用.
onStateChange()	instance	(none)	这个方法通常不会被外部调用。 当AJAX请求状态改变的时候被这个对象自己调用。
request(url)	instance	url: url for the AJAX call, AJAX请求的url	这个方法通常不会被外部调用.已经在构造方法执行过程中调用了。
respondToReadyState(readyState)	instance	readyState: state number (1 to 4),状态数字 (1 到 4)	这个方法通常不会被外部调用。 当AJAX请求状态改变的时候被这个对象自己调用。
setRequestHeaders()	instance	(none)	这个方法通常不会被外部调用。 被这个对象自己调用来配置在HTTP请求要发送的HTTP报头。

top

options 参数对象

AJAX操作中一个重要的部分就是options 参数. 本质上没有options 类. 任何对象都可以被传入, 只要带有需要的属性.  通常会只为了AJAX调用创建匿名类.

属性	类型	默认值	描述
method	String	'post'	HTTP 请求方式
parameters	String or Object	''	在HTTP请求中传入的url格式的值列表(for example 'employee=john&month=11') 或者一个描绘parameters参数的类似hash对象 (for example {employee:'john', month:11}. 后面这个是前面版本所没有的. )
asynchronous	Boolean	true	指定是否做异步 AJAX 请求
postBody	String	undefined	在HTTP POST的情况下，传入请求体中的内容
requestHeaders	Array	undefined	和请求一起被传入的HTTP头部列表, 这个列表必须含有偶数个项目, 任何奇数项目是自定义的头部的名称, 接下来的偶数项目是这个该头部的字符串值. 例子:['my-header1', 'this is the value', 'my-other-header', 'another value'].(我挺奇怪的,干嘛它不用类似hash的对象呢)
encoding	String	'UTF-8'	在请求主体(特别是POST请求)中使用的字符编码. UTF-8足够应付绝大部分情况, 除非你清楚知道自己正在做什么, 那你可以使用其他的编码. (照我的理解应该是说, 如果你清楚知道字符编码的作用, 那你可以根据自己的实际情况使用不同的编码.这个属性是前面版本没有的)
contentType	String	'application/x-www-form-urlencoded'	设置Ajax请求的Content-Type HTTP头.(这个属性是前面版本没有的)
onXXXXXXXX	Function(XMLHttpRequest, Object)	undefined	在AJAX请求中, 当相应的事件/状态被触发的时候调用的自定义方法. 在这个option属性中"XXXXXXXX"有几个选择, 选择的范围是在Ajax.Request.Events 里面的状态, 和HTTP状态码(HTTP status codes). (例如 var myOpts = {on403:not Allowed, onComplete:showResponse, onLoaded:registerLoaded };).这个方法使用时会接收一个参数, 这个参数包括携带AJAX操作的XMLHttpRequest 对象, 这个方法还会再接收另一个参数,这个参数包含已执行的X-JSON响应的HTTP头. (跟以前的版本相比,onXXXX可以用HTTP状态码, 比如on200等,200大家应该很熟了吧,调用的方法貌似只用一个参数就行了, 如果用到了JSON可能就需要2个参数,下面的也一样.)
onSuccess	Function(XMLHttpRequest, Object)	undefined	当AJAX请求成功完成的时候调用的自定义方法. 这个方法将被传入一个参数,  这个参数是携带AJAX操作的XMLHttpRequest 对象, 这个方法还会传入另一个参数, 这个参数是包含已执行的X-JSON响应的HTTP头.(这个属性常用)
onFailure	Function(XMLHttpRequest, Object)	undefined	当AJAX请求完成但出现错误的时候调用的自定义方法. 这个方法将被传入一个参数,  这个参数是承载AJAX操作的 XMLHttpRequest 对象, 这个方法还会传入另一个参数, 这个参数是包含已执行的X-JSON响应的HTTP头.
onException	Function(Ajax.Request, exception)	undefined	当客户端执行的Ajax请求发生异常情况时调用的自定义函数, 这些异常情况可能无效响应或无效参数等等. 这个方法使用时将接收到两个参数, 包含异常Ajax操作的Ajax.Request对象和异常对象.
insertion	an Insertion class	undefined	一个能决定怎么样插入新内容的类. 只能应用于Ajax.Updater 对象, 如果没有特殊指定, 新内容将完全替换现有的内容.如果有Insertion衍生类被给定, 新内容将被添加到现有的内容中. 这个衍生类可以是 Insertion.Before, Insertion.Top, Insertion.Bottom, 或 Insertion.After. (这个方法跟1.40以前的版本很大的不同, 以前是只能插入文本而已.)
evalScripts	Boolean	undefined, false	决定是否当响应到达的时候执行其中的脚本块, 只在应用于Ajax.Updater 对象.
decay	Number	undefined, 1	决定是否当最后一次接收到的响应和前一次相同时, 在 Ajax.PeriodicalUpdater 对象中逐次降低刷新的频率,例如，如果设为2，后来的刷新和之前的结果一样, 这个Ajax.PeriodicalUpdater 对象将等待2个设定的刷新时间间隔进行下一次刷新. 如果又一次一样, 那么将等待4个刷新时间间隔, 等等. 不设定这个值，或者设置为1，将避免刷新频率变慢.
frequency	Number	undefined, 2	重复刷新的时间间隔(不是频率),以秒为单位. 只能应用于 Ajax.PeriodicalUpdater 对象.

top

Ajax.Updater 类

继承 Ajax.Request

当请求的url返回一段HTML而你想把它直接放置到页面的某个特定元素中的时候被用到.  如果url的返回<script> 的块并且想在接收到时就执行它的时候也可以使用该对象。含有脚本的时候使用evalScripts 选项。

属性	类型	类别	描述
containers	Object	instance	这个对象包含两个属性:AJAX请求成功执行的时候用到 containers.success, 否则的话用到 containers.failure.

方法	类别	参数	描述
[ctor](container, url, options)	constructor	container:可以是元素的id, 也可以是元素对象本身, 或者可以是带有2个属性的对象 - object.success AJAX请求成功的时候用到的元素(或者id) 否则用到object.failure 中设定的元素(或id), (例如:{success: 'elementID'}) url: 请求的url, options:AJAX options	创建一个用给定的选项请求给定的url的对象实例。
updateContent()	instance	(none)	这个方法通常不会被外部调用. 当响应到达的时候，被这个对象自己调用.  它会用HTML更新适当的元素或者调用在 insertion 选项中传入的方法-这个方法将被传入两个参数, 被更新的元素和响应文本.

top

Ajax.PeriodicalUpdater 类

继承  Ajax.Base

这个类重复生成并使用Ajax.Updater 对象来刷新页面中的一个元素。或者执行Ajax.Updater  可以执行的其它任务。更多信息参照 Ajax.Updater 参考 。

属性	类型	类别	描述
container	Object	instance	这个值将直接传入 Ajax.Updater 的构造方法.
url	String	instance	这个值将直接传入 Ajax.Updater 的构造方法.
frequency	Number	instance	两次刷新之间的时间间隔 (不是频率), 以秒为单位. 默认2秒.  当调用Ajax.Updater 对象的时候, 这个数将和当前的 decay属性 相乘.
decay	Number	instance	重复执行任务的时候保存被应用的当前衰退水平.
updater	Ajax.Updater	instance	最近使用的 Ajax.Updater对象
timer	Object	instance	到了下一次更新的时间通知对象更新,这个操作所用到的定时器。

方法	类别	参数	描述
[ctor](container, url, options)	constructor	container:可以是元素的id, 也可以是元素对象本身, 或者可以是带有2个属性的对象 - object.success AJAX请求成功的时候用到的元素(或者id) 否则用到object.failure 中设定的元素(或id), (例如:{success: 'elementID'}) url: 请求的url,   options: AJAX options	创建一个用给定的选项请求给定的url的对象实例。
start()	instance	(none)	这个方法通常不会被外部调用.对象为了开始周期性执行任务的时候调用的方法.
stop()	instance	(none)	对象为了停止执行周期性任务的时候调用的方法. 停止后, 对象将调用onComplete选项(有的话)中的callback函数.(在1.4 之前的版本这个方法是通常不会被外部调用的)
updateComplete()	instance	(none)	这个方法通常不会被外部调用. 当一次请求完成的时候后,被当前的Ajax.Updater使用,  它被用作计划下一次请求。
onTimerEvent()	instance	(none)	这个方法通常不会被外部调用.当到下一次更新时被内部调用.

 

 

 

 

上一部分: prototype.js1.5.0开发者手册 译文+添加注释(三)

查考文章: https://compdoc2cn.dev.java.net/prototype/html/prototype.js.cn.html

                  http://thinhunan.cnblogs.com/archive/2006/04/01/DeveloperNotesForPrototype.html

英文原版: http://www.sergiopereira.com/articles/prototype.js.html

国庆回家啦, 本来想2个星期完成的,看来是不行了