Ajax 选项
在 Ajax
命名空间中的所有请求对象都共享一系列公共的选项和回调函数。 回调函数在请求生命周期的各个阶段被调用,并且它们具有相同的参数列表。在请求期间,参数所包括的选项被不断的传递到请求中。
公用选项
选项 | 默认值 | 描述 |
---|---|---|
asynchronous |
true |
指出 XMLHttpRequest 是否是异步的。因为同步的方式在某种程度上具有一定的不确定性, 通常不是一个好的选择,应尽量避免使用。 |
contentType |
'application/x-www-form-urlencoded' |
请求头部的 Content-Type (译注:form 元素的 enctype 属性)设置。可能你想要发送的内容是 XML 格式而不是常规的 URL 编码格式,这时,你就需要重新设置这个选项。 |
encoding |
'UTF-8' |
请求内容的编码方式。最好使用默认的设置,但是如果发生一些离奇的编码问题,你必须修正它, 使你页面中与编码相关的部分和服务器上保持一致。 |
method |
'post' |
HTTP 的请求方式。另一个常用的方式是 'get' 。在专用于 Ruby On Rails 时,Prototype 也能响应其它的谓词(例如 'put' 和 'delete' ,事实上,这些谓词是在 'post' 方式上增加了一个额外的参数 '_method' )。 |
parameters |
'' |
请求的参数。在 'get' 方式下,参数被编码并附加到 URL 中(译注:URL 中的查询字符串), 其它方式下,参数被插入到请求数据主体中。参数的类型可以是一个 URL 编码字符串,也可以是任意一个与 Hash 兼容的对象(Prototype 会自动将兼容对象的属性名称和属性值转换为名值对作为参数)。 |
postBody |
None | 在 'post' (实际应用中可能会有一些变化,上面的 method 选项对此做了描述)方式下,指定请求发送的内容。如果该参数为空,则使用parameters 选项填充内容。 |
requestHeaders |
请查看说明 |
请求头可以使用下述两种方式进行传递:
Prototype 默认提供了一组预设的请求头,这些选项可以被重写,你也可以增加新的选项:
|
evalJS |
true | 如果服务器返回的 content-type 是下述类型之一:application/ecmascript , application/javascript , application/x-ecmascript , application/x-javascript , text/ecmascript , text/javascript , text/x-ecmascript 或 text/x-javascript ,并且 请求遵循 SOP (译注:中文说明)Prototype 默认会自动执行 Ajax.Response#responseText 内容中的 Javascript 代码。如果你想要在任何情况下,均强制执行内容中的 Javascript 代码,请将该选项设为 'force' ,为完全阻止代码的执行,设为 'false' 。译注:该选项设为 'true' 或 'force' 时,会执行返回内容中的 Javascript 代码,并且代码不需要置于 <script> 和 </script> 标签中。例如返回的内容值为 alert('Hello world') , Prototype 也会执行该语句,而不是把它当作一个普通的字符串。'force' 和 'true' 的区别在于: 若返回内容的 content-type 不是上述列出的类型,'force' 会强制把返回内容当作 Javascript 代码执行,而 'true' 不会执行。例如返回的 content-type 为text/plain 时,'force' 会执行,而 'true' 不执行。 |
evalJSON |
true | 如果服务器返回数据的 content-type 类型为 application/json ,则自动解析执行 Ajax.Response#responseText 的内容,然后填充到Ajax.Response#responseJSON 。 如果请求不遵循 SOP (译注:中文说明)规范,在执行前会对内容进行过滤。如果你希望强制执行,请将该选项设置为 'force' ,为完全阻止代码的执行,设为 'false' 。 |
sanitizeJSON |
本地请求为false ,否则为true |
在运行之前过滤 Ajax.Response#responseText 的内容。 |
公用回调函数
用于单独的对象实例时(译注:“单独的对象实例”是相对 Ajax.Responders
是一个全局的对象,面向所有通过 Prototype 发出的 Ajax 请求),所有的回调函数(除 onException
外)均包含两个参数:XMLHttpRequest
对象以及执行 X-JSON
响应头后的结果(如果有的话,可为 null
)。
在 Ajax.Request 中,从另外一个角度描述了回调函数在请求生命周期中调用的先后顺序以及回调函数的互斥性。
回调函数 | 描述 |
---|---|
onCreate (v1.5.1) |
当 Ajax.Request 对象被初始化后触发。回调发生在参数和 URL 被处理之后,第一次调用 XHR(XMLHttpRequest) 对象的方法之前。 |
onComplete |
在请求生命周期的最未端被触发,用于在请求完成后,与指定状态代码相关的回调函数(译注:onXYZ) 也被调用后,处理一些可能需要的善后事宜。 |
onException |
当 XHR 发生错误时触发。有一个约定俗成的函数签名方式:第一个参数是请求本身(如 Ajax.Request 实例),第二个参数是异常对象。 |
onFailure |
在一个请求完成后,若存在相应的状态代码,但状态代码不是 2xy 系列,将调用 onFailure。 如果已经定义了与指定状态代码相关的回调函数,该回调将不被执行。回调发生在 onComplete 之前。译注:参见状态代码表 |
onInteractive |
(不保证可用)服务器响应的数据通常是通过多个包来发送的,当每次接收到其中一部分数据(但不是最后一部分)时触发该回调。 |
onLoaded |
(不保证可用)当基础的 XHR 对象被创建,连接已打开,并准备发送实际的请求时,触发该回调。 |
onLoading |
(不保证可用)在基础的 XHR 对象创建过程中,连接被打开时,触发该回调。 |
onSuccess |
当一个请求完成时,没有返回状态代码,或者返回的状态代码是 2xy 系列,调用该回调。 如果已经定义了与指定状态代码相关的回调函数,该回调将不被执行。回调发生在 onComplete 之前。译注:参见状态代码表 |
onUninitialized |
(不保证可用)当 XHR 对象刚被创建时调用。 |
on XYZ |
XYZ 表示 XMLHttp 请求返回的状态代码。当响应刚完成,并且返回的状态代码与你指定的 XYZ 值相同时调用该回调。它会阻止 onSuccess /onFailure 执行。 回调发生在 onComplete 之前。译注:参见状态代码表 |
响应回调
当用于响应器(responders,译注:Ajax.Responders)时,所有被调用的回调函数(除 onException
和 onCreate
外)都具有三个参数:请求本身(例如 Ajax.Request
的实例),XMLHttpRequest
对象和执行 X-JSON
响应头后的结果(如果有,可为 null
)。它们运行在响应的上下文中,this
引用被绑定到响应本身。
回调函数 | 描述 | |
---|---|---|
onCreate |
当一个请求对象通过 Ajax 命名空间创建,并且已经设置好它的参数,但它的 XHR 连接尚未打开的时候触发该回调。它具有两个参数:请求的对象和基础的 XHR 对象。 |
|
onComplete |
在请求生命周期的最未端被触发,用于在请求完成后,与指定状态代码相关的回调函数(译注:onXYZ) 也被调用后,处理一些可能需要的善后事宜。 | |
onException |
当 XHR 发生错误时触发。有一个约定俗成的函数签名方式:第一个参数是请求本身(如 Ajax.Request 实例),第二个参数是异常对象。 | |
onInteractive |
(不保证可用)服务器响应的数据通常是通过多个包来发送的,当每次接收到其中一部分数据(但不是最后一部分)时触发该回调。 | |
onLoaded |
(不保证可用)当基础的 XHR 对象被创建,连接已打开,并准备发送实际的请求时,触发该回调。 | |
onLoading |
(不保证可用)在基础的 XHR 对象创建过程中,连接被打开时,触发该回调。 | |
onUninitialized |
(不保证可用)当 XHR 对象刚被创建时调用。 |