ExtJS API文档的使用方法详解

      以前都是使用jQuery。感觉jQuery的文档写的非常棒！每一个API都有解释，有例子代码。！试着非常得劲！怎一个爽子了得！

      现在工作的公司使用ExtJS，所以就要学习一下ExtJS。API文档少不了要经常查。但是，ExtJS的文档真是不敢恭维。尽管ExtJS很好很强大！不过，这两天上网无意中查看了一批文章，里面讲解了一下ExtJS文档的使用方法，感觉不错。把主要内容摘录出来，和大家分享一下！

      API中，都是针对每个类来讲解的，每个类中又基本上都由以下4部分组成：

1. Config Options , 配置项
2. Public Properties, 公共属性
3. Public Methods, 公共方法
4. Public Events, 公共事件

      Config Options下的内容为你在实例化一个对象时进行配置的，也就是比如new Ext.Panel({closable:true,  title:"定义Panel的标题"})，这里的closable和title就是来自于Config Options。

      这个所谓的配置选项，也就是Config Options下的内容，只有你在实例化的时候用的，也就是你在new 类名({…})时用的。其他类的使用方法也一样。 这里，我结合自己的经验，需要特别说明一下，ExtJS中的配置项都是JSON格式的。编程时一定注意！

      Public Properties表示的是你从一个实例化对象里取得的属性，比如你刚才 var panel = new Ext.Panel({closable:true,  title:"定义Panel的标题"});这样已经实例化了一个对象了。那么现在你可以取实例化对象的数据了。这个实力对象里面有什么东西可以取呢？怎么取呢？那么这里public properties里的列出的就是你能取的。那么你要panel.buttons 就能获得一个Array类型的数据，面板的按钮组成的数组。所以public properties下列出的就是一个实例化对象能取的信息，冒号后面的是你索取得的信息的返回类型。

      再来看Public Methods 这个部分，一般第一个都会是你实例化一个对象的构造方法。（可能这条是针对ExtJS 2.X的API说的。我查了两个类，在3.X中已经没有构造方法的说明了。）所以，我就拿普通的方法举例了。比如addListener( String eventName , Function fn , Object scope , Object options ) : void ，加入一个事件处理函数。表示的是这个方法可以接受三种类型的参数，一个是String类型的，一个是Function类型的，最后一个是Object类型的。所谓的object类型的一般是这种模式{…}。不过，也有例外。而所谓的string类型就是"…"。至于Function，现在不会很明白，以后再说。注意看括号里面的，括号里面的才是调用这个方法时需要传递进去的参数类型。而冒号后面的那个Node的意思是你调用这个方法后返回的一个数据类型。

      接下来看Public Events部分。这部分的内容表示的是你在使用Panel类的时候可能出现的事件。比如你对一个Panel面板的标题有改动后触发，那么titlechange事件就会发生。titlechange( Ext.Panel p, String t )，括号里后面的表示的是发生这个事件时会传递过来的数据。这一点一定要记住并理解！如何捕获事件呢？由两种方式，一种是on，一种是listeners。可以在实例化一个类的时候为listeners配置选项赋值。比如：比如var panel = new Ext.Panel({listeners:{"titlechange", function(a,b){….}}})；还有一种是你对这个实例进行on或addListener方法的调用。这两个方法就在Public Methods。on( String eventName , Function handler , Object scope , Object options ) : void ，所以你要知道这个事件捕获接受哪些参数。这里的[Object scope], [Object options]相对复杂些。这里需要哦提前说明的是，js跟java是不一样的，java的方法你传递的参数个数必须根定义的一样，但是js的并不需要。所以你在进行on方法的调用是可以传递不等同个数的参数。你可以只传递2个参数。一般情况下，这个api告诉你的是，[]这样括起来的表示你可以不传递的参数。其他的最好传递进来。所以你可以这样调用了. panel.on("titlechange",function(){…})或者panel.on("titlechange",hello);    function hello(a,b,c,d){…} 。[Object scope], [Object options]这个一般要传就是传递this什么的。有时候会用到，特别是当你遇到一些问题时。这个on或addListener方法的调用跟public events下的事件是挂钩的，在写处理函数时，需要public events中的参数。事件titlechange( Ext.Panel p, String t )括号里面表示的是事件发生时自动得到的信息。所以，当你在调用on方法时，on方法里handler参数就很关键了。Function handler 这里定义的方法将被调用，别且会将事件titlechange( Ext.Panel p, String t )括号里面表示的是事件发生时自动得到的信息 的参数传递给它。所以在定义这个handler的时候就可以定义成接受( Ext.Panel p, String t ) 这两个类型的参数。Public Events下面的东西只是定义了一些事件。而真正使用事件是你进行捕获。

      API各个配置选项或属性或方法或事件的右边有个叫Defined By（列头 – Defined By）。他表示的是这些信息是由哪个类定义的。请注意Ext中一个很重要的信就是继承。所以有些方法或配置选项或属性都是来自于他的父类或超类。那么这个Defined By 就告诉了你是来自具体的哪个父类或超类。

      然后我们再看看最上面的部分，

Class Ext.Panel
Package: Ext
Defined In: Panel.js
Class: Ext.Panel
Extends: Ext.Container

      注意，这里有个Extends；有的类还有Subclasses。Subclasses表示这个类有哪些子类，Extends表示这个类继承自哪个类。之所以要说这点，是因为要说一下事件应用的限制。只有那些继承了Observable类的类，也就是这个类是Observable的子类或子孙类，那么这个类才拥有事件处理机制，也就是才会有Public Events部分。所以，如果要自己扩展一个类，想拥有事件处理和响应机制，那么你这个类就必须是这个Observable类的子类或子孙类。可以一直点Extends后面的进去，最后肯定会出来我说的这个Observable类。

这里还有几个问题需要注意一下：

1. 事件处理中后两个参数的意义以及怎么使用？
2. Function类注意功能是什么？如何使用？
3. 如何扩展一个类？如何定义一个自己的类？

      希望以后自己“ 功力”提升了能更深入地去使用，了解ExtJS。

      参考网址：http://yahaitt.iteye.com/blog/217517

更多内容，请见我的博客：“地瓜哥”，http://www.diguage.com/