云积分前端规范

1.规范说明

此为前端开发团队遵循和约定的代码书写规范，意在提高代码的规范性、扩展性、可维护性、阅读性，提高工作效率，提升个人技术。

此规范为参考规范，不全是硬性要求，部分硬性约定见下一条书写规范，统一团队编码规范和风格。让所有代码都是有规可循，并且能够得到沉淀，减少重复劳动。

1.1结构说明

-- 项目结构
----|---- public公共静态文件夹
----|----|---- CSS文件夹
----|----|---- JS文件夹
----|----|----|---- libs插件文件夹
----|----|---- images文件夹

2.书写规范

2.1 样式与内容分离

2.1.1 项目结构

-——  根目录  
    |-——- 功能目录  
        |-——- index.html //功能入口页面  
    |-——- public/  
        |-——- CSS/  
            |-——- 对应功能样式目录  
        |-——- JS/  
            |-——- 对应功能JS目录

2.1.2 重构步骤

1. index.html页面中的全部样式关联 class="xxx" 注：制作静态页面的时候文件中不包含任何一个id="XXX"
2. 为 index.html 书写CSS style [到这里页面重构完成]
3. 开始 index.html 书写JS交互文件，使用 id 和 class定位元素来进行交互，如果是单个元素操作 id 名的前面加上 js，如果是操作元素的 class 则给 class 加上 js- 前缀 [到这里页面交互完成]

2.1.3 命名规范

• 文件以及文件夹：全部用英文小写字母+数字或者是连接符“-、_”，不可出现其它字符，例如：...、---...
• 文件：调用 /libs 文件需包含版本号，压缩文件需包含 min 关键词，其它插件则不包含，例如： /libs/jquery.1.9.1.js、fileuploader.js
• ID名：匈牙利命名法 & 驼峰式大小写，如果是要获取某个ID的value，那这个ID名最好和后端提供的接口字段名一模一样，为了方便查看
  如：firstName aList
• Class名：全部小写，用-连接符
  如：top-item main-box
• 尽可能用语义明确的单词命名

2.1.4 格式&编码

• 文本文件： .xxx UTF-8(无BOM)编码
• 图片文件： .png png-24或者png-8（根据情况而定） .jpg
• 动态图片： .gif

2.2 CSS细化规范

2.2.1

-—— /css/
    |-——- base.css  CSS全局文件
    |-——- 功能样式目录

2.2.1 文件说明

• base.css 这个文件包含了CSS reset部分、各个模块的样式、各种margin padding width height...补丁
• 功能样式目录中包含了各个功能的样式，目录按照页面目录来分层
• 为了方便查看页面引入的CSS文件，不建议使用 @import

2.2.2 CSS注释格式约定

/*
@name: 文件名
@description：文件描述
@require（可选）： 依赖哪个文件
@author：作者
*/

2.2.3 CSS嵌套规则

/*推荐嵌套层级*/
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-nav .ui-list{}
.ui-table .ui-list{}

/* 不推荐 */
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-list{}
.ui-nav{}

2.2.4 补充说明

由于现阶段我们还未使用 CSS预编译工具 ，因此在开发的时候我们展示只考虑CSS的目录结构，后期如果我们使用到了 CSS预编译工具 我们就需要有一个预编译文件对应的目录，如 LESS SASS，编译我们可以依靠自动化构建工具来处理

2.3 HTML细化规范

2.3.1 HTML注释格式约定

• HTML换行缩进必须清晰，采用四个空格，如果觉得按空格麻烦，可以在编辑器将 Tab 键设为四个空格

2.3.2 第一行统一使用HTML5标准

标签的使用就不在这里备注了，避免使用过时的标签，统一标准闭合

2.4 JS细化规范

2.4.1 JS文件结构

-—— /js/
|-——- /libs/  使用到的JS插件以及库文件夹
|-——- base.js 全局函数和变量文件
|-——- api.js 存放所有的接口调用函数
|-——- 功能JS目录 对应视图文件的目录

• 每一个页面中的JS文件建议单独写一个，文件以及文件目录对应视图文件的目录，方便查找以及维护
• 建议将接口调用写成一个函数，这个函数返回三种状态，成功 失败 完成。

3.前后端配合规范

3.1 文档书写规范

• 接口文档书写清晰，尽量避免错别字以及语句歧义
• 如有特殊情况，对应接口后面加以备注