EXTJS4官方文档翻译系列一:类系统和编码规范
2013-05-28 20:57
453 查看
上个礼拜开始使用extjs4,之前都没用过ext,所以现在只好努力的看文档了,顺便记下来避免以后忘记.括号中内容是我自己添加的备注或者原文.英语比较烂,但不想一直烂,所以试着翻译,希望大家指能出错误的地方,英语好的建议看官方文档,不要被我误导了.
地址: http://docs.sencha.com/ext-js/4-0/#/guide/class_system
PS:上次说要翻译的一些titanium的文档,无奈后面太监了..没办法,工作用不上,业余时间要学工作的东西.titanium虽然喜欢,但是很久没去碰了.有机会继续吧..
ext4使用新的类机制进行了大量的重构,这在ext的历史上还是第一次!为了支撑新的架构,ext4几乎重写了每一个类,因此最好先好好的理解一下新的架构,再开始编码
本文适合想在extjs4中扩展现有类或者创建新类的开发者(注:其实想用ext4的都要看看).共分为4个部分:
第一部分:概述,说明了强大的类机制的必要性.
第二部分:编码规范,讨论类、方法、属性、变量和文件命名的最佳实践.
第三部分:动手,详细的编码示例.
第四部分:错误处理和调试,提供一些有用的调试和异常处理技巧
一,概述
ExtJS4拥有超过300个的类.迄今为止,我们的社区拥有超过20万来自世界各地,使用不同后台语言的开发者.要在这种规模的框架上提供具有以下特点的架构,需要面临巨大的挑战:
1,简单易学。2,快速开发、调试简单、部署容易。3,良好的结构、可扩展性和可维护性。
javascript是一种类无关(原文:classless)、基于原型的语言。因此javascript最强大的特点是灵活。同样的事情可以使用不同的方式,不同的编码风格和技巧去完成。这个特点也会带来一些不可预测的风险。如果没有统一的编码规范,javascript代码将很难理解、维护和复用。
相反的,基于类的编程语言拥有较为流行的面向对象模型,强类型、内建的封装机制和强制的编码约束等特点。通过强制开发人员遵守一些大的原则来使代码的行为更容易被理解,以及提高可扩展性(这里不明白,javascript这类动态语言不是更容易扩展么?)和可伸缩性。但是,这类语言没有javascript的灵活性。
二,命名约定
在所有类、命名空间(namespace)和文件名中使用一致的命名约定,有助于保持代码的良好结构和可读性。
1)类
类名只能包含字母和数字。允许包含数字,但是大部分情况下不建议使用,除非这些数字是专业术语的一部分。不要使用下划线,连字符等非数字字母符号。例如:
MyCompany.useful_util.Debug_Toolbar 不建议
MyCompany.util.Base64 合适的(虽然包含数字,但是数字是术语的一部分)
类名应该包含在使用点号分隔的命名空间中。至少,要有一个顶级命名空间。例如:
MyCompany.data.CoolProxyMyComp
MyCompany.data.CoolProxyMyCompa
顶级命名空间和实际的类名应使用驼峰命名(CamelCased),其他则为小写。例如:
MyCompany.form.action.AutoLoad
不是Sencha开发的类(即不是Ext自带的)不要使用Ext做为顶级命名空间。
缩写也要遵守以上的驼峰式命名约定。例如:
2)代码文件
类名对应类所在的文件(包括文件名)。因此,每个文件应该只包含一个类(类名和文件名一样)。例如:
path/to/src 是你应用程序所在目录。所有类都应该在这个通用根目录下,并且使用适当的命名空间以利于开发、维护和部署。
3)方法和变量
和类命名一样,方法和变量也只能包含字母和数字。数字同样是允许但不建议,除非属于专业术语。不要使用下划线,连字符等任何非字母数字符号。
方法和变量名一样使用驼峰式命名,缩写也一样。
举例
合适的方法名:
encodeUsingMd5() getHtml() 代替 getHTML()
getJsonResponse() 代替 getJSONResponse()
parseXmlContent() 代替parseXMLContent()
合适的变量名:
var isGoodName
var base64Encoder
var xmlReader
var httpServer
4)属性
类属性名称遵循以上的变量和方法命名约定.除非是静态的常量.
类的静态属性常量应该全部大写。例如:
Ext.MessageBox.YES = "Yes"
Ext.MessageBox.NO = "No"
MyCompany.alien.Math.PI = "4.13"
三,动手实践
1).声明
1.1) 旧的方式
如果你曾经使用过旧版本的extjs,那么你肯定熟悉使用Ext.extend来创建一个类:
这个方法很容易从现有的类中继承创建新的类.相比直接继承,我们没有好用的API用于类创建的其他方面,诸如:配置、静态方法、混入(Mixins)。呆会我们再来详细的重新审视这些方面。现在,让我们来看看另一个例子:
在这个例子中,我们创建我们的新类,继承Ext.Window,放在命名空间中。我们有两个问题要解决:
1,在我们访问My.cool的Window属性之前,My.cool必须是一个已有的对象.
2,Ext.Window必须在引用之前加载.
第一个问题通常使用Ext.namespace(别名Ext.ns)来解决.该方法递归创建(如果该对象不存在)这些对象依赖.比较繁琐枯燥的部分是你必须在Ext.extend之前执行Ext.ns来创建它们.
第二个问题不好解决,因为Ext.Window可能直接或间接的依赖于许多其他的类,依赖的类可能还依赖其它类...出于这个原因,在ext4之前,我们通常引入整个ext-all.js,即使是我们只需要其中的一小部分.
1.2) 新的方式
在Extjs4中,你只需要使用一个方法就可以解决这些问题:Ext.define.以下是它的基本语法:
onClassCreated: 可选的回调函数,在所有依赖都加载完毕,并且类本身建立后触发.由于类创建的新的异步特性,这个回调函数在很多情况下都很有用.这些在第四节中将进一步讨论
例如:
注意我们使用Ext.create()方法创建了My.sample.Person类的一个新实例.我们也可以使用新的关键字(new My.sample.Person())来创建.然而,建议养成始终用Ext.create来创建类示例的习惯,因为它允许你利用动态加载的优势.更多关于动态加载信息,请看入门指南:入门指南
2).配置
在ExtJS 4 ,我们引入了一个专门的配置属性,用于提供在类创建前的预处理功能.特性包括:
配置完全封装其他类成员
getter和setter.如果类没有定义这些方法,在创建类时将自动生成配置的属性的getter和setter方法。
同样的,每个配置的属性自动生成一个apply方法.自动生成的setter方法内部在设置值之前调用apply方法.如果你要在设置值之前自定义自己的逻辑,那就重载apply方法.如果apply没有返回值,则setter不会设置值.看下面applyTitle的例子:
以下是它的用法:
3.Statics
静态成员可以使用statics配置项来定义
四.错误处理&调试
Extjs 4包含一些有用的特性用于调试和错误处理.
你可以使用Ext.getDisplayName()来显示任意方法的名字.这对显示抛出异常的类和方法非常有用.
当使用Ext.define()定义的类中的方法抛出异常后.你将在调用堆栈中看到类和方法名(如果你使用webkit).例如,以下是chrome浏览器的效果:
![](http://docs.sencha.com/ext-js/4-0/guides/class_system/call-stack.png)
本文原作者地址:http://www.cnblogs.com/honhonmin/archive/2011/07/02/2096078.html
地址: http://docs.sencha.com/ext-js/4-0/#/guide/class_system
PS:上次说要翻译的一些titanium的文档,无奈后面太监了..没办法,工作用不上,业余时间要学工作的东西.titanium虽然喜欢,但是很久没去碰了.有机会继续吧..
ext4使用新的类机制进行了大量的重构,这在ext的历史上还是第一次!为了支撑新的架构,ext4几乎重写了每一个类,因此最好先好好的理解一下新的架构,再开始编码
本文适合想在extjs4中扩展现有类或者创建新类的开发者(注:其实想用ext4的都要看看).共分为4个部分:
第一部分:概述,说明了强大的类机制的必要性.
第二部分:编码规范,讨论类、方法、属性、变量和文件命名的最佳实践.
第三部分:动手,详细的编码示例.
第四部分:错误处理和调试,提供一些有用的调试和异常处理技巧
一,概述
ExtJS4拥有超过300个的类.迄今为止,我们的社区拥有超过20万来自世界各地,使用不同后台语言的开发者.要在这种规模的框架上提供具有以下特点的架构,需要面临巨大的挑战:
1,简单易学。2,快速开发、调试简单、部署容易。3,良好的结构、可扩展性和可维护性。
javascript是一种类无关(原文:classless)、基于原型的语言。因此javascript最强大的特点是灵活。同样的事情可以使用不同的方式,不同的编码风格和技巧去完成。这个特点也会带来一些不可预测的风险。如果没有统一的编码规范,javascript代码将很难理解、维护和复用。
相反的,基于类的编程语言拥有较为流行的面向对象模型,强类型、内建的封装机制和强制的编码约束等特点。通过强制开发人员遵守一些大的原则来使代码的行为更容易被理解,以及提高可扩展性(这里不明白,javascript这类动态语言不是更容易扩展么?)和可伸缩性。但是,这类语言没有javascript的灵活性。
二,命名约定
在所有类、命名空间(namespace)和文件名中使用一致的命名约定,有助于保持代码的良好结构和可读性。
1)类
类名只能包含字母和数字。允许包含数字,但是大部分情况下不建议使用,除非这些数字是专业术语的一部分。不要使用下划线,连字符等非数字字母符号。例如:
MyCompany.useful_util.Debug_Toolbar 不建议
MyCompany.util.Base64 合适的(虽然包含数字,但是数字是术语的一部分)
类名应该包含在使用点号分隔的命名空间中。至少,要有一个顶级命名空间。例如:
MyCompany.data.CoolProxyMyComp
MyCompany.data.CoolProxyMyCompa
顶级命名空间和实际的类名应使用驼峰命名(CamelCased),其他则为小写。例如:
MyCompany.form.action.AutoLoad
不是Sencha开发的类(即不是Ext自带的)不要使用Ext做为顶级命名空间。
缩写也要遵守以上的驼峰式命名约定。例如:
Ext.data.JsonProxy而不是
Ext.data.JSONProxy
MyCompany.util.HtmlParser而不是
MyCompary.parser.HTMLParser
MyCompany.server.Http而不是
MyCompany.server.HTTP
2)代码文件
类名对应类所在的文件(包括文件名)。因此,每个文件应该只包含一个类(类名和文件名一样)。例如:
Ext.util.Observable存储在
path/to/src/Ext/util/Observable.js
Ext.form.action.Submit存储在
path/to/src/Ext/form/action/Submit.js
MyCompany.chart.axis.Numeric存储在 path/to/src/MyCompany/chart/axis/Numeric.js
path/to/src 是你应用程序所在目录。所有类都应该在这个通用根目录下,并且使用适当的命名空间以利于开发、维护和部署。
3)方法和变量
和类命名一样,方法和变量也只能包含字母和数字。数字同样是允许但不建议,除非属于专业术语。不要使用下划线,连字符等任何非字母数字符号。
方法和变量名一样使用驼峰式命名,缩写也一样。
举例
合适的方法名:
encodeUsingMd5() getHtml() 代替 getHTML()
getJsonResponse() 代替 getJSONResponse()
parseXmlContent() 代替parseXMLContent()
合适的变量名:
var isGoodName
var base64Encoder
var xmlReader
var httpServer
4)属性
类属性名称遵循以上的变量和方法命名约定.除非是静态的常量.
类的静态属性常量应该全部大写。例如:
Ext.MessageBox.YES = "Yes"
Ext.MessageBox.NO = "No"
MyCompany.alien.Math.PI = "4.13"
三,动手实践
1).声明
1.1) 旧的方式
如果你曾经使用过旧版本的extjs,那么你肯定熟悉使用Ext.extend来创建一个类:
varMyWindow=Ext.extend(Object,{...});
这个方法很容易从现有的类中继承创建新的类.相比直接继承,我们没有好用的API用于类创建的其他方面,诸如:配置、静态方法、混入(Mixins)。呆会我们再来详细的重新审视这些方面。现在,让我们来看看另一个例子:
My.cool.Window = Ext.extend(Ext.Window, { ...});
在这个例子中,我们创建我们的新类,继承Ext.Window,放在命名空间中。我们有两个问题要解决:
1,在我们访问My.cool的Window属性之前,My.cool必须是一个已有的对象.
2,Ext.Window必须在引用之前加载.
第一个问题通常使用Ext.namespace(别名Ext.ns)来解决.该方法递归创建(如果该对象不存在)这些对象依赖.比较繁琐枯燥的部分是你必须在Ext.extend之前执行Ext.ns来创建它们.
Ext.ns('My.cool');
My.cool.Window = Ext.extend(Ext.Window, { ...});
第二个问题不好解决,因为Ext.Window可能直接或间接的依赖于许多其他的类,依赖的类可能还依赖其它类...出于这个原因,在ext4之前,我们通常引入整个ext-all.js,即使是我们只需要其中的一小部分.
1.2) 新的方式
在Extjs4中,你只需要使用一个方法就可以解决这些问题:Ext.define.以下是它的基本语法:
Ext.define(className, members, onClassCreated);
className: 类名
members:代表类成员的对象字面量(键值对,json)
onClassCreated: 可选的回调函数,在所有依赖都加载完毕,并且类本身建立后触发.由于类创建的新的异步特性,这个回调函数在很多情况下都很有用.这些在第四节中将进一步讨论
例如:
Ext.define('My.sample.Person', {
name: 'Unknown',
constructor: function(name) {
if (name) {
this.name = name;
}
return this;
},
eat: function(foodType) {
alert(this.name + " is eating: " + foodType);
return this;
}
});
var aaron = Ext.create('My.sample.Person', 'Aaron');
aaron.eat("Salad"); // alert("Aaron is eating: Salad");
注意我们使用Ext.create()方法创建了My.sample.Person类的一个新实例.我们也可以使用新的关键字(new My.sample.Person())来创建.然而,建议养成始终用Ext.create来创建类示例的习惯,因为它允许你利用动态加载的优势.更多关于动态加载信息,请看入门指南:入门指南
2).配置
在ExtJS 4 ,我们引入了一个专门的配置属性,用于提供在类创建前的预处理功能.特性包括:
配置完全封装其他类成员
getter和setter.如果类没有定义这些方法,在创建类时将自动生成配置的属性的getter和setter方法。
同样的,每个配置的属性自动生成一个apply方法.自动生成的setter方法内部在设置值之前调用apply方法.如果你要在设置值之前自定义自己的逻辑,那就重载apply方法.如果apply没有返回值,则setter不会设置值.看下面applyTitle的例子:
Ext.define('My.own.Window', {
/** @readonly */
isWindow: true,
config: {
title: 'Title Here',
bottomBar: {
enabled: true,
height: 50,
resizable: false
}
},
constructor: function(config) {
this.initConfig(config);
return this;
},
applyTitle: function(title) {
if (!Ext.isString(title) || title.length === 0) {
alert('Error: Title must be a valid non-empty string');
}
else {
return title;
}
},
applyBottomBar: function(bottomBar) {
if (bottomBar && bottomBar.enabled) {
if (!this.bottomBar) {
return Ext.create('My.own.WindowBottomBar', bottomBar);
}
else {
this.bottomBar.setConfig(bottomBar);
}
}
}
});
以下是它的用法:
var myWindow = Ext.create('My.own.Window', {
title: 'Hello World',
bottomBar: {
height: 60
}
});
alert(myWindow.getTitle()); // alerts "Hello World"
myWindow.setTitle('Something New');
alert(myWindow.getTitle()); // alerts "Something New"
myWindow.setTitle(null); // alerts "Error: Title must be a valid non-empty string"
myWindow.setBottomBar({ height: 100}); // Bottom bar's height is changed to 100
3.Statics
静态成员可以使用statics配置项来定义
Ext.define('Computer', {
statics: {
instanceCount: 0,
factory: function(brand) {
// 'this' in static methods refer to the class itself
return new this({brand: brand});
}
},
config: {
brand: null
},
constructor: function(config) {
this.initConfig(config);
// the 'self' property of an instance refers to its class
this.self.instanceCount ++;
return this;
}
});
var dellComputer = Computer.factory('Dell');
var appleComputer = Computer.factory('Mac');
alert(appleComputer.getBrand()); // using the auto-generated getter to get the value of a config property. Alerts "Mac"
alert(Computer.instanceCount); // Alerts "2"
四.错误处理&调试
Extjs 4包含一些有用的特性用于调试和错误处理.
你可以使用Ext.getDisplayName()来显示任意方法的名字.这对显示抛出异常的类和方法非常有用.
throw new Error('['+ Ext.getDisplayName(arguments.callee) +'] Some message here');
当使用Ext.define()定义的类中的方法抛出异常后.你将在调用堆栈中看到类和方法名(如果你使用webkit).例如,以下是chrome浏览器的效果:
![](http://docs.sencha.com/ext-js/4-0/guides/class_system/call-stack.png)
本文原作者地址:http://www.cnblogs.com/honhonmin/archive/2011/07/02/2096078.html
相关文章推荐
- EXTJS4官方文档翻译系列一:类系统和编码规范
- EXTJS4官方文档翻译系列一:类系统和编码规范
- TC官方文档翻译12----编码API(Tokyo Cabinet/Tokyo Tyarnt 文档系列)
- 【SUN/Oracle官方文档翻译+纠错】JAVA语言编码规范
- TC官方文档翻译05----Hash Map对象API(Tokyo Cabinet/Tokyo Tyarnt 文档系列)
- TC官方文档翻译10----其他API(Tokyo Cabinet/Tokyo Tyarnt 文档系列)
- JMeter系列教程 | 官方文档翻译
- 【Spring Boot&& Spring Cloud系列】单点登录SSO之OAuth2官方开发文档翻译
- Extjs4 官方文档翻译系列二:组件(components)、自定义组件
- TC官方文档翻译11----文件操作API(Tokyo Cabinet/Tokyo Tyarnt 文档系列)
- 【大数据系列】FileSystem Shell官方文档翻译
- ABP官方文档翻译 1.3 模块系统
- MongoDB官方文档翻译系列之 -- 执行二阶段提交
- 【大数据系列】apache hive 官方文档翻译
- Android官方开发文档Training系列课程中文版:管理系统UI之变暗系统条
- 【AKKA 官方文档翻译】actor模型如何满足现代分布式系统的需求
- Apple官方文档翻译之iOS 文件管理系统
- 我的《Android官方开发文档Training系列课程中文版》的中期翻译计划
- solr官方文档翻译系列之schema.xml配置介绍
- ABP官方文档翻译 8.1 通知系统