Ajax 选项 - Prototype JavaScript 框架

Xunxin Prototype API

previous page next page

Ajax 选项

本章描述所有核心选项（被所有 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 请查看说明

请求头可以使用下述两种方式进行传递：

  • 作为一个 object：使用属性来描述请求头。
  • 作为一个 array：偶数索引 (0, 2…) 元素表示头名称，奇数索引 (1, 3…) 元素表示对应的值。

Prototype 默认提供了一组预设的请求头，这些选项可以被重写，你也可以增加新的选项：

  • X-Requested-With 被设置为 'XMLHttpRequest'。
  • X-Prototype-Version 提供 Prototype 的当前版本号（如：1.5.0）。
  • Accept 默认为 'text/javascript, text/html, application/xml, text/xml, */*'
  • Content-type 基于 contentType 和 encoding 选项的值生成。
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 而言，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 对象刚被创建时调用。
onXYZ 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 对象刚被创建时调用。
previous page start next page