本文参考内容:
京东凹凸实验室前端代码规范 :https://guide.aotu.io/docs/js/react.html
vue风格指南:https://cn.vuejs.org/v2/style-guide/index.htm
HTML规范
<!-- HTML文件必须加上 DOCTYPE 声明,并统一使用 HTML5 的文档声明: --><!DOCTYPE html>
<!-- 优先使用 IE 最新版本和 Chrome Frame --> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
<!--所有具有开始标签和结束标签的元素都要写上起止标签,某些允许省略开始标签或和束标签的元素亦都要写上 ---><div> <h1>我是h1标题</h1> <p>我是一段文字,我有始有终,浏览器能正确解析</p></div> <!-- 空元素标签都不加 “/” 字符 ---><br>
<!-- 不需要为 css、JS 指定类型属性,HTML5 中默认已包含 --><link rel="stylesheet" href="" ><script src=""></script>
元素属性值
元素属性值可以写上的都写上
推荐:
<input type="text"><input type="radio" name="name" checked="checked" >
不推荐:
<input type=text><input type='text'><input type="radio" name="name" checked >
<!-- 特殊字符引用 如小于号 “<” 和大于号 “>” --><a href="#">more>></a>
代码缩进
我们可以约定4个空格还是2个空格:商量确定tab:缩进2
<!--统一使用四个空格进行代码缩进,使得各编辑器表现一致(各编辑器有相关配置) --><div class="jdc"> <a href="#"></a></div>
<!-- 移动端 --><!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, shrink-to-fit=no" ><meta name="format-detection" content="telephone=no" > <!-- PC端 --><!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8"><meta name="keywords" content="your keywords"><meta name="description" content="your description"><meta name="author" content="author,email address"><meta name="robots" content="index,follow"><meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1"><meta name="renderer" content="ie-stand">
DNS Prefetch 是一种DNS 预解析技术,当你浏览网页时,浏览器会在加载网页时对网页中的域名进行解析缓存,这样在你单击当前网页中的连接时就无需进行DNS 的解析,减少用户等待时间,提高用户体验。
详细介绍参考 :https://blog.csdn.net/weixin_30734435/article/details/97847990
<!-- S DNS预解析 --><link rel="dns-prefetch" href=""><!-- E DNS预解析 -->
图片规范CSS Sprites VS Data URIs
CSS Sprites特点
- 减少请求数
- 加速图片的显示
- 维护更新成本大
- 更多的内存消耗,特别是大体积或有过多空白的 Sprites 图
- 图片渗漏,相邻的不需展示的图片有可能出现在展示元素中,特别是在高清设备移动设备上
Data URIs特点(base64编码)
- 减少请求数
- 转换文件体积大,大约比原始的二进制大33%
- IE6 / IE7 不支持
- 图片显示相对较慢,需要更多的CPU消耗
CSS Sprites 使用建议
- 适合使用频率高更新频率低的小图标
- 尽量不留太多的空白
- 体积较大的图片不合并
- 确保要合并的小图坐标数值和合并后的 Sprites 图尺寸均为偶数
Data URIs(base64编码)使用建议
- 适合更新频率高的小图片,如某些具备自定义功能的标题icon等
- 转换成 Base64 编码的图片应小于 2KB
- 移动端不使用 Base64 编码
- 要兼容 IE6/IE7 的不使用
css规范
css属性书写顺序
mozilla官方属性顺序推荐
建议遵循以下顺序: (stylelint)
- 布局定位属性:display / position / float / clear / visibility / overflow
- 自身属性:width / height / margin / padding / border / background
- 文本属性:color / font / text-decoration / text-align / vertical-align / white- space / break-word
- 其他属性(CSS3):content / cursor / border-radius / box-shadow / text-shadow / background:linear-gradient …
.jdc { display: block; position: relative; float: left; width: 100px height: 100px; margin: 0 10px; padding: 20px 0; font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; color: #333; background: rgba(0,0,0,.5); -webkit-border-radius: 10px; -moz-border-radius: 10px; -o-border-radius: 10px; -ms-border-radius: 10px; border-radius: 10px;}
-webkit-tap-highlight-color
在 IOS Safari 上,当用户点击链接或具有 JAVAScript 可点击脚本的元素,系统会为这些被点击元素加上一个默认的透明色值,该属性可以覆盖该透明值
-webkit-line-clamp
限制在一个块元素显示的文本的行数。 为了实现该效果,它需要组合其他外来的WebKit属性 常见结合属性:
- display: -webkit-box:必须结合的属性,将对象作为弹性伸缩盒子模型显示。
- -webkit-box-orient:必须结合的属性,设置或检索伸缩盒对象的子元素的排列方式。
- text-overflow:可以用来多行文本的情况下,用省略号“…”隐藏超出范围的文本。
-webkit-user-modify
定义用户是否可编辑元素内容
属性值
- ead-only:只读
- read-write:可读可写,粘贴内容会保留富文本格式( Android 机不保留富文本格式 )
- read-write-plaintext-only:可读可写,粘贴内容所有富文本格式都会丢失
注意:使用这个属性的时候,请不要出现 -webkit-user-select: none,文本无法选中的情况下,在 Safari 该属性不生效,不过在 Chrome 依然生效
-Apple-system
苹果操作系统会从两种不同外观和大小的字体进行自动转换去调节系统新字体 “San Francisco”,可以通过 CSS 规则
font-family: -apple-system , sans-serif;
让系统智能选择适配操作系统的字体,添加 -apple-system 可以使字体变得更圆润锐利。
关于 -apple-system 更详细的介绍可以参考:
What’s New in Safari 9.0
兼容性
- iOS 9.0 及更高版本
- Safari 9.0 及更高版本
- iOS / OS X only
命名规范
目录命名
- 项目文件夹:projectname
- 样式文件夹:css
- 脚本文件夹:js
- 样式类图片文件夹:img
图片命名
图片业务(可选) +(mod_)图片功能类别(必选)+ 图片模块名称(可选) + 图片精度(可选)
- 图片业务:
- wx_:微信
- jd_:京东商城
- …
- 图片功能类别:
- mod_:是否公共,可选
- icon:模块类固化的图标
- logo:LOGO类
- spr:单页面各种元素合并集合
- btn:按钮
- bg:可平铺或者大背景
- …
- 图片模块名称:
- goodslist:商品列表
- goodsinfo:商品信息
- userava tar:用户头像
- …
- 图片精度:
- 普清:@1x
- Retina:@2x | @3x
- …
HTML/CSS文件命名
确保文件命名总是以字母开头而不是数字,且字母一律小写,以下划线连接且不带其他标点符号
目前html还是保留驼峰写法。
<!-- HTML -->jdc.htmljdc_list.htmljdc_detail.html <!-- SASS -->jdc.scssjdc_list.scssjdc_detail.scss
ClassName命名
ClassName的命名应该尽量精短、明确,必须以字母开头命名,且全部字母为小写,单词之间统一使用下划线 “_” 连接
祖先模块不能出现下划线,除了是全站公用模块,如 mod_ 系列的命名:
当子孙模块超过4级或以上的时候,可以考虑在祖先模块内具有识辨性的独立缩写作为新的子孙模块
推荐:
<div class="modulename"> <div class="modulename_info"> <div class="modulename_son"></div> <div class="modulename_son"> <div class="modulename_son_user"> <img src="" alt=""> <!-- 这个时候 miu 为 modulename_info_user 首字母缩写--> <div class="miu_tit"></div> <div class="miu_txt"></div> ... </div> </div> ... </div> </div> <!-- 这个是全站公用模块,祖先模块允许直接出现下划线 --> <div class="mod_info"> <div class="mod_info_son"></div> <div class="mod_info_son"></div> ... </div>
模块命名
全站公共模块:以 mod_ 开头
<div class="mod_yours"></div>
业务公共模块:以 业务名_mod_ 开头
<div class="paipai_mod_yours"></div>
常用命名推荐
注意:ad、banner、gg、guanggao 等有机会和广告挂勾的字眠不建议直接用来做ClassName,因为有些浏览器插件(Chrome的广告拦截插件等)会直接过滤这些类名,因此
<div class="ad"></div>
这种广告的英文或拼音类名不应该出现
另外,敏感不和谐字眼也不应该出现,如:
<div class="fuck"></div><div class="jer"></div><div class="sm"></div><div class="gcd"></div><div class="ass"></div><div class="KMT"></div>...
JS规范
React&JSX 书写规范
基本规则
- 每个文件只包含一个 React 类组件
- 但是多个函数式组件可以放到一个文件中,eslint: react/no-multi-comp
- 一般使用 JSX 语法
- 除非是在非 JSX 文件中初始化应用,否则不要使用 React.createElement
命名规范
- 组件文件扩展名
如果使用 JavaScript,则文件扩展名为 .js;如果使用 TypeScript,则文件扩展名为 .tsx
- 组件文件名
如果是组件文件,则使用 PascalCase,如 MyComponent.js
如果组件是一个目录,则组件主入口命名为 index,如 index.js
- 引用命名
React 组件使用 PascalCase,组件实例使用 CamelCase,eslint: react/jsx-pascal-case
// bad import reservationCard from './ReservationCard'// good import ReservationCard from './ReservationCard'// bad const ReservationItem = <ReservationCard />// good const reservationItem = <ReservationCard />
对齐
遵循以下JSX语法的对齐风格,eslint: react/jsx-closing-bracket-location
// bad <Foo superLongParam='bar' anotherSuperLongParam='baz' /> // good <Foo superLongParam='bar' anotherSuperLongParam='baz'/> // if props fit in one line then keep it on the same line <Foo bar='bar' /> // children get indented normally<Foo superLongParam='bar' anotherSuperLongParam='baz'> <Quux /></Foo> // bad{showButton && <Button />}// bad { showButton && <Button />} // good{showButton && ( <Button />)} // good {showButton && <Button />}
空格
自闭合的标签前要加一个空格,eslint: no-multi-spaces, react/jsx-tag-spacing
// bad<Foo/> // bad <Foo/> // good<Foo />
不要在 JSX 的花括号里边加空格,eslint: react/jsx-curly-spacing
// bad<Foo bar={ baz } />// good<Foo bar={baz} />
引号
JSX 属性要使用单引号,与其他普通 JS 保持一致
// bad<Foo bar="bar" />// good<Foo bar='bar' /> // bad <Foo style={{ left: "20px" }} /> // good <Foo style={{ left: '20px' }} />
属性
属性名使用 CamelCase
// bad <Foo UserName='hello' phone_number={12345678} /> // good <Foo userName='hello' phoneNumber={12345678}/>
当属性值为true时可以省略, eslint:react/jsx-boolean-value
// bad <Foo hidden={true}/> // good <Foo hidden/> // good <Foo hidden />
避免使用数组的索引作为 key 属性值, 建议使用稳定的ID,eslint:react/no-array-index-key
原因:不使用稳定的 ID 会对性能产生副作用并且组件状态会出问题,是一种反模式
为所有的非必需属性定义使用 defaultProps 明确的默认值
Refs
避免使用字符串引用,请使用回调函数作为引用,eslint: react/no-string-refs
// bad <Foo ref='myRef' /> // good <Foo ref={ref => { this.myRef = ref }} />
圆括号
当 JSX 标签超过一行时使用圆括号包裹, eslint: react/wrap-multilines
// bad render () { return <MyComponent className='long body' foo='bar'> <MyChild /> </MyComponent> } // good render () { return ( <MyComponent className='long body' foo='bar'> <MyChild /> </MyComponent> ) } // good, when single line render () { const body = <div>hello</div> return <MyComponent>{body}</MyComponent> }
标签
没有子元素的标签请自闭合,eslint: react/self-closing-comp
// bad <Foo className='stuff'></Foo> // good <Foo className='stuff' />
如果组件包含多行属性,在新的一行闭合标签,eslint:react/jsx-closing-bracket-location
// bad <Foo bar='bar' baz='baz' /> // good <Foo bar='bar' baz='baz' />
vue规范
参考官网:https://cn.vuejs.org/v2/style-guide/index.html
组件名为多个单词(必要)
组件名应该始终是多个单词的,根组件 App 以及 <transition>、<component> 之类的 Vue 内置组件除外。
这样做可以避免跟现有的以及未来的 HTML 元素相冲突,因为所有的 HTML 元素名称都是单个单词的。
组件数据(必要)
组件的 data 必须是一个函数。
当在组件中使用 data property 的时候 (除了 new Vue 外的任何地方),它的值必须是返回一个对象的函数。
// In a .vue file export default { data () { return { foo: 'bar' } } } // 在一个 Vue 的根实例上直接使用对象是可以的// 因为只存在一个这样的实例。new Vue({ data: { foo: 'bar' } })
Prop 定义(必要)
Prop 定义应该尽量详细。
为 v-for 设置键值(必要)
永远不要把 v-if 和 v-for 同时用在同一个元素上 一般我们在两种常见的情况下会倾向于这样做:
- 为了过滤一个列表中的项目 (比如 v-for="user in users" v-if="user.isActive")。在这种情形下,请将 users 替换为一个计算属性 (比如 activeUsers),让其返回过滤后的列表。
- 为了避免渲染本应该被隐藏的列表 (比如 v-for="user in users" v-if="shouldShowUsers")。这种情形下,请将 v-if 移动至容器元素上 (比如 ul、ol)。
私有 property 名(必要)
使用模块作用域保持不允许外部访问的函数的私有性。如果无法做到这一点,就始终为插件、混入等不考虑作为对外公共 API 的自定义私有 property 使用 $_ 前缀。并附带一个命名空间以回避和其它作者的冲突 (比如 $_yourPluginName_)
组件文件–强烈推荐
只要有能够拼接文件的构建系统,就把每个组件单独分成文件。
当你需要编辑一个组件或查阅一个组件的用法时,可以更快速的找到它。
单文件组件文件的大小写
单文件组件的文件名应该要么始终是单词大写开头 (PascalCase),要么始终是横线连接 (kebab-case)。
基础组件名
应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头,比如 Base、App 或 V。
单例组件名
只应该拥有单个活跃实例的组件应该以 The 前缀命名,以示其唯一性。
紧密耦合的组件名强烈推荐
和父组件紧密耦合的子组件应该以父组件名作为前缀命名。
如果一个组件只在某个父组件的场景下有意义,这层关系应该体现在其名字上。因为编辑器通常会按字母顺序组织文件,所以这样做可以把相关联的文件排在一起。
模板中的组件名大小写
若组件名大写,vscode编辑器可以高亮提醒,所以商量决定组件使用大写命名方便 查阅
对于绝大多数项目来说,在单文件组件和字符串模板中组件名应该总是 PascalCase 的——但是在 DOM 模板中总是 kebab-case 的。 由于 HTML 是大小写不敏感的,在 DOM 模板中必须仍使用 kebab-case
多个 attribute 的元素
多个 attribute 的元素应该分多行撰写,每个 attribute 一行。
模板中简单的表达式
组件模板应该只包含简单的表达式,复杂的表达式则应该重构为计算属性或方法
应该把复杂计算属性分割为尽可能多的更简单的 property