Web前端开发标准规范

web前端开发规范的意义

  • 提高团队的协作能力
  • 提高代码的复用利用率
  • 可以写出质量更高,效率更好的代码
  • 为后期维护提供更好的支持

一、命名规则

  1. 命名使用英文语义化,禁止使用特殊字符,禁止使用拼音,禁止使用中英文混合
  2. 项目、目录、html/css/js等文件命名全部采用小写方式, 以下划线分隔。eg:my_project_name
  3. html/css/js文件名一一对应参考微信小程序.eg: login.html、login.css、login.js
  4. class、图片、视频、音频采用小写方式,以下划线或中划线分隔;eg:btn-play或btn_play
  5. id可采用驼峰命名;eg:play或playGame
  6. 变量名采用小写方式, 以下划线分隔;应为名词,eg: product,product_detail
  7. 常量采用全大写方式, 以下划线分隔;eg:MAX_COUNT
  8. 函数名采用驼峰命名,以动词开始。 getName(), 返回类型是布尔类型,一般以is开头,eg: isEnable();
  9. 变量和函数命名,不要担心长度,一定要语义化合乎逻辑。eg: saveImageToPhotosAlbum()
  10. 变量和函数名不能以数字开始,不能使用保留字;jQuery对象以'$'符号开头,私有变量以'_'开头。

二、注释

  • 页面头部需要添加制作时间等信息。
<head>    
    <title>页面名称</title>
     <!-- 月影 2019-02-19  -->
</head>
  • 功能模块,请在模块之间加入注释,中英文不做要求:
... 
 
<!-- 活动规则 开始  -->
<div class="rules-wrapper">
    <div class="rules-title">活动规则</div>
    <div class="rules-list">
        <div class="rules-item" v-for='item,index in rules_list'>
            <div class="rules-num">{{index+1}}</div>
            <div class="rules-text">{{item}}</div>
        </div>
    </div>
</div>
<!-- 活动规则 结束  -->
 ... 
/* rules start*/
.rules-wrapper{...}
.rules-title{...}
.rules-list{...}
.rules-item{...}
.rules-num{...}
.rules-text{...}
/* rules end*/
  • 自定义函数。请注明函数的调用方式,包括函数的用途、参数类型等。
/**
* JQ公告滚动 封装函数
* 参数说明
* @obj : 动画的节点,本例中是ul
* @top : 动画的高度,本例中是-35px;注意向上滚动是负数
* @time : 动画的速度,即完成动画所用时间,本例中是500毫秒,即marginTop从0到-35px耗时500毫秒
* function : 回调函数,每次动画完成,marginTop归零,并把此时第一条信息添加到列表最后;
* 
*/
function noticeUp(obj,top,time) {
    $(obj).animate({
        marginTop: top
    }, time, function () {
        $(this).css({marginTop: "0"}).find(":first").appendTo(this);
    })
}
$(function () {
    // 调用 公告滚动函数
    setInterval("noticeUp('.notice ul','-35px',500)", 2000);

});

三、HTML规范

1、页面头部

  1. 文档类型统一使用html5的doctype:
  2. lang属性统一使用en,特殊场景特殊处理
  3. 字符编码统一指定为'UTF-8'
  4. 页面标题(Title): 页面名称-产品中文全称-官方网站-腾讯游戏-产品slogan,28个汉字以内
  5. 页面关键字(Keywords): Keywords为产品名、专题名、专题相关名词,之间用英文半角逗号隔开
  6. 页面描述(Description) :不超过150个字符,描述内容要和页面内容相关。
  7. IE兼容模式 <meta http-equiv="X-UA-Compatible" content="IE=Edge">
  8. 移动端禁止缩放

PC端头部示范:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <!-- 月影 2019-02-19  -->
    <title>抓金角银角大王每周末放送装备 - 地下城与勇士官方网站 - 腾讯游戏</title>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge">
    <meta name="keywords"
          content="英雄联盟,lol,lol新手礼包,lol攻略,lol视频,lol视频攻略,英雄资料,英雄联盟战争学院,明星解说视频,101战争学院,英雄,攻略,WCG,点亮图标,赛事"/>
    <meta name="description"
          content="英雄联盟官方网站,海量风格各异的英雄,丰富、便捷的物品合成系统,游戏内置的匹配、排行和竞技系统,独创的“召唤师”系统及技能、符文、天赋等系统组合,必将带你进入一个崭新而又丰富多彩的游戏世界。"/>
</head>
<body>
</body>
</html>

移动端头部示范:

 <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <!-- 月影 2019-02-19  -->
    <title>页面名称-产品中文全称-官方网站-腾讯游戏-产品slogan</title>
    <!-- 禁止缩放 -->
    <meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1,maximum-scale=1,user-scalable=no">
    <!-- 为了防止页面数字被识别为电话号码,可根据实际需要添加: -->
    <meta name="format-detection" content="telephone=no">
    <!-- 让添加到主屏幕的网页再次打开时全屏展示,可添加: 删除默认的苹果工具栏和菜单栏  -->
    <meta content="yes" name="mobile-web-app-capable">
    <meta content="yes" name="apple-mobile-web-app-capable">
    <meta name="Description" content="页面的描述内容"/>
    <meta name="Keywords" content="页面关键字"/>
    <!-- External CSS -->
    <link rel="stylesheet" href="demo.css">
    <!-- In-document CSS -->
    <style>

    </style>
</head>
<body>

<!-- External JS -->
<script src="demo.js"></script>

<!-- In-document JS -->
<script>

</script>
</body>
</html>

2、HTML标签

  1. 标签必须合法且闭合、嵌套正确,标签名需小写,不要使用HTML5已经废弃的标签。eg:b、 em
  2. 自定义标签需要符合语义化,必须小写
  3. 标签的自定义属性以data-开头,后面跟小写单词,多单词使用下划线连接如:<a data-goods_num='18' href="javascript:;" ></a>
  4. 缩进使用Tab键不要使用空格键,webstorm中使用快捷键command+option+L(Ctrl+Alt+L)对齐
  5. 引入CSS 和 JavaScript 文件时一般不需要指定 type 属性,因为 text/css 和 text/javascript 分别是它们的默认值。css放在上面head中,JavaScript放在body下面紧临</body>
  6. 标签中属性必须添加双引号(非单引号),应该按照特定的顺序出现以保证易读性;属性顺序

    class
    id
    name
    data-*
    src, for, type, href, value , max-length, max, min, pattern
    placeholder, title, alt
    aria-*, role
    required, readonly, disabled
    class是为高可复用组件设计的,所以应处在第一位;
    id更加具体且应该尽量少使用,所以将它放在第二位。
  7. boolean属性指不需要声明取值的属性,XHTML需要每个属性声明取值,但是HTML5并不需要;boolean属性的存在表示取值为true,不存在则表示取值为false。
  8. 在编写HTML代码时,需要尽量避免多余的父节点;很多时候,需要通过迭代和重构来使HTML变得更少。删除无意义的空标签,不要用标签名来设置样式

三、CSS规范

1、CSS引入方式

  • 一般情况使用外部样式表:统一使用link标签,少用@import(原生import有加载性能问题),sass、less、vue.js等文件使用import命令除外(因为最终前端构建工具会将引入文件编译成一个css文件)。

    <link rel="stylesheet" href="xxx.css">
  • 个别情况使用内部样式表:页面非常简单且样式非常少的单独页面,如:纯图片海报页面,纯文字协议页面

    <style>
    ...
    </style>
  • 特殊情况才使用行内样式:如:js动态获取滚动高度:

    style="height:{{scroll_height}}px;"

2、CSS代码风格

  • css头部统一加上@charset声明,如下: @charset "utf-8";
  • 禁止使用ID选择器来定义元素样式
  • 禁止使用层级过深的选择器,最多3级。eg: ul.pro_list > li > p
  • 除非是样式reset需要,禁止对纯元素选择器设置特定样式,避免样式污染

    PC端和移动端通用reset示例

    body,html{width:100%;min-height:100%;/*移动端*/-webkit-user-select:none;user-select:none/*
    禁止选中文本(如无文本选中需求,此为必选项) */}
    body{background-color:#fff;color:#333;font-size:16px;font-family:PingFangSC-Regular}
    a,body,button,dd,div,dl,dt,h1,h2,h3,h4,h5,h6,img,input,li,ol,p,select,table,td,textarea,th,tr,ul{box-sizing:border-box;margin:0;padding:0;border:0}
    button,input,select,textarea{outline:0;font-size:100%}
    h1,h2,h3,h4,h5,h6{font-size:100%} 
    li,ol,ul{list-style:none}
    a{cursor:pointer} 
    a,a:hover{text-decoration:none}
    ::-webkit-input-placeholder{color:#B0B0B0}
    :-moz-placeholder{color:#B0B0B0}
    ::-moz-placeholder{color:#B0B0B0}
    :-ms-input-placeholder{color:#B0B0B0}
  • 媒体查询顺序由大到小

    @media only screen and (max-width: 1080px), only screen and (max-device-width:1080px) {} 
    @media only screen and (max-width: 960px), only screen and (max-device-width:960px) { } 
  • 缩进 使用soft tab(4个空格)
  • 分号 每个属性声明末尾都要加分号。
  • 引号 最外层统一使用双引号;url的内容要用引号;属性选择器中的属性值需要引号。
  • 空格

    以下几种情况不需要空格:

    属性名后
    多个规则的分隔符','前
    !important '!'后
    属性值中'('后和')'前
    行末不要有多余的空格

    以下几种情况需要空格:

    属性值前
    选择器'>', '+', '~'前后
    '{'前
    !important '!'前
    @else 前后
    属性值中的','后
    注释'/*'后和'*/'前
  • CSS属性的声明顺序与性能无关,但是为了易于阅读统一规范 按如下顺序

    .declaration-order {
        /* 定位 */
        position: absolute;
        top: 0;
        right: 0;
        bottom: 0;
        left: 0;
        z-index: 100;
        float: right;
        /* 盒模型 */
        display: block;
        width: 100px;
        height: 100px;
        /* 外观 */
        border: 1px solid #e5e5e5;
        border-radius: 3px;
        background-color: #f5f5f5;
        /* 排版 */
        color: #333;
        text-align: center;
        font: normal 13px "Helvetica Neue", sans-serif;
        line-height: 1.5;
        /*透明度*/
        opacity: 1;
    }
  • 采用flex布局
  • 项目上线前先添加兼容性前缀 Autoprefixer,然后压缩代码

2、CSS框架

四、Javascript规范

1、Javascript引入方式

  • 一般情况使用外部js:统一使用<script>标签,少用@import(原生import有加载性能问题), 使用webpack等打包工具的项目使用import命令除外。js在body底部紧贴</body>引用,先引框架js的再引工具类js然后私有js的最后写内部的js。如下

     <script src="./plugins/layui/layui.js"></script>
     <script src="./plugins/vue/vue.min.js"></script>
     <script src="./plugins/js/util.js"></script>
     <script src="./js/index.js"></script>
     <script> ... </script>
    优点:
    1.页面代码跟js代码实现有效分离,降低耦合度
    2.便于代码的维护和扩展
    3.有利于代码的复用
  • 内部js: 在直接在页面的<script></script>标签内写js代码,vue项目多用此方式

    <script>
        layui.use('console', layui.factory('console'));
    </script>
    优点:内部js代码较为集中,与页面结构的实现代码耦合度较低,比较便于维护
    缺点:js代码仅限于当前页面的使用,代码无法被多个页面重复使用,导致代码冗余度较高
  • 行内js: 直接嵌套在html的语句

    <input type="button" onclick="alert('行内引入')" value="button" name="button">
    开发中不推荐这种方式
    1.因为这种方式跟页面结构代码耦合性太强了,后期维护很不方便,
    2.而且这种方式在开发过程中会导致产生很多的冗余代码

2、Javascript代码编写

  • 目前只在使用了webpack等打包工具的时候才能用ES6语法,所以一般项目还是采用ES5。
  • 一条语句通常以分号作为结束符。
  • 变量必须先声明再使用,即在每个作用域开始前声明这些变量。
  • 函数声明使用表达式方式

    // bad
      const fn= function () {
      };
    // good
      function fn() {
      }
  • 除了三目运算,if,else等禁止简写

     console.log(name);
     // 不推荐的书写
     if (true)
         alert(name);
     console.log(name);
     // 不推荐的书写
     if (true)
     alert(name);
     console.log(name)
    
     // 正确的书写
     if (true) {
         alert(name);
     }

    使用三元运算符,但不要滥用

    (type==1?(agagin==1?'再售':'已售'):'未售')
     // 再多就不要用三元运算符!

3、Javascript框架以及插件

  • 必须掌握jQuery和Vue
  • 工作中jQuery一般用在维护老项目,新项目一般都采用Vue。其他框架稍作了解,遇到了去查文档。(业余时间可以自学angular和React以及你喜欢的框架)
  • 移动端:Mint UI
  • PC端官网、商城: Element
  • PC端后台管理系统:layui或者 iView
  • 轮播图:swiper
  • 滚动插件:iScrollbetter-scroll
  • 响应式官网: 尽量使用媒体查询自定义样式,不推荐使用bootstrap(因为我不喜欢记那一堆类名^_^)。
  • 将常用的功能封装在util.js中,大家共同完善;方便以后使用。

参考
Code Guide by @AlloyTeam
页面前端规范

阅读 2.2k更新于 3月15日
推荐阅读
前端那些事
用户专栏

爱前端爱生活

32 人关注
21 篇文章
专栏主页
目录