前端javascript开发规范文档 (extjs5)

[TOC]

介绍

此文档适用 Extjs5.x MVC 开发模式,开发人员通过此文档来规范开发extjs5 example文档

特点

简单易学。
快速开发、效率高。
良好的结构、可扩展性和可维护性。

命名

以下所有命名只能包含字母,不要使用下划线，连字符等任何非字母数字符号。

Variable

【强制】小驼峰式命名法。
【强制】前缀应当是名词。(函数的名字前缀为动词，以此区分变量和函数)
【正例】

	var maxCount = 10;
	var tableTitle = 'LoginTable';

Function

【强制】小驼峰式命名法。
【强制】前缀应当为动词。

动词	含义	返回值
can	判断是否可执行某个动作(权限)	函数返回一个布尔值。true：可执行；false：不可执行
has	判断是否含有某个值	函数返回一个布尔值。true：含有此值；false：不含有此值
is	判断是否为某个值	函数返回一个布尔值。true：为某个值；false：不为某个值
get	获取某个值	函数返回一个非布尔值
set	设置某个值	无返回值、返回是否设置成功或者返回链式对象
load	加载某些数据	无返回值或者返回是否加载完成的结果

MVC模式的目录及文件名命名规约

【正例】

 	+- - pages
 	+- - scripts
 		+- - pageDir  //页面一
 			+- - controller 
 				- - prefixController.js
 					...
 			+- - store
 				- - prefixStore.js
 					...
 			+- - model
 				- - prefixModel.js
 					...
 			+- - view  
 				+- - viewFloder
 					- - prefix...Window.js
 					- - prefix...Form.js
 					- - prefix...Grid.js
 						...
 				- - Viewport.js
 			- - application.js   //mvc 程序入口
 		+- - twoModule    //页面二
 				...
 		+- - threeModule  //页面三
 				...
 	+- - styles

【强制】当前模块有不同页面都要在scripts下新增不同页面的目录.
【强制】在当前页面模块目录下创建controller、store、model、view目录,是mvc模式的规范.
【强制】 mvc程序入口文件application.js,建议为当前领域模块名称为前缀,如prefixApp.js,name属性值声明为当前页面名称以作为一个应用名.
【强制】 view目录下,需要新增视图文件Viewport.js,名字只允许为Viewport,目录按照不同页面模块存放视图使用js,不与ViewPort.js在同一层目录.
【强制】在controller、model、store文件夹中,新增的js文件名前缀须加上与当前模块相关名称,方便查找和维护.
- 【正例】prefixController.js、prefixModel.js、prefixStore.js、prefix...Window.js、prefix...SearchForm.js、prefix...Grid.js
- 【反例】controller.js、model.js、store.js、list.js、search.js、grid.js

###Component、Property、Method 规约

【强制】声明自定义组件类名称规约,<appName>.<pageDir>.<pageDir>.<fileName>,目录级别按路径层级为准.

【正例】

 	Ext.define('appName.pageDir.controller.demoController',{
 		...
 		property,
 		constructor: function() { ... }
 	});

【反例】

 	Ext.define('fileName',{
 		...
 		property,
 		constructor: function() { ... }
 	});

【强制】自定义组件类componment中必须声明constructor函数,并且在底部调用,否则无法加载.

实践

Development

【强制】代码中不允许留有console.log()、console.info()、console.error()console家族的代码以及类似调试代码的函数
【强制】 jsp中不允许引入js或者是调试注释的js
【强制】和后端做异步交互请求时,每个请求都需要添加遮罩层,防止多次请求,或者给按钮设置不可用,获得响应后再设置为可用

【强制】不要在js中添加全局变量,可以添加静态方法.

【正例】

 	Ext.define('appName.pageDir.controller.demoController', {
 	     statics: {
 	         DEMOCONSTANT:'test'
 	     },
 	     constructor: function() { ... }
 	});
 	console.log(appName.pageDir.controller.demoController.DEMOCONSTANT);

【推荐】除mvc之外的类,建议养成始终用Ext.create来创建类示例的习惯,因为它允许你利用动态加载的优势.

【正例】

 	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

【强制】 common.js和util.js封装了大量的扩展组件和方法,可复用组件统一定义在common.js中,工具类的公用函数定义在util.js中

Form Panel 、Grid Panel

【强制】界面查询表单中的按钮使用buttons属性组件,只做重置和提供查询条件的功能,curd 操作按钮统一在grid上设定tbar组件.
【强制】 formPanel 中textfield组件的宽度只允许设定columnWidth,支持基本响应式功能.
【强制】 formPanel 统一要设置defaults属性对象的值,比如对齐方式,label是否带有冒号,全局的lable文字宽度,组件宽度
【强制】 gridPanel组件首列统一设置rownumberer类型的列,设置default的align属性为center.

【强制】 gridPanel组件的分页插件,都需要设置displayInfo的属性值为true,用于在右下角显示条数和总数

【正例】

 	pagingToolbar: null,
     getPagingToolbar: function () {
         if (this.pagingToolbar == null) {
             this.pagingToolbar = Ext.create('Ext.toolbar.Paging', {
                 store: this.store,
                 dock: 'bottom',
                 displayInfo: true
             });
         }
         return this.pagingToolbar;
     }

【强制】 tbar上的按钮组css3 font图标一定要在图标库找到符合的图标,不能随意使用(css3图标库已经更新到最新).
【强制】 tbar上的按钮组,需要设置成响应式按钮组.

Window

【强制】 window'的关闭模式,都统一使用destory`模式(默认)
【强制】 window中的按钮设置要符合windows操作系统中的习惯操作位置来放置,[保存]在左,[取消]在右,并且在底部垂直居中.
【强制】提示类型的window,要使用封装好的弹出提示框warning、error 、msg、confirm

Api的使用建议

【推荐】尽量使用Extjs方言
- 【说明】 ExtJS提供了很多有用的方法，解决客户端JavaScript常见的开发任务，常见的有查询HTMLDom，创建HTML元素，为HTML元素注册事件响应函数等，这些大可以全部使用ExtJS提供的方法，使自己代码构建与ExtJS之上.
- 【正例】
  - 减少使用getCmp(id)或者get(id)方法来达到减少内存消耗的目的,可以使用up(),down(),widget().
  - 查询ID为container的DIV下所有的checkbox，可以使用Ext.fly(‘container’).select(‘input【type=checkbox】’)
  - 在ID为container的DIV内创建一个按钮，可以使用Ext.fly(‘container’).createChild({ tag: ‘input’, type: ‘button’})
  - 为ID为container的DIV的click事件注册处理函数，可以使用Ext.fly(‘container’).on(‘click’, handlerFn, scope)
  - 操作dom可以使用,Ext.query,Ext.DomHelper,Ext.DomQuery

注释

js支持两种不同类型的注释：单行注释和多行注释。

单行注释

【说明】单行注释以两个斜线开始，以行尾结束.
- 【强制】单独一行：//(双斜线)与注释文字之间保留一个空格。
- 【强制】在代码后面添加注释：//(双斜线)与代码之间保留一个空格，并且//(双斜线)与注释文字之间保留一个空格。
- 【强制】注释代码：//(双斜线)与代码之间保留一个空格。

【正例】

 	// 调用了一个函数； 1)单独在一行
 	setTitle();
 	 
 	var maxCount = 10; // 设置最大量； 2)在代码后面注释
 	 
 	// setName(); //  3)注释代码

多行注释

【说明】以/*开头，*/结尾.
- 【强制】若开始(/*)和结束(*/)都在一行，采用单行注释。
- 【强制】若至少三行注释时，第一行为/*，最后行为*/，其他行以*开始，并且注释文字与*保留一个空格。

【正例】

 	/*
 	 * 代码执行到这里后会调用setTitle()函数
 	 * setTitle()：设置title的值
 	 */
 	setTitle();

配置

Dev Tool

【强制】所有的js文件都必须添加文件注释头
- IDEA模板:打开Setting->Editor->File And Code Templates->Files,选择JavaScript File,修改文件注释头
- 【正例】
```
 	/**
 	 * @description:
 	 * @author: ${USER}
 	 * @date: ${DATE} ${TIME}
 	 */
```
【强制】代码格式化
- 提交代码前检验代码中是否多余空白行造成代码不规整,可读性差的问题
  - javascript代码都使用idea默认代码格式主题,或者在提交前,选择局部代码快捷键格式化后提交,保持代码的可读性高(不要全局格式化)
  - Mac os 快捷键 cmd + option + l (kemaps[Mac ox 10.5+])
  - win 快捷键 ctrl + shift + f (kemaps[Eclipse])

压缩

【强制】所有带有js的文件须使用压缩插件.
- 【说明】
  - pom.xml 必须要配置插件依赖wro4j-maven-plugin,
  - pom.xml必须声明<properties><moduleContext>moduleName</moduleContext></properties>声明模块的名称,否则maven install 会失败
  - wro.xml配置了需要使用的js文件引入,jsp中使用<ext:module/>标签定义压缩后的js文件前缀名称.在wro.properties文件中配置压缩的属性
  - wor.xml不允许引入已经被压缩过或者混淆过的mini.js文件,否则压缩后的该文件不生效
  - wor.xml不允许引入不被使用js提交到git上

错误&调试

【推荐】你可以使用Ext.getDisplayName()来显示任意方法的名字.这对显示抛出异常的类和方法非常有用.
```
 	throw new Error('['+ Ext.getDisplayName(arguments.callee) +'] Some message here');
```
【推荐】使用ant.xml实现静态资源打包来进行js更新调试功能
- 【说明】
  - 在当前的module根目录下新建ant.xml,添加导入资源的配置信息,将ant.xml导入idea中的右侧ant build面板中,运行run build即可(如没有则点击左下角的面板图标,选择ant build)
  - jsp中要引入需要调试的js,wro.xml中相应的js不能再引入(修改后的文件切勿提交到git)

【正例】 ant.xml配置example

 	<?xml version="1.0"?>
 	<project basedir="." name="table" default="deploy">  <!-- name 需要修改为自己的工程名称 -->
 		<!-- 静态资源paste目录地址,webapp下的资源访问目录 -->
 		<property name="webapp" value="${basedir}/../demo-login/src/main/webapp" />   <!--  -->
 		<property name="todir-scripts" value="${webapp}/scripts/${ant.project.name}/" />
 		<property name="todir-pages" value="${webapp}/WEB-INF/pages/${ant.project.name}/" />
 		<property name="todir-images" value="${webapp}/images/${ant.project.name}/" />
 		<property name="todir-styles" value="${webapp}/styles/${ant.project.name}/" />
 		<!-- 静态资源copy目录地址 -->
 		<property name="fromdir" value="${basedir}/src/main/resources/com/hoau/framework/module/table/server/META-INF" />
 		<property name="scripts" value="${fromdir}/scripts"/>
 	    <property name="pages" value="${fromdir}/pages"/>
 	    <property name="images" value="${fromdir}/images"/>
 	    <property name="styles" value="${fromdir}/styles"/>
 		<target name="deploy">
 	        <copy todir="${todir-scripts}" overwrite="true" verbose="true">
 	            <fileset dir="${scripts}">
 	                <include name="**" />
 	            </fileset>
 	        </copy>
 	        <copy todir="${todir-pages}" overwrite="true" verbose="true">
 	            <fileset dir="${pages}">
 	                <include name="**" />
 	            </fileset>
 	        </copy>
 	        <copy todir="${todir-images}" overwrite="true" verbose="true">
 	            <fileset dir="${images}" >
 	                <include name="**"/>
 	            </fileset>
 	        </copy>
 	        <copy todir="${todir-styles}" overwrite="true" verbose="true">
 	            <fileset dir="${styles}">
 	                <include name="**" />
 	            </fileset>
 	        </copy>
 	        <echo>
 	            ${webapp}
 	        </echo>
 	    </target>
 	</project>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

dev-ext5js-example-specification.md

dev-ext5js-example-specification.md

前端javascript开发规范文档 (extjs5)

目录

介绍

特点

命名

Variable

Function

MVC模式的目录及文件名命名规约

实践

Development

Form Panel 、Grid Panel

Window

Api的使用建议

注释

单行注释

多行注释

配置

Dev Tool

压缩

错误&调试

Files

dev-ext5js-example-specification.md

Latest commit

History

dev-ext5js-example-specification.md

File metadata and controls

前端javascript开发规范文档 (extjs5)

目录

介绍

特点

命名

Variable

Function

MVC模式的目录及文件名命名规约

实践

Development

Form Panel 、Grid Panel

Window

Api的使用建议

注释

单行注释

多行注释

配置

Dev Tool

压缩

错误&调试