prototype.js开发者手册
对应版本1.4.0
last update: March 30th 2006
中文版:THIN
最后更新:2006-3-31
看到一个很好的东西在国内没有被很多人使用起来,实在是不爽,所以花了很大功夫把这个手册翻译成中文,由于这篇文章很长,所以,翻译的工作量很大而且有些地方英文版也没有说清楚,虽得查看源代码,好在不是坚持做完了,大家鼓励下啊!^o^
prototype.js是一个非常优雅的javascript基础类库,对javascript做了大量的扩展,而且很好的支持Ajax,国外有多个基于此类库实现的效果库,也做得很棒。
prototype.js不仅是一个有很大实用价值的js库,而且有很高的学习价值,所以我强烈建议B/S开发人员和对JS开发感兴趣的朋友去浏览一些它的源代码,其中有很多的珠玑,你绝对会觉得读它的源代码是一种享受,当然要读得懂,呵呵。
网上也有人写过1.3版的源码解读,大家可以找来看看。不过1.4版做了很大的扩充,所以希望有朋友写出1.4版的源码解读。
几点说明:
prototype.js是什么?
万一你没有使用过大名鼎鼎的prototype.js,那么让我来告诉你,prototype.js是由Sam Stephenson写的一个javascript类库。这个构思奇妙,而且兼容标准的类库,能帮助你轻松建立有高度互动的非官方参考
在阅读这个文档时,熟悉Ruby的开发者将会注意到Ruby的一些内建类和本类库扩展实现之间非常相似。
相关文章
Advanced JavaScript guide.
一些实用的函数
这个类库带有很多预定义的对象和实用函数,这些东东的目的显然是把你从一些重复的打字中解放出来 。
使用$()方法
$() 方法是在DOM中使用过于频繁的 document.getElementById() 方法的一个便利的简写,就像这个DOM方法一样,这个方法返回参数传入的id的那个元素。
比起DOM中的方法,这个更胜一筹。你可以传入多个id作为参数然后 $() 返回一个带有所有要求的元素的一个 Array 对象。
<HTML> <HEAD> <TITLE> Test Page </TITLE> <script src="prototype-1.3.1.js"></script> <script> function test1() { var d = $('myDiv'); alert(d.innerHTML); } function test2() { var divs = $('myDiv','myOtherDiv'); for(i=0; i<divs.length; i++) { alert(divs[i].innerHTML); } } </script> </HEAD> <BODY> <div id="myDiv"> <p>This is a paragraph</p> </div> <div id="myOtherDiv"> <p>This is another paragraph</p> </div> <input type="button" value=Test1 onclick="test1();"><br> <input type="button" value=Test2 onclick="test2();"><br> </BODY> </HTML>
另外一个好处是,这个函数能传入用string表示的对象ID,也可以传入对象本身,这样,在建立其它能传两种类型的参数的函数时非常有用。
使用$F()函数
$F()函数是另一个大收欢迎的“快捷键”,它能用于返回任何表单输入控件的值,比如text box,drop-down list。这个方法也能用元素id或元素本身做为参数。
<script>
function test3()
{
alert( $F('userName') );
}
</script>
<input type="text" id="userName" value="Joe Doe"><br>
<input type="button" value=Test3 onclick="test3();"><br>
使用$A()函数
$A()函数能把它接收到的单个的参数转换成一个Array对象。
这个方法,结合被本类库扩展了的Array类,能方便的把任何的可枚举列表转换成或拷贝到一个Array对象。一个推荐的用法就是把DOM Node Lists转换成一个普通的Array对象,从而更有效率的进行遍历,请看下面的例子。
<script> function showOptions(){ var someNodeList = $('lstEmployees').getElementsByTagName('option'); var nodes = $A(someNodeList); nodes.each(function(node){ alert(node.nodeName + ': ' + node.innerHTML); }); } </script> <select id="lstEmployees" size="10" > <option value="5">Buchanan, Steven</option> <option value="8">Callahan, Laura</option> <option value="1">Davolio, Nancy</option> </select> <input type="button" value="Show the options" onclick="showOptions();" >
使用 $H() 函数
$H()函数把一些对象转换成一个可枚举的和联合数组类似的Hash对象。
<script>
function testHash()
{
//let's create the object
var a = {
first: 10,
second: 20,
third: 30
};
//now transform it into a hash
var h = $H(a);
alert(h.toQueryString()); //displays: first=10&second=20&third=30
}
</script>
使用$R()函数
$R()是new ObjectRange(lowBound,upperBound,excludeBounds)的缩写。
跳到ObjectRange 类文档可以看到一个关于此类的完整描述. 此时,我们还是先来看一个例子以展示这个缩写能代替哪些方法吧。其它相关的一些知识可以在Enumerable 对象文档中找到。
<script>
function demoDollar_R(){
var range = $R(10, 20, false);
range.each(function(value, index){
alert(value);
});
}
</script>
<input type="button" value="Sample Count" onclick="demoDollar_R();" >
使用Try.these()函数
Try.these() 方法使得实现当你想调用不同的方法直到其中的一个成功正常的这种需求变得非常容易, 他把一系列的方法作为参数并且按顺序的一个一个的执行这些方法直到其中的一个成功执行,返回成功执行的那个方法的返回值。
在下面的例子中, xmlNode.text在一些浏览器中好用,但是xmlNode.textContent在另一些浏览器中正常工作。 使用Try.these()方法我们可以得到正常工作的那个方法的返回值。
<script>
function getXmlNodeValue(xmlNode){
return Try.these(
function() {return xmlNode.text;},
function() {return xmlNode.textContent;)
);
}
</script>
Ajax对象
上面提到的共通方法非常好,但是面对它吧,它们不是最高级的那类东西。它们是吗?你很可能自己编写了这些甚至在你的脚本里面有类似功能的方法。但是这些方法只是冰山一角。
我很肯定你对prototype.js感兴趣的原因很可能是由于它的AJAX能力。所以让我们解释当你需要完成AJAX逻辑的时候,这个包如何让它更容易。
Ajax 对象是一个预定义对象,由这个包创建,为了封装和简化编写AJAX 功能涉及的狡猾的代码。 这个对象包含一系列的封装AJAX逻辑的类。我们来看看其中几个类。
使用Ajax.Request类
如果你不使用任何的帮助程序包,你很可能编写了整个大量的代码来创建XMLHttpRequest对象并且异步的跟踪它的进程, 然后解析出响应 然后处理它。当你不需要支持多于一种类型的浏览器时你会感到非常的幸运。
为了支持 AJAX 功能。这个包定义了 Ajax.Request 类。
假如你有一个应用程序可以通过url http://yoursever/app/get_sales?empID=1234&year=1998与服务器通信。它返回下面这样的XML 响应。
<?xml version="1.0" encoding="utf-8" ?> <ajax-response> <response type="object" id="productDetails"> <monthly-sales> <employee-sales> <employee-id>1234</employee-id> <year-month>1998-01</year-month> <sales>$8,115.36</sales> </employee-sales> <employee-sales> <employee-id>1234</employee-id> <year-month>1998-02</year-month> <sales>$11,147.51</sales> </employee-sales> </monthly-sales> </response> </ajax-response>
用 Ajax.Request对象和服务器通信并且得到这段XML是非常简单的。下面的例子演示了它是如何完成的。
<script> function searchSales() { var empID = $F('lstEmployees'); var y = $F('lstYears'); var url = 'http://yoursever/app/get_sales'; var pars = 'empID=' + empID + '&year=' + y;var myAjax = new Ajax.Request( url, { method: 'get', parameters: pars, onComplete: showResponse });} function showResponse(originalRequest) { //put returned XML in the textarea $('result').value = originalRequest.responseText; } </script> <select id="lstEmployees" size="10" onchange="searchSales()"> <option value="5">Buchanan, Steven</option> <option value="8">Callahan, Laura</option> <option value="1">Davolio, Nancy</option> </select> <select id="lstYears" size="3" onchange="searchSales()"> <option selected="selected" value="1996">1996</option> <option value="1997">1997</option> <option value="1998">1998</option> </select> <br><textarea id=result cols=60 rows=10 ></textarea>
你注意到传入 Ajax.Request构造方法的第二个对象了吗? 参数{method: 'get', parameters: pars, onComplete: showResponse} 表示一个匿名对象的真实写法。他表示你传入的这个对象有一个名为 method 值为 'get'的属性,另一个属性名为 parameters 包含HTTP请求的查询字符串,和一个onComplete 属性/方法包含函数showResponse。
还有一些其它的属性可以在这个对象里面定义和设置,如 asynchronous,可以为true 或 false 来决定AJAX对服务器的调用是否是异步的(默认值是 true)。
这个参数定义AJAX调用的选项。在我们的例子中,在第一个参数通过HTTP GET命令请求那个url,传入了变量 pars包含的查询字符串, Ajax.Request 对象在它完成接收响应的时候将调用showResponse 方法。
也许你知道, XMLHttpRequest在HTTP请求期间将报告进度情况。这个进度被描述为四个不同阶段:Loading, Loaded, Interactive, 或 Complete。你可以使 Ajax.Request 对象在任何阶段调用自定义方法 ,Complete 是最常用的一个。想调用自定义的方法只需要简单的在请求的选项参数中的名为 onXXXXX 属性/方法中提供自定义的方法对象。 就像我们例子中的 onComplete 。你传入的方法将会被用一个参数调用,这个参数是 XMLHttpRequest 对象自己。你将会用这个对象去得到返回的数据并且或许检查包含有在这次调用中的HTTP结果代码的 status 属性。
还有另外两个有用的选项用来处理结果。我们可以在onSuccess 选项处传入一个方法,当AJAX无误的执行完后调用, 相反的,也可以在onFailure选项处传入一个方法,当服务器端出现错误时调用。正如onXXXXX 选项传入的方法一样,这两个在被调用的时候也传入一个带有AJAX请求的XMLHttpRequest对象。
我们的例子没有用任何有趣的方式处理这个 XML响应, 我们只是把这段XML放进了一个文本域里面。对这个响应的一个典型的应用很可能就是找到其中的想要的信息,然后更新页面中的某些元素, 或者甚至可能做某些XSLT转换而在页面中产生一些HTML。
在1.4.0版本中,一种新的事件回传外理被引入。如果你有一段代码总是要为一个特殊的事件执行,而不管是哪个AJAX调用引发它,那么你可以使用新的Ajax.Responders对象。
假设你想要在一个AJAX调用正在运行时,显示一些提示效果,像一个不断转动的图标之类的,你可以使用两个全局事件Handler来做到,其中一个在第一个调用开始时显示图标,另一个在最后一个调用完成时隐藏图标。看下面的例子。
<script>
var myGlobalHandlers = {
onCreate: function(){
Element.show('systemWorking');
},
onComplete: function() {
if(Ajax.activeRequestCount == 0){
Element.hide('systemWorking');
}
}
};
Ajax.Responders.register(myGlobalHandlers);
</script>
<div id='systemWorking'><img src='spinner.gif'>Loading...</div>
更完全的解释,请参照 Ajax.Request 参考 和 Ajax选项参考。
使用Ajax.Updater类
如果你的服务器的另一端返回的信息已经是HTML了,那么使用这个程序包中 Ajax.Updater 类将使你的生活变得更加得容易。用它你只需提供哪一个元素需要被AJAX请求返回的HTML填充就可以了,例子比我写说明的更清楚。
<script> function getHTML() { var url = 'http://yourserver/app/getSomeHTML'; var pars = 'someParameter=ABC';var myAjax = new Ajax.Updater( 'placeholder', url, { method: 'get', parameters: pars });} </script> <input type=button value=GetHtml onclick="getHTML()"> <div id="placeholder"></div>
你可以看到,这段代码比前面的例子更加简洁,不包括 onComplete 方法,但是在构造方法中传入了一个元素id。 我们来稍稍修改一下代码来描述如何在客户端处理服务器段错误成为可能。
我们将加入更多的选项, 指定处理错误的一个方法。这个是用 onFailure 选项来完成的。我们也指定了一个 placeholder 只有在成功请求之后才会被填充。为了完成这个目的我们修改了第一个参数从一个简单的元素id到一个带有两个属性的对象, success (一切OK的时候被用到) 和 failure (有地方出问题的时候被用到) 在下面的例子中没有用到failure属性,而仅仅在 onFailure 处使用了 reportError 方法。
<script>
function getHTML()
{
var url = 'http://yourserver/app/getSomeHTML';
var pars = 'someParameter=ABC';
var myAjax = new Ajax.Updater( {success: 'placeholder'}, url, { method: 'get', parameters: pars, onFailure: reportError });} function reportError(request) { alert('Sorry. There was an error.'); } </script> <input type=button value=GetHtml onclick="getHTML()"> <div id="placeholder"></div>
如果你的服务器逻辑是连同HTML 标记返回JavaScript 代码, Ajax.Updater对象可以执行那段JavaScript代码。为了使这个对象对待响应为JavaScript,你只需在最后参数的对象构造方法中简单加入evalScripts: true属性。但是值得提醒的是,像这个选项名evalScripts暗示的,这些脚本会被执行,但是它们不会被加入到Page的脚本中。“有什么区别?”,可能你会这样问。我们假定请求地址返回的东东像这样:
<script language="javascript" type="text/javascript"> function sayHi(){ alert('Hi'); } </script> <input type=button value="Click Me" onclick="sayHi()">
如果你以前这样尝试过,你知道这些脚本不会如你所期望的那样工作,原因是这段脚本会被执行,但像上面这样的脚本执行并不会创建一个名叫sayHi的函数,它什么也不做。如果要创建一个函数,我们应当把代码改成下面这个样子:
<script language="javascript" type="text/javascript">sayHi = function(){ alert('Hi'); };</script> <input type=button value="Click Me" onclick="sayHi()">
为什么我们在上面的代码中不使用var关键字来声明这个变量呢(指sayHi ),因为那样做创建出来的函数将只是当前脚本块的一个局部变量(至少在IE中是这样)。不写var关键字,创建出来的对象的作用域就是我们所期望的window。
更多相关知识,请参看 Ajax.Updater reference 和options reference.
枚举... 噢!噢!
你知道,我们都是这样来做循环的,建一个Array,用elements组织它们,再建一个循环结构(例如for,foreach,while)通过index数字来访问每一个element,再用这个element做一些动作。
当你想到这时,你会发现几乎每次写循环代码你都会迟早用到一个Array。那么,如果Array对象能够提供更多的功能给它们的迭代器使用不是很爽吗?确实是这样,事实上很多的编程语言都在它们的Array或其它类似的结构中(如Collections,Lists)提供一些这样的功能。
现在好了,prototype.js了给我们一个 Enumerable对象,它实现了很多和可迭代数据进行交互的窍门。和原有的JS对象相比prototype.js更上一层楼,它对 类s扩展了所有枚举要用的函数。
循环, Ruby样式的
在标准的javascript中,如果你想把一个array中的所有elements显示出来,你可以像下面代码这样写得很好:
<script> function showList(){ var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];for(i=0;i<simpsons.length;i++){ alert(simpsons[i]); }} </script> <input type="button" value="Show List" onclick="showList();" >
使用我们新的最好的朋友,prototype.js,我们可以把它生写成这样
function showList(){ var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];simpsons.each( function(familyMember){ alert(familyMember); });}
你可能会想“非常奇怪的方式...相对旧的,这种语法太怪异了”。哦,在上面的例子,确实什么也没有,在这个简单得要死例子中,也没有改变太多啊,尽管如此,请继续读下去。
在继续下面内容之前,你注意到那个被做为一个参数传递给each函数的函数?我们把它理解成迭代器函数。
Your arrays on steroids
就如我们上面提到的,把你的Array中的elements当成相同的类型使用相同的属性和函数是很通用(Common,不知该翻译成通用还是庸俗)的。让我们看看怎么样利用我们新的马力强劲的Arrays的迭代功能吧。
依照标准找到一个element。
<script> function findEmployeeById(emp_id){ var listBox = $('lstEmployees') var options = listBox.getElementsByTagName('option'); options = $A(options); var opt = options.find( function(employee){ return (employee.value == emp_id); }); alert(opt.innerHTML); //displays the employee name } </script> <select id="lstEmployees" size="10" > <option value="5">Buchanan, Steven</option> <option value="8">Callahan, Laura</option> <option value="1">Davolio, Nancy</option> </select> <input type="button" value="Find Laura" onclick="findEmployeeById(8);" >
现在我们再下一城,看看如何过滤一个Array中的元素,从每个元素中得到我们想要的成员。
<script> function showLocalLinks(paragraph){ paragraph = $(paragraph); var links = $A(paragraph.getElementsByTagName('a')); //find links that do not start with 'http' var localLinks = links.findAll( function(link){ var start = link.href.substring(0,4); return start !='http'; }); //now the link texts var texts = localLinks.pluck('innerHTML'); //get them in a single string var result = texts.inspect(); alert(result); } </script> <p id="someText"> This <a href="http://othersite.com/page.html">text</a> has a <a href="#localAnchor">lot</a> of <a href="#otherAnchor">links</a>. Some are <a href="http://wherever.com/page.html">external</a> and some are <a href="#someAnchor">local</a> </p> <input type=button value="Find Local Links" onclick="showLocalLinks('someText')">
上面的代码仅仅是一点小小的实践让人爱上这种语法。请参看 Enumerable和Array的所有函数
Enumerable
用上、下边界描述一个对象区域。
Property | Type | Kind | Description |
---|---|---|---|
start | (any) |
range的下边界 | |
end | (any) | instance | range的上边界 |
exclusive | Boolean | instance | 决定边界自身是不是range的一部分。 |
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](start, end, exclusive) | constructor | start: the lower bound, end: the upper bound, exclusive: include the bounds in the range? | 创建一个range对象,从start生成到end,这里要注意的是,start和end必段类型一致,而且该类型要有succ()方法。 |
include(searchedValue) | searchedValue: value that we are looking for | 检查一个value是不是在range中。 |
The Class object
在这个程序包中 Class 对象在声明其他的类时候被用到 。用这个对象声明类使得新类支持 initialize() 方法,他起构造方法的作用。
看下面的例子
//declaring the class
var MySampleClass = Class.create();
//defining the rest of the class implmentation
MySampleClass.prototype = {
initialize: function(message) {
this.message = message;
},
showMessage: function(ajaxResponse) {
alert(this.message);
}
};
//now, let's instantiate and use one object
var myTalker = new MySampleClass('hi there.');
myTalker.showMessage(); //displays alert
Method | Kind | Arguments | Description |
---|---|---|---|
create(*) | (any) | 定义新类的构造方法。 |
The Ajax object
这个对象被用作其他提供AJAX功能的类的根对象。
Property | Type | Kind | Description |
---|---|---|---|
activeRequestCount | Number | instance | 正在处理中的Ajax请求的个数。 |
Method | Kind | Arguments | Description |
---|---|---|---|
getTransport() | (none) | 返回新的XMLHttpRequest 对象。 |
Enumerable
这个对象维持一个在Ajax相关事件发生时将被调用的对象的列表。比如,你要设置一个全局钩子来处理Ajax操作异常,那么你就可以使用这个对象。
Property | Type | Kind | Description |
---|---|---|---|
responders | Array | 被注册到Ajax事件通知的对象列表。 |
Method | Kind | Arguments | Description |
---|---|---|---|
register(responderToAdd) | instance | responderToAdd: object with methods that will be called. | 被传入参数的对象应包含名如Ajax事件的系列方法(如onCreate,onComplete,onException)。通讯事件引发所有被注册的对象的合适名称的函数被调用。 |
unregister(responderToRemove) | instance | responderToRemove: object to be removed from the list. | 从列表中移除。 |
dispatch(callback, request, transport, json) | instance | callback: name of the AJAX event being reported, request: the Ajax.Request object responsible for the event, transport: the XMLHttpRequest object that carried (or is carrying) the AJAX call, json: the X-JSON header of the response (if present) | 遍历被注册的对象列表,找出有由callback参数决定的那个函数的对象。然后向这些函数传递其它的三个参数,如果Ajax响应中包含一个含有JSON内容的X-JSON HTTP头,那么它会被热行并传入json参数。如果事件是onException,那么transport参数会被异常代替,json不会传递。 |
AJAX options
Ajax.Base
封装 AJAX 操作
Property | Type | Kind | Description |
---|---|---|---|
Events | Array | static | 在AJAX操作中所有可能报告的事件/状态的列表。这个列表包括: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 和 'Complete'。 |
transport | XMLHttpRequest | instance | 承载AJAX操作的 XMLHttpRequest 对象。 |
url | 请求的URL。 |
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](url, options) | constructor | url: the url to be fetched, options: AJAX options | 创建这个对象的一个实例,它将在给定的选项下请求url。onCreate事件在调用constructor事被激发。 重要: 如果选择的url受到浏览器的Insertion.Before, Insertion.Top, Insertion.Bottom, 或 Insertion.After. 只能应用于Ajax.Updater 对象. |
evalScripts | Boolean | undefined, false | 决定当响应到达的时候是否执行其中的脚本块,只在 Ajax.PeriodicalUpdater 对象。 |
Ajax.Request
当请求的url返回一段HTML而你想把它直接放置到页面中一个特定的元素的时候被用到。 如果url的返回<script> 的块并且想在接收到时就执行它的时候也可以使用该对象。含有脚本的时候使用 evalScripts 选项。
Property | Type | Kind | Description |
---|---|---|---|
containers | Object | instance | 这个对象包含两个属性:AJAX请求成功执行的时候用到 containers.success , 否则的话用到 containers.failure 。 |
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](container, url, options) | constructor | container:this can be the id of an element, the element object itself, or an object with two properties - object.success element (or id) that will be used when the AJAX call succeeds, and object.failure element (or id) that will be used otherwise. url: the url to be fetched, options: AJAX options | 创建一个用给定的选项请求给定的url的一个实例。 |
updateContent() | (none) | 这个方法通常不会被外部调用。 当响应到达的时候,被这个对象自己调用。 它会用HTML更新适当的元素或者调用在 insertion 选项中传入的方法-这个方法将被传入两个参数, 被更新的元素和响应文本。 |
继承自Ajax.Base
这个类重复生成并使用 Ajax.Updater 对象来刷新页面中的一个元素。或者执行 Ajax.Updater 可以执行的其它任务。更多信息参照 Ajax.Updater 参考 。
Property | Type | Kind | Description |
---|---|---|---|
container | Object | 这个值将直接传入Ajax.Updater的构造方法。 | |
url | String | instance | 这个值将直接传入Ajax.Updater的构造方法。 |
frequency | Number | instance | 两次刷新之间的间隔 (不是频率) ,以秒为单位。 默认2秒。 This 当调用 Ajax.Updater 对象的时候,这个数将和当前的 decay 相乘。 |
decay | instance | 重负执行任务的时候保持的衰败水平。 | |
updater | Ajax.Updater | instance | 最后一次使用的 Ajax.Updater 对象 |
timer | Object | instance | 通知对象该下一次更新时用到的JavaScript 计时器。 |
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](container, url, options) | constructor | container:this can be the id of an element, the element object itself, or an object with two properties - object.success element (or id) that will be used when the AJAX call succeeds, and object.failure element (or id) that will be used otherwise. url: the url to be fetched, options: AJAX options | 创建一个用给定的选项请求给定的url的一个实例。 |
start() | (none) | 这个方法通常不会被外部调用。 对象为了开始周期性执行任务的时候调用的方法。 | |
stop() | instance | (none) | 使对象停止执行周期任务。停止后,如果有onComplete选项,那么引发callback。 |
updateComplete() | instance | (none) | 这个方法通常不会被外部调用。 被当前的 Ajax.Updater 使用,当一次请求结束的时候,它被用作计划下一次请求。 |
onTimerEvent() | instance | (none) | 这个方法通常不会被外部调用。当到下一次更新时被内部调用。 |
Enumerable
在一个对象中表示CSS class names的集合。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element) | constructor | element: any DOM element object or id | 创建一个对象,给出对象的CSS class names被表现在这个ClassNames对象中。 |
add(className) | className: a CSS class name | 把CSS class name包含进对象的class names 列表。 | |
remove(className) | instance | className: a CSS class name | 从对象的class names列表中移除className |
set(className) | instance | className: a CSS class name | 设定对象CSS class name为className,移除其它class names。 |
Abstract.Insertion
在给定元素开始标记的前面插入HTML。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element, content) | element: element object or id, content: HTML to be inserted | 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。 |
下面的代码
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script> new Insertion.Before('person', 'Chief '); </script>
将把 HTML 变为
<br>Hello, Chief <span id="person" style="color:red;">Wiggum. How's it going?</span>
Abstract.Insertion
在给定元素第一个子节点位置插入 HTML。内容将位于元素的开始标记的紧后面。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element, content) | element: element object or id, content: HTML to be inserted | 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。 |
下面的代码
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script> new Insertion.Top('person', 'Mr. '); </script>
将把 HTML 变为
<br>Hello, <span id="person" style="color:red;">Mr. Wiggum. How's it going?</span>
Abstract.Insertion
在给定元素最后一个子节点位置插入 HTML。内容将位于元素的结束标记的紧前面。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element, content) | constructor | element: element object or id, content: HTML to be inserted | Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion. |
The following code
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.Bottom('person', " What's up?"); </script>
Will change the HTML to
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going? What's up?</span>
Abstract.Insertion
在给定元素结束标记的后面插入HTML。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element, content) | constructor | element: element object or id, content: HTML to be inserted | Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion. |
The following code
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.After('person', ' Are you there?'); </script>
Will change the HTML to
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> Are you there?
Abstract.TimedObserver
Abstract.TimedObserver 的一个实现类用来监听表单输入项目的值的变化。当你想监听一个没有带报告值变化事件的元素的时候使用这个类。否则的话使用 Form.Element.EventObserver 类代替。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element, frequency, callback) | constructor | element: element object or id, frequency: interval in seconds, callback: function to be called when the element changes | 继承自 Abstract.TimedObserver. 创建一个监听元素值属性的对象。 |
getValue() | (none) | 返回元素的值。 |
Abstract.TimedObserver
Abstract.TimedObserver 的一个实现类用来监听表单中任何数据项的值的变化。当你想监听一个没有带报告值变化事件的元素的时候使用这个类。 否则的话使用类Form.EventObserver 代替。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](form, frequency, callback) | constructor | form: form object or id, frequency: interval in seconds, callback function to be called when any data entry element in the form changes | 继承自 Abstract.TimedObserver. 创建一个监听表单变化的对象。 |
getValue() | (none) | 返回所有表单数据的一系列值。 |
Form.Element.Observer 类代替。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](element, callback) | constructor | element: element object or id, callback: function to be called when the event happens | 继承自 Abstract.EventObserver。 创建一个监听元素值属性的对象。 |
getValue() | (none) | 返回元素的值。 |
Form.Observer 类代替。
Method | Kind | Arguments | Description |
---|---|---|---|
[ctor](form, callback) | constructor | form: form object or id, callback: function to be called when any data entry element in the form changes | 继承自 Abstract.EventObserver。 创建一个监听元素值属性的对象。 |
getValue() | (none) | 返回所有表单数据的一系列值。 |
Position 对象 (预备文档)
这个对象提供许多和元素位置相关的方法。
Method | Kind | Arguments | Description |
---|---|---|---|
prepare() | (none) | 调整 deltaX 和 deltaY 属性来协调在滚动位置中的变化。 记得在页面滚动之后的任何调用的withinIncludingScrolloffset 之前调用这个方法。 | |
realOffset(element) | element: object | 返回这个元素的正确滚动偏差的 Array 对象, 包括所有影响元素的滚动偏差。结果数组类似 [total_scroll_left, total_scroll_top] | |
cumulativeOffset(element) | instance | element: object | 回这个元素的正确滚动偏差的 Array 对象, 包含任何被放置的父元素强加偏差。结果数组类似 [total_offset_left, total_offset_top] |
within(element, x, y) | instance | element: object, x and y: coordinates of a point | 测试给定的点的坐标是否在给定的元素的外部矩形范围之内。 |
withinIncludingScrolloffsets(element, x, y) | instance | element: object, x and y: coordinates of a point | 测试给定的点的坐标是否在给定的元素的外部矩形范围之内(包含scroll offsets)。 |
overlap(mode, element) | mode: 'vertical' or 'horizontal', element: object | 在调用这个方法之前需要调用within() 。这个方法返回0.0到1.0之间的数字,来表示坐标在元素重叠的分数。 举个例子,如果元素是一个边长是100px的正方形的DIV,并且位于(300, 300), 然后 within(divSquare, 330, 330);overlap('vertical', divSquare); 会返回 0.10,意思是那个点位于DIV顶部边框以下 10% (30px) 的位置上。 | |
clone(source, target) | instance | source: element object or id, target: element object or id | 改变目标元素的大小尺寸和位置与源元素的相同。 |