基于gulp的前端框架开发规范
前端开发及相关规范 - 基于gulp的前端框架开发规范
1.前端开发工具的安装和使用说明
前端开发工具的目录结构
├── statics
├── html //静态文件开发
├── js // 非require引入的js文件
├── Lib // 第三方JS包
├── ve_2_1 //
├── css // 样式目录
├── fonts // bootstrap的图标字体
├── img // 图片目录
├── less // less源码
├── sprite // 雪碧图按目录全称目录名的图片
├── dirName
├── vender // 第三方css包,比如bootstrap
├── js // JS目录
├── dist //生成文件的目录(与开发源码目模块对应)
├── cart.js
├── common.js
├── lib.js
├── region.js
├── sidebar.js
├── tpl.js
├── user.js
├── web.js
├── src // 开发源码的目录
├── cart // 购物车模块
├── common // 公共的函数模块
├── lib // 公共jq插件模块
├── region // 处理联动地址的模块
├── sidebar // 侧边栏模块
├── tpl // 前端mvc模板引擎的压缩源码
├── user // 用户中心模块
├── web // VE前端模块，包括首页、亲子、品牌专题、详情页等
├── tpl //
├── config.dev.js // requirejs 开发配置文件[自动生成]
├── config.js // requirejs开发配置文件[自动生成]
├── config.release.js //
├── config.test.js // requirejs 测试环境配置文件[自动生成]
├── js.map.json // 压缩后的文件位置映射[自动生成]
├── path.json // requirejs 的 config -> path 内容，第三包的路径缩写配置
├── shim.json // requirejs 的 config -> shim 内容，第三包的依赖申明
├── ver_config.json // 开发、测试、预生产到发布，方便部署静态资源，而创建的版本和环境变量
├── tpl //
├── toolbar
├── mian.html
├── dot.gif // lazyloading的占位符
├── evc-VE.js // 在线客服的js
├── favicon.ico // 网站的缩略logo
├── README.md // 文档首页内容 markdown 语法
├── region.js // 地址
statics/Lib // 第三方JS包 目录说明
每个包单独一个文件夹，目的是：方便一个包多版本存放
如：jQuery 的 1.x 跟 2.x ， 2.x 是针对移动版
安装
- 前往 http://nodejs.org/ 安装nodeJS
- 注意系统是32位还是64位的，选择对应的版本
- 如果是windows系统，需自行设置好环境变量，将nodejs的路径加入到系统的
path环境变量中
- 在终端执行
npm install -g cnpm --registry=http://r.cnpmjs.org- 安装国内镜像管理命令--
cnpm - 参考文档 https://www.npmjs.org/package/cnpm
- 安装国内镜像管理命令--
- 在终端执行
npm install -g gulp，安装gulp全局支持 - 进入前端自动化开发和部署工具的目录，执行
npm install(使用国外镜像) 或cnpm install(使用国内镜像)
-- enjoy --
升级自动化工具
- 进入前端自动化开发和部署工具的目录，执行
npm install(使用国外镜像) 或cnpm install(使用国内镜像)
执行自动化工具
以下操作，需进入
FeBuilder的解压目录目录下执行
gulp- 监控 less 文件变化，自动生成 css
- 监控 js/src 文件变化， 自动在
dist目录生成对应的压缩 js - 监控 js/src 文件变化， 自动在
doc目录，根据jsdoc格式，生成文档 - 监控
css/sprite目录，如果有新sns文件，自动生成雪碧图
注：如果添加新目录，需重新执行该指令，否则新目录不会监控
gulp sprite生成雪碧图gulp script压缩，合并，打包jsgulp less编译less文件gulp watch
数据格式约定
- 原则上，前端开发是完全可以脱离开发环境和生产环境来进行的，因为前端开发主要是开发一些静态的资源，比如
HTML、CSS和JS等。 - 与后端的通讯，我们约定以
JSON的格式进行数据交换，那么前端开发完全就可以本地模拟一个.json格式的文件来进行开发调试。 - 基于
JSON的本地模拟数据，在与后端的同事沟通约定后，只需要对方API返回的数据结构和本地模拟的一致即可。
2.前端开发工具的相关约定
文件和目录的命名约定
- 必须是英文单词、名字拼音或者名字拼音首字母;
- 多个单词用下划线(_)连接;
- 只能出现英文字母、数字、连字符(_)，严禁以中文名来命名;
> 注：此命名约定适用于 html, css, js, swf, php, xml, png, gif, jpg, ico 等前端维护的所有文件类型和相关目录
开发文件的建立
- css
- 基于gulp的前端框架，前端开发是通过编写LESS，然后gulp会自动监听LESS来生成压缩的CSS，生成的文件与LESS同名
- 在 css/less 目录下建立LESS文件
- 不需要输出的CSS的，文件名要以下划线 _ 为前缀，通过 @import 包含的方式调用
- 例如: @import "_ve_index";（注意，@import包含的less文件可将.less后缀省略掉）
- 尽管LESS语法兼容CSS语法，但LESS源文件的编写请遵循LESS语法，以提高它的可读性和可维护性。
- icon合成雪碧图 -css sprite
- 在 css/sprite 目录下，按照功能模块的不同来建立文件夹，然后将零星的小图标放置在这个文件夹中；
- 在gulp启动的状态下，它会自动监控文件夹中文件的变化，自动合成 css/img/dirName.png 雪碧图及 css/less/_sp_dirName.less。
- 通过 @import 包含的方式调用 _sp_dirName.less即可
- 请注意，如果一个项目没有icon，则不要建立一个空的文件夹，gulp会报错。
什么是CSS Sprites？？
CSS Sprites就是把网页中一些背景图片整合到一张图片文件中，再利用CSS的background-image，background-repeat，background-position的组合进行背景定位，background-position可以用数字精确的定位出背景图片的位置。利用CSS Sprites能很好地减少网页的http请求，从而大大的提高页面的性能，这也是CSS Sprites最大的优点。
-
Javascript
为了项目更容易管理和团队协作，js的开发需要以模块化的方式进行。
在ve_2_1/js/src目录下建立按照功能模块的不同，来建立文件夹及js文件- js要按照AMD规范来命名和书写， 通过requireJS包管理器的方式来加载它依赖的其他js模块；
- js编译好之后，会自动压缩到
ve_2_1/js/dist目录，在页面中需要配合require.js（js依赖管理）和config.js（依赖的配置文件）来加载自动压缩后的js。 - config.js有四个不同环境：
config.dev.js、config.test.js、config.release.js和config.js分别对应开发环境、测试环境、预生产环境和生产环境。 - 四个不同环境的js文件加载，在嵌套cms系统的前端模板时，只需要用
{php echo init_js();}(后端php同事要预先封装好init_js函数)来动态输出即可。
*** 更多js模块化开发的参考文档: - RequireJS和AMD规范
- Javascript模块化编程1
- Javascript模块化编程2
- Javascript模块化编程3
*** 举例：
ve双城首页的js，我们就建立在 js/src/web 目录下，并命名为index.js，它依赖于'jquery.slide', 'web/common', 'web/timer'和jquery，而'jquery.slide', 'web/common', 'web/timer'也依赖于jqeury，jquery已被全局化，那么index.js应该是这样的：
index.js:
javascriptcodeBuilder - v0.9define('web/index', ['jquery.slide', 'web/common', 'web/timer'], function(slide, common) { var doc = document, win = window; //首页大图轮播 var _fullSlide = function() { var $sliderBox = $('.slider_box'); var $fullSlide = $('.fullSlide'); var imgs = $fullSlide.find('.bd .preload'); var now_img = $fullSlide.find('.bd img').eq(0); ...又如 common.js应该是这样的：
common.js:
javascriptcodeBuilder - v0.9define('web/common', [], function() { var exports = {}; var doc = document, win = window; //网页顶部的关注hover事件 exports.hover_qr = function() { $('.QRcode').on('mouseover', function() { $('.QRcode-box').toggle(); $('.QRcode i').toggleClass('selected'); }).on('mouseout', function() { $('.QRcode-box').toggle(); $('.QRcode i').toggleClass('selected'); }); }; ...index.js 和common.js不需要在引用
jquery.js,在它们内部中可以直接使用全局jquery中定义的$符号。- 页面中加载index.js的方法
<script src="http://s1.ve.cn/statics/Lib/require/require.js?_v2.1"> </script><script src="http://s1.ve.cn/statics/Lib/jquery/jquery.min.js?_v2.1"></script> <script src="http://s1.ve.cn/statics/ve_2_1/js/config.js?_1415852637"></script> <!-- requireJS -->
文档的格式化 - tab制表符来控制缩进
- 无论css、html还是js，开发的源文件都要适当地进行代码的格式化，一律以tab制表符来控制缩进；
- 调整自己的编辑器，将 tab制表符 以 4个空格 来替代。
> 小技巧：在绝大部分IDE开发工具中， tab是缩进，而shift+tab则是删除缩进。
3.HTML静态模板规范
约定
- 所有页面元素的z-index属性值控制在1000以下，将1000-2000留给组件级调用，2000以上用于解决特殊情况下的适应问题；
- 所有的标签及属性名采用小写，DOCTYPE除外；
- 保证标签语义化；
- 分离思想，所有的样式除特殊情况，css样式不能内联写在style属性中；
- 如非必要，尽量不采用表格来布局页面。
- 如非项目需要，不使用html5特有的标签，如canvas。
页头声明
必须加上以下3项，提高兼容性
<meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" />
<meta name="renderer" content="webkit" />
<meta name="viewport" content="width=device-width, initial-scale=1">
前 2 项，是指定 360 等国产浏览器，用 webkit 内核渲染页面
后 1 项，是在移动端上，指定页面的缩放比例
HTML注释
开始和结束均需要带有可识别的class或id，结束时则加斜杠 /(表示标签闭合了)。
<!-- 商品标题 -->
<div class="breadcrumb">
<a href="">唯一优品首页</a> > <a href="">名品特卖</a> > <a href="">新安怡夏季大促</a> > <a href="" class="title">新安怡 婴儿保湿润肤乳液(200ml)</a>
</div>
<!-- 商品标题end -->
css ， js 文件，在页面上的位置
- 原则上， css 文件， 必须在
<head>内 - 原则上， js 文件， 必须在
</body>结束前（尽可能的放底部），尽情避免在<head>内插入 js
script 标签是阻塞式加载的。 如果一个 js 文件 比较大，或者 404 ，这将阻塞后面部分内容的加载
标准前端html模板 -- 仅供参考
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" />
<meta name="renderer" content="webkit" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{title}</title>
<meta name="description" content="{description}" />
<meta name="keywords" content="{keywords}" />
<!-- 样式文件 -->
<link rel="stylesheet" href="./../../ve_2_1/css/ve_wap.css" />
</head>
<body>
<section class=''>
<div class="container">
<div class="row">
a
</div>
</div>
</section>
<!-- 尾部js -->
<script src="./../../ve_2_1/js/vendor/require/require.js"></script>
<script src="./../../ve_2_1/js/config.dev.js"></script>
<!-- 替换结束 -->
<!-- 自定义代码部分 -->
<script>
//js codes here.
require(['wap/index'], function() {
require(['wap/indexJs']);
});
</script>
</body>
</html>
推荐使用的元素
- 结构元素：blockquote, body, br, div, h1 - h6, head, hr, html, p
- 头部元素：base, link, meta, script, style, title
- 列表元素：ul, ol, li, dl, dt, dd
- 文本格式元素：a, abbr, acronym, address, bdo, cite, code, del, dfn, em, ins, kbd, noscript, pre, q, samp, small, span, strong, sub, sup, var
- 表单元素：button, fieldset, legend, form, input, label, optgroup, option, select, textarea
- 多媒体元素：area, img, map, object, param
- 表格元素：caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr
- 窗体元素：iframe
不推荐使用的元素
- 结构元素：无
- 头部元素：无
- 列表元素：dir, menu
- 文本格式元素：b, basefont, big, blink, center, comment, font, i, marquee, nobr, plaintext, ruby, s, strike, u, wbr, xmp
- 表单元素：isindex
- 多媒体元素：applet, bgsound, embed, noembed
- 表格元素：无
- 窗体元素：frame, frameset, noframes
转世重生的元素
- i - 作为单个图标的展位符，表示icon
- b - 预留，尚未想到合理的复活理由
- s - 预留，尚未想到合理的复活理由
4.CSS规范
文件编码约定
- 所有文件一律采用 utf-8编码
id 和 class 命名约定
- id 和 class 的命名总规则为： 内容优先,表现为辅. 首先根据内容来命名, 比如 main-nav. 如果根据内容找不到合适的命名, 可以再结合表现来定, 比如 amount-choose, product-intro, main_nav,logo_box 名称一律小写, 多个单词用下划线或者连字符连接, 比如 .time-countdown,size-choice,logo_box
- class 名称中只能出现小写的 26 个英文字母、数字、下划线和连字符(-), 任何其它字符都严禁出现.
- id的命名采用连接符命名法和下划线命名法,首字母小写，如：buy-ok,shop_btn
- id 和 class 尽量用英文单词命名.确实找不到合适的单词时, 可以考虑使用产品的中文拼音。
- 对于中国特色词汇可以使用拼音
- 除了产品名称和特色词汇, 其它任何情况下都严禁使用拼音.
* 在不影响语义的情况下, id 和 class 名称中可以适当采用英文单词缩写, 比如 col, nav, hd, bd, ft 等, 但切忌自造缩写.（常用缩写总结在css规范部分） - id 和 class 名称中的第一个词必须是单词全拼或语义非常清晰的单词缩写, 比如 goods, col.
基本规范
- 模块命名要注意带上模块名，下面尽可能的简写，页面级（app应用级）命名应该尽量简洁;
- 尽可能地使用css-sprite
- 尽量通过class属性定义样式,将id留给hook
- 尽量不要在css中使用expression
- 组件开发中，可以先不考虑性能，尽量使用选择符组以方便html调用，如.table-ctrl tbody tr td.selected{}；
- font中的字体用英文或unicode代替,如黑体可写成SimHei：font: 12px/1.5 SimHei ,tahoma,arial,\5b8b\4f53,sans-serif;
CSS引用
- 统一以link形式引入
- 不推荐内嵌形式引入css
- 不推荐标签出现在body中，特定页面（比如404错误页）除外。
- 不推荐内联CSS，请尽量放在head标签内
常用CSS属性顺序建议
- 显示属性(display, list-style, position, float, clear)
- 盒模型(width, height, margin, padding, border, background)
- 文本属性(color, font, text-decoration, text-align, vertical-align, white-space, other text, content)
注释风格
/*头注释*/
/*------------------------------------------------
@Filename: ve_goods
@Description: 产品内页
------------------------------------------------*/
//商品属性区块
//产品颜色选择
/*爆款*/
5.Javascript规范
快速指引
- 必须使用 Tab 键进行代码缩进，以节约代码大小和提高可读性。 (调整自己的编辑器tab制表符一律以4个空格来替代)
-
命名风格
|| || 规则 || 列如 ||
|| 类 || 混合式 || fixToTopClass ||
|| 公有方法 || 混合式 || isDate() check_password ||
|| 公有变量 || 混合式 || 列如 ||
|| 常量 || 大写式 || 列如 ||* 其他建议风格
非必要
|| 结构 || 规则 || 列如 ||
|| 私有方法 || 混合式 || ||
|| 私有变量 || 混合式 || ||
|| 方法参数 || 混合式 || ||
|| 本地(local)变量 || 混合式 || || -
所有语句结束后，必须使用
;号结束
命名规范
基本原则：尽量避免潜在冲突；精简短小, 见名知意。
- 局变量以$开头，如$user，相当于：window.$user
- 常量全部大写，单词以下划线分隔，如STATIC_ROOT
- 普通变量，采用驮峰式写法，首字母小写，如userIcon，UserRelation
- 类名首字母大写，如Object = function(){}
- 局部变量可缩写，命名空间，类名尽量不缩写
- 方法和函数，名字同普通变量名;
- 条件表达式、正则表式式，如果很复杂，给其命名
- 枚举量, 同常量;
- 私有变量, 属性和方法, 名字以下划线开头,如_init(),_param;
- 保护变量, 属性和方法, 名字同普通变量名;
注释规范
因为基于gulp架构，jsDoc插件可以自动根据段落注释自动生成可读性很好的文档，因此前端开发必须按照jsDoc的规范来写了js注释。
