Ajax.Updater
new Ajax.Updater(container, url[, options])
执行一个 AJAX 请求,并将响应内容更新到指定容器。
Ajax.Updater
是一个特殊的 Ajax.Request
: 后者所具备的功能,前者同样拥有。如果你不熟悉 Ajax.Request
,请先阅读与之相关的文档,然后再回到本章。
一个简单的样例
new Ajax.Updater('items', '/items', {
parameters: { text: $F('text') }
});
注意时序
更新完成后,onComplete
回调将会被调用。
附加选项
因为 Ajax.Updater
的目标是使用 AJAX 请求所返回的响应文本更新指定 DOM 元素(容器)的内容,因此, 除公用选项外,它还具有一些新的特定选项:
选项 | 默认值 | 描述 |
---|---|---|
evalScripts | false | 指出是否执行响应文本中包含的 <script> 元素下的脚本。 |
insertion | None | 默认情形下,通过 Element.update 将指定容器的内容替换为响应文本。你可能希望插入响应文本到已有的内容中,在 1.6.0 以前的版本, 你必须传入一个有效的 Insertion ,例如 Insertion.Bottom 。在 1.6.0 中,不再推荐使用这种标记方法。 现在,你只需简单的传入 'top' ,'bottom' ,'before' 或 'after' 即可。 |
在下面的样例中,假设需要通过一个 AJAX 返回的 XHTML 片断创建新的条目,并放置到列表容器已有内容的后面:
new Ajax.Updater('items', '/items',
{ parameters: { text: $F('text') },
insertion: Insertion.Bottom
});
关于 evalScripts
和脚本块定义
如果你使用 evalScripts: true
,那么所有的 <script>
块将被执行。 执行的意思不是仅仅将脚本放置在页面中,而是将它们的内容直接传递给原生的 eval()
函数,因此需要注意两点:
- 脚本块中脚本的作用域被限定在 Prototype 内部,在脚本块中使用
var
定义的变量在执行后马上被销毁,页面上其它地方的脚本永远无法访问到它。
译注:若要使用脚本块返回可在页面其它地方使用的变量,请直接使用变量名,而不要用 var 定义或预先声明,如myVariant = 'this is a example'
。 - 如果你在脚本块中定义了函数,你需要实际的创建它,否则页面上其它地方的脚本无法访问这个函数, 这意味着下面的脚本不会执行:
//如果是通过 Ajax.Updater 处理,这种类型的脚本不能工作:
function coolFunc() {
// Amazing stuff!
}
需要使用下面的语法(译注:请注意,coolFunc
前面没有 var
):
//如果通过 Ajax.Updater 处理,需要这种类型的脚本才会正常工作
coolFunc = function() {
// Amazing stuff!
}
对于初学者而言,这是一个常见的陷井,因此,请注意!
使用单一的容器,或者在 success/failure 时使用不同的容器?
上面所有的样例都假定无论请求成功还是失败,都将响应更新到同一个容器。有时,你可能希望只有在请求成功时才更新内容, 或者在请求失败时更新到另一个容器。
为达到这个目的,需要为 container
参数传递一个 DOM 元素的替代对象,替代对象必须具有 success
属性,属性值为请求成功时需要更新的容器。如果你同时提供 failure
属性,则当请求失败时会更新该属性指定的容器。
下述代码中,仅在请求成功时才更新容器:
new Ajax.Updater({ success: 'items' }, '/items', {
parameters: { text: $F('text') },
insertion: Insertion.Bottom
});
下面的样例假设请求失败后在响应文本中会返回一条错误信息,并将错误信息更新到另一个元素(可能是一个状态区域)。
new Ajax.Updater({ success: 'items', failure: 'notice' },
'/items',
{ parameters: { text: $F('text') }, insertion: Insertion.Bottom }
);