prototype.js1.5.0开发者手册 译文+添加注释(二)

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

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

   

目录                                                           

6. 所有出现的 "?" 和 "□" 是什么？

7. 枚举Enumerable...哇！Damn！Wahoo！

        循环，Rudy样式

        让你的数组更加出色

8. 本人强烈推荐的图书

9. Prototype.js参考

        JavaScript 类的扩展

           对 Object 类的扩展

           对 Number 类的扩展

           对 Function 类的扩展

           对 String 类的扩展

           对 Array 类的扩展

           对 document DOM 对象的扩展

           对 Event 对象的扩展

 

 

 

top

 

所有出现的 "?" 和 "□" 是什么？                                                         

通过Ajax.Updater 对象你能写一些快速测试脚本去更新你的页面，它能很好的完成。运行脚本后的结果跟实际数据比较前，你可能以为完成了。

如果你的更新文本中存在非英文字母的字眼，那你的更新文本会显示不正常，其中会出现 " ?" 或者其他不规则的符号(通常所说的乱码)。

出现上面的情况，你可能第一个就怀疑是prototype.js方面的问题，当然，它很可能是。但这时请不用怀疑这个库。

问问你自己真正了解多少字符编码，代码页，浏览器如何处理它(这里的它应该指非英文字母)。

如果你的答案是肯定的，我打赌你能用自己的方式去解决这个问题(乱码问题)。

如果你是80%(注意这是作者粗略的估计)认为使用字符编码是理所当然的网络开发人员中的一个，那请你继续看下去。

我不会在这个话题上假装是权威，更不会给你一个完美解决这个问题的完整解释。相反地，你可以直接通过我所用和提供的提

示，找到符合自己实际情况下解决乱码问题的办法。

简单的说，解决方案将在下面的声明提到：任何浏览器都是期望适应你的服务，如果我们要更新页面中的文本内容包括unicode/utf-8字符，那我们最好让浏览器知道这点。

让我们先从简单的情况开始，假设你只是更新驻留在你的服务器上一个静态html文件中的页面文字。当你依靠你使用的文本编辑器创建这个文件，

很有可能这个文件被保存成ANSI ( 或者更甚者，非Unicode )格式。

这是很多文本编辑器的默认方式，尤其是源代码编辑器，因为文件将会比较小，而使用 Unicode 字符编辑源代码是相当不正常的。

假设你的服务器上有命名为static-content.html的文件，下面代码是它的内容。你把这个文件保存为ANSI 格式。（注意里面有非英文字符）

<div>
    Hi there, José. Yo no hablo español.
div>

更新你的主页用类似下面的片断。

<script>...
    function updateWithFile()...{
        var url = 'static-content.html';
        var pars = '';
        var myAjax = new Ajax.Updater(
                'placeholder', url, 
                ...{method: 'get', parameters: pars});
    }
script>
<div id="placeholder">(this will be replaced)div>
<input id="btn" value="Test With Static File"  
                 onclick="updateWithFile()" type="button"/>

当你点击例子中的按钮，static-content.html文件将被检索，非英文字符将会被" ? "或其他字符替换。

显示的文本将会是像这样 "Hi there, Jos?. Yo no hablo espa?ol." 或 "Hi there, Jos?Yo no hablo espa?"，是哪一个取决于你的浏览器。

在这种情况下，解决的办法是简单的，把静态文件简单地保存为一个适当的格式。让我们把这个文件保存为UTF-8的格式，

重新运行脚本( 任何正规的文本编辑器都会有个"另存为"的选项 )。现在你应该可以看到正确的文本了( 如果不是，你的浏览器可能有缓冲旧版本，尝试用不同的文件名 )。

如果你使用不是静态页面，如果它由一些应用框架( 如asp.net，php，甚至是perl )动态生成的，确定生成HTML页面的代码能在适当的编码和代码页中生成文本，

并包括一个通知header在HTTP响应头中。每个平台有不同的方式做到这一点，但他们都非常相似。

举例来说，在asp.net 中，你可以在web.config  中设置全局环境，而默认配置已经能在第一时间很好的避免了这个问题。在你的web.config 中应该已经下面这段代码了。

<globalization requestEncoding="utf-8" responseEncoding="utf-8" />

在经典的asp 3.0中 ，你可以使用以下代码解决这个问题。

Response.CodePage = 65001
Response.CharSet = "utf-8" 

在php语法添加像下面的响应头。

php header('Content-Type: text/html; charset=utf-8'); ?>

无论在那种情况下，你的最终目的都是把像下面一样HTTP头发送到响应中。

Content-Type: text/html; charset=utf-8 

在上面的例子中我们是使用了UTF-8编码，但如果你想使用其他的编码，你能很方便的改动它。

top

 

枚举Enumerable...哇！Damn！Wahoo！                                          

对于循环我们应该很熟悉啦。正如你所知，自己建立一个Array对象，用相同类型的元素( elements )填充这个对象，

再建一个循环管理结构（例如for,foreach,while)通过索引( index )数字来连续访问每一个元素( element )，再通过这个元素( element )做一些操作。

当你想到这时，你会发现几乎每次写循环代码你都会迟早用到一个Array对象。如果Array对象能够提供更多的功能给它们的迭代器( iterations )使用不是很好吗？

确实是这样，事实上很多的编程语言都在它们的Array或其它类似的结构中（如Collections,Lists）提供一些这样的功能。

好了，prototype.js了给我们一个 Enumerable对象，它实现了很多和迭代数据进行交互的窍门。

和原有的JS对象相比prototype.js更上一层楼，它通过Enumerable 的所有函数对 Array 类 扩展。

top

循环，Rudy样式

在标准的javascript中，如果你想把一个array中的所有elements连续显示出来，像下面代码那样写就很好了：

< script > ...
    function showList()...{
        var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Maggie'];
        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', 'Maggie'];
        simpsons.each( function(familyMember)...{
            alert(familyMember);
        });
    }

你可能会想“非常奇怪的方式...相对旧的，这种语法太怪异了”。哦，在上面的例子，确实没有什么惊人的发生。毕竟在这个简

单得要死例子中，也没有太多要改变的。尽管如此，请继续读下去。

在继续下面内容之前，你注意到那个被做为一个参数传递给 each 函数的函数？我们把它理解成迭代器( iterator )函数。

top

 让你的数组更加出色

就像我们上面提到的，在你的array 中所有的元素普遍都是类型相同，使用相同的属性和方法。让我们看看我们能怎样通过我们

新的更有效率的Arrays发挥迭代器( iterator)函数的优势。

下面的代码表明了怎样根据规则找到某个元素( 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);"   />  

现在让我们再下一城，看看我们怎样过滤 Arrays 中的元素，然后从每个元素中找到我们想要的成员。

< 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)...{
            //we'll just assume for now that external links
            // do not have a '#' in their url
            return link.href.indexOf('#') >= 0;
        });
        //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 参考。

top

 本人强烈推荐的图书                                                    

一些好书是值得向其他人传达的。下面的书在我学习充分地创建AJAX应用程序所需的新技能时对我的帮助很大，并且巩固了我已

经掌握的技能。我认为好书是值得花钱的，在很长的时间里它对你是有好处的。

 

 中的脚本块,

并执行这些代码块。

(如var a='都移除的字符串

stripTags() instance (none) 返回一个把所有的HTML或XML标记都移除的字符串。

sub(pattern,

     replacement [, count])

instance

pattern: string or regular expression

      being searched.

replacement: string, or Function(strings[])

to produce the replacements.  

count: 设置执行替换的次数-默认为1.      

       number or replacements

       to perform - defaults to 1.

跟gsub作用很类似，

不过这个方法可以通过第三个参数count设置替换的次数.

(e.g.:var s='the name of the gay';

alert(s.sub("the","a"));//显示:a name of the gay,

如果是alert(s.sub("the","a",2));

//则显示:a name of a gay,

替换操作执行了2次)

toArray() instance (none)

把字符串分割为一个个字符，

然后放到一个字符串数组(Array)中.

(e.g.:如var a='abc';var ca = a.toArray();

alert(ca);//显示:a,b,c。而ca是数组[a,b,c])

toQueryParams()

或toQueryParams([separator])

instance

(none)

separator:作为分割标志的符号，

如果这个参数为空，默认为'&'

把查询字符串分解到一个联合数组(Array)中，

这个联合数组通过参数的名称进行索引(跟Hash很像).

(e.g.:var aa = 'a=123&b=bb';
var bb=aa.toQueryParams();

alert(bb['a']);//显示:123,

alert(bb['b'];//显示:bb,

原文档没写这个方法有参数，

但是这个方法是可以用到参数的，

例如:aa='a=123!b=bb'),

aa.toQueryParams('!');

alert(bb['a']);//显示:123,

alert(bb['b']);//显示:bb.

truncate(length [, truncation]) instance

length: maximum length of

          the resulting string.

          结果字符串的最大长度.

truncation: string used to replace

the last characters

of the resulting

string - defaults to '...'

  替换结果字符串后面字符的字符串，

默认为'...'

被用来控制一个字符串的所需最大长度.

万一某个字符串需要被截短去控制最大长度，

truncation参数中的给定文本是用来替换后面字符的.

(e.g.: var s='123456790';

alert(s.truncate(5)); //displays '12...',

如果不想用...,

可以这样s.truncate(5,'???') ;//变为'12???')

underscore() instance (none)

把一个驼峰式字符串转换为一个带下划线格式的字符串.

例如：s='Namespace::MyClass123';

alert(s.underscore());

//显示'namespace/my_class123' ).

这个方法貌似直接支持Ruby on Rails功能性标识。

unescapeHTML() instance (none)

跟escapeHTML()作用相反

 

top

对 Array 类的扩展

 从一开始，Array类就继承自Enumerable 类，所以所有在Enumerable 对象中定义的可使用的方法Array对象都可以使用。除此之外，下面列出的方法也是被应用到的。

方法	类别	参数	描述
clear()	instance	(none)	清空数组并返回数组.(源数组被清空)
compact()	instance	(none)	返回一个不包括源array中null或undefined元素的array, 此方法不改变源array。
first()	instance	(none)	返回数组的第一个元素.
flatten()	instance	(none)	返回一个扁平的一维数组. 这个整平操作在发现数组每个元素中存在也是数组的元素时, 也包括这些元素(为数组的元素)的子元素是数组时启用, 通过递归的方式把元素数组的子元素返回到数组中. (这个方法不改变源数组)
indexOf(value)	instance	value: what you are looking for.	如果给定的参数value的值在数组中被找到, 返回这个value在数组中的位置(以0为起点).  如果没被找到,返回-1.
inspect()	instance	(none)	覆盖inspect(), 返回一个反映数组Array及其元素精细格式的字符串表现. (e.g.:var a=['a','b','c']; var c= a.inspect(); alert(a+" and "+c); //显示：a,b,c and ['a','b','c'] 。 这个方法不改变源数组的)
last()	instance	(none)	返回数组的最后一个元素.
reverse([applyToSelf])	instance	applyToSelf: indicates if the array              itself should also be reversed. 这个布尔值参数指出,源数组是否也倒转次序. (默认值是true,源数组倒转次序, 如果为false,源数组将不变.)	返回倒转了次序的数组. 如果没有给出参数或者参数为true, 源数组本身将被改变.否则源数组将保持不变.
shift()	instance	(none)	返回数组的第一个元素并把它从数组中移除, 减少源数组的长度1(length-1)。 (注意这个方法有两个作用, 第一是返回第一个元素， 第二是移除第一个元素， 数组长度减1。 e.g.:var a=['a','b','c']; alert(a.length);//显示:3; var b = a.shift(); alert(b+" and "+a+":now length "+a.length); //显示:a and b,c:now length 2）
without(value1 [, value2 [, .. valueN]])	instance	value1 ... valueN: values to be excluded if present in the array.	返回一个把参数列表中 包含的元素从源Array中排除的Array. 这个方法不改变源Array本身.

让我们看看上面的一些方法在实战中的运用。

<script>
var A = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' ];
alert(A.inspect()); // "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']"
var B = A.without('e','f' );
alert(B.inspect()); // "['a', 'b', 'c', 'd', 'g', 'h']"
alert(A.inspect()); // did not change A: "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']"
A.push(null );
A.push('x' );
A.push(null );
A.push('y' );
alert(A.inspect()); // "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', null, 'x', null, 'y']"
A =  A.compact();
alert(A.inspect()); // "['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'x', 'y']"
var e =  A.shift();
alert(e); // "a" 
alert(A.inspect()); // "['b', 'c', 'd', 'e', 'f', 'g', 'h', 'x', 'y']"
alert(A.indexOf('c')); // 1
alert(A.first()); // 'b'
alert(A.last()); // 'y'
A.clear();
alert(A.inspect()); // "[]"
A = ['a', 'b', 'c' ];
B = A.reverse(false );
alert(B.inspect()); // "['c', 'b', 'a']"
alert(A.inspect()); // A left untouched: "['a', 'b', 'c']"
A.reverse(true );
alert(A.inspect()); // "['c', 'b', 'a']"    
A = ['a', 'b',  ['c1','c2','c3'] , 'd',  ['e1','e2' ]  ];
B =  A.flatten();
alert(B.inspect()); // "['a','b','c1','c2','c3','d','e1','e2']"        
alert(A.inspect()); // unchanged: "['a','b',['c1','c2','c3'],'d',['e1','e2']]"        
script>

  top

对 documentDOM 对象的扩展

方法	类别	参数	描述
getElementsByClassName(className [, parentElement])	instance	className: name of a CSS       class associated with the elements,       关联在元素上的CSS类名, parentElement: object or id of the element that contains the elements being retrieved. 包含被找到的子元素的对象或元素的id.	返回所有关联特定CSS类名的元素. 如果给定parentElement(父元素id), 将在整个document主体中搜索.

 

 top

对 Event 对象的扩展

属性	类型	描述
KEY_BACKSPACE	Number	8: 常量，退格(Backspace)键的代码.
KEY_TAB	Number	9: 常量，Tab键的代码.
KEY_RETURN	Number	13: 常量，回车键的代码.
KEY_ESC	Number	27: 常量， Esc键的代码。
KEY_LEFT	Number	37: 常量，左箭头键的代码。
KEY_UP	Number	38: 常量，上箭头键的代码。
KEY_RIGHT	Number	39: 常量，右箭头键的代码。
KEY_DOWN	Number	40: 常量，下箭头键的代码。
KEY_DELETE	Number	46: 常量，删除(Delete)键的代码。
observers:	Array	缓存的观察者的列表，这个对象内部具体实现的一部分。

 

Method	Kind	Arguments	Description
element(event)	static	event:事件对象	返回引发这个事件的元素。
isLeftClick(event)	static	event:事件对象	如果鼠标左键单击返回true。
pointerX(event)	static	event:事件对象	返回鼠标指针在页面上的x坐标。
pointerY(event)	static	event:事件对象	返回鼠标指针在页面上的y坐标。
stop(event)	static	event:事件对象	用这个方法来中止事件的默认行为和暂停事件的传播。
findElement(event, tagName)	static	event:事件对象, tagName:指定标记的名字	从触发事件的元素开始, 在DOM树中向上查找指定标记名称的元素, 返回找到的第一个元素.
observe(element, name,               observer, useCapture)	static	element:对象或者对象id, name: 事件名(如'click', 'load',等等), observer:处理这个事件的方法(evt), useCapture: 如果为true, 在捕捉到事件的阶段处理事件, 如果为false则在bubbling阶段处理.	添加一个事件处理程序方法到事件中. (添加的处理程序方法定义,像function(evt), evt是当前的事件对象, 在处理程序方法中调用其他Event方法, evt将是这些方法的事件对象.)
stopObserving(element, name,                       observer, useCapture)	static	element:对象或者对象id, name:事件名(如'click'), observer:正在处理事件的方法, useCapture:如果为true,在捕捉到事件的阶段处理事件, 如果为false则在bubbling阶段处理.	从事件中移除一个事件处理程序.
_observeAndCache(element, name,                       observer, useCapture)	static		私有方法，不用管它。
unloadCache()	static	(none)	私有方法，不用管它。清除内存中的所有缓存的观察者。

 

让我们看看怎样用这个对象添加一个事件处理程序到window对象的load事件中。

< script > ...
       Event.observe(window,'load',page_loaded,false);

     function  page_loaded(evt)  ... {
       Event.observe('parent_node','click',item_clicked,false);
    }
    
     function  item_clicked(evt) ... {
        var child = Event.element(evt);   //返回触发事件的元素
        alert('The child node with id=' + child.id + ' was clicked');
        Event.stop(evt); //avoid another call related to 'parent_node' itself
    }
script >     
...
< div  id ="parent_node" >
     < div  id ="child1" > First div >
     < div  id ="child2" > Second div >
     < div  id ="child3" > Third div >
div >        

 

---

 

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

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

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

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