《规范》前端编码规范

最新推荐文章于 2025-05-29 23:36:24 发布

peixiancccc

最新推荐文章于 2025-05-29 23:36:24 发布

阅读量445

点赞数 3

分类专栏：程序员文章标签：前端

本文链接：https://blog.youkuaiyun.com/peixiancccc/article/details/138942826

版权

程序员专栏收录该内容

302 篇文章

订阅专栏

组件名以单词大写开头，当多个单词拼写成的组件时，采用驼峰式命名规则。一般是多个单词全拼，减少简写的情况。

组件应该都放到 components 文件夹下，单个页面独立一个文件夹，用来放相对应的 vue 文件以及页面相关的样式文件，样式少可直接写到页面组件里边，这样更符合组件化的思想。

公用组件应该统一放到 public 文件下。

基础组件

当项目中需要自定义比较多的基础组件的时候，比如一些 button，input，icon，建议以一个统一的单词 Base 开头，或者放到 base 文件夹统一管理，这样做的目的是为了方便查找。

页面级组件应该放到相对应页面文件夹下，比如一些组件只有这个页面用到，其他地方没有用到的，可以直接放到页面文件夹，然后以父组件开头命名，例如：HomeHeader.vue,HomeNav.vue。

项目级组件一般放到公共文件夹 public 下给所有的页面使用。

组件结构

组件结构遵循从上往下 template，script，style 的结构。

编码规范

==============================================================

HTML / Template 编码规范

语法

【强制】缩进使用两个空格代替 Tab;

前端代码层级较深，使用短缩进有利于利用屏幕空间，提升效率；
使用两个空格代替 Tab 可以保证在所有环境下获得一致展现；

bar

【强制】嵌套元素应当缩进一次（即两个空格），同层级缩进应保持一致；

bar

【强制】对于属性的定义，使用双引号，不要使用单引号

【强制】不要省略可选的结束标签（closing tag）（如或）省略可选的结束标签，虽不会违反 H5 规范；但可能会造成层级上的困扰，导致代码出现无法预料的问题

h1 text

h2 text

h1 text

h2 text

【强制】特殊符号使用 HTML 字符实体（实体名称对大小写敏感），常用如下：

空格：

©：©

¥：¥

®：®

：>

<：<

&：&

【强制】td / th 要在 tr 里面，li 要在 ul / ol 里面；

test

【强制】行内元素里面不可使用块级元素

a 标签是一个行内元素，行内元素里面套了一个 div的标签，这样可能会导致 a 标签无法正常点击，可以使用如下代码进行修复： + … … .

【强制】不使用自定义HTML标签，会与Vue组件系统的自定义组件冲突

【强制】不使用重复属性，重复的属性只会取第一个

【强制】不要在https的链接里写http的图片

只要https的网页请求了一张http的图片，就会导致浏览器地址栏左边的小锁没有了，一般不要写死，写成根据当前域名的协议去加载，用//开头:

【推荐】不要在自闭合（self-closing）元素的尾部添加斜线（ HTML5 规范中说明这是可选的）

【推荐】不使用属性设置样式（img, table等元素

【参考】自定义属性要以data-开头自己添加的非标准的属性要以data-开头，否则w3c validator会认为是不规范的

【强制】为每个 HTML 页面添加标准模式（standard mode）的声明，确保在每个浏览器中拥有一致的展现

…

【强制】强烈建议为 html 根元素指定 lang 属性，从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音，有助于翻译工具确定其翻译时所应遵守的规则等等。

【强制】通过声明一个明确的字符编码，让浏览器轻松、快速的确定网页内容渲染方式，通常指定为’UTF-8’

…

【强制】根据 HTML5 规范，在引入 CSS 和 JavaScript 文件时不需要指定 type 属性，因为 text/css 和 text/javascript 分别是它们的默认值

【推荐】编写 HTML 代码时，尽量避免多余的层级

【参考】属性应该按照特定的顺序出现以保证易读性

1.class

2.id

3.name

4.data-*

5.src, for, type, href, value , max-length, max, min, pattern

6.placeholder, title, alt

7.aria-*, role

8.required, readonly, disabled

【参考】尽量遵循 HTML 标准和语义，但是不要以牺牲实用性为代价；任何时候都要尽量使用最少的标签并保持最小的复杂度。

CSS / Less 编码规范

命名

【强制】类名使用小写字母，以中划线分隔

【强制】id 采用驼峰式命名

【强制】less 中的变量、函数、混合等采用驼峰式命名

@mainFontColor: #444;

#companyName,

.company-name {

color: @mainFontColor;

}

语法

【强制】所有声明语句都应当以分号结尾最后一条声明语句后面的分号是可选的，但是，如果省略这个分号，你的代码可能更易出错

/* error */

.selector {

font-size: 15px

color: red

}

/* not good */

.selector {

font-size: 15px;

color: red

}

/* good */

.selector {

font-size: 15px;

color: red;

}

【强制】避免为 0 值指定单位，例如，用 margin: 0; 代替 margin: 0px;

【强制】为选择器中的属性添加双引号，例如，input[type=“text”]；某些情况下是可选的，但是，为了代码的一致性，建议都加上双引号

/* not good */

/* … */

}

/* good */

/* … */

}

【推荐】十六进制值应该全部小写，例如，#f3f6fa

【强制】不出现空的规则（声明块中没有声明语句）

【推荐】不要设置太大的 z-index（一个正常的系统的层级关系在 10 以内就能完成）

【强制】多写注释，且多使用句子进行描述而不是词语

/* 为了去除输入框和表单点击时的灰色背景 */

input,

form {

-webkit-tap-highlight-color: rgba(255, 255, 255, 0);

}

【推荐】不要使用*选择器

【推荐】适当使用:before 和:after 来画页面的一些视觉上的辅助性元素，如三角形、短的分隔线、短竖线等，可以减少页面上没有用的标签

【推荐】选择器不要超过 4 层（在 Less 中避免嵌套超过 4 层）

【推荐】用 border: 0; 代替 border: none;

【推荐】使用简写形式的十六进制值，例如，用 #fff 代替 #ffffff

【推荐】对于属性值或颜色参数，省略小于 1 的小数前面的 0 （例如，.5 代替 0.5；-.5px 代替 -0.5px）

代码风格

此处大部分工作将由代码格式化工具完成（参见环境要求），一般无需考虑

【强制】缩进使用两个空格代替 Tab

【强制】为选择器分组时，将单独的选择器单独放在一行 +

/* not good */

.selector, .selector-secondary, .selector[type=text] {

/* … */

}

/* good */

.selector,

.selector-secondary,

/* … */

}

【强制】声明块的左花括号前添加一个空格

【强制】声明块的右花括号应当单独成行

【强制】每条声明语句的 : 后应该插入一个空格

【强制】每条样式声明应该独占一行

/* not good */

.selector {

font-size: 15px; color: red;

}

/* good */

.selector {

font-size: 15px;

color: red;

}

【强制】对于以逗号分隔的属性值，每个逗号后面都应该插入一个空格（例如，box-shadow，transition）

/* not good */

.selector {

transition: border .2s,color .3s,padding .4s;

}

/* good */

.selector {

transition: border .2s, color .3s, padding .4s;

}

【强制】!important 前插入一个空格

【强制】注释：//后插入一个空格，/后插入一个空格，/前插入一个空格

【强制】Less 的操作符，在圆括号中的数学计算表达式的数值、变量和操作符之间均添加一个空格

【推荐】注释统一用/* */（ Less 中也不要用//）

样式兼容性

【强制】当使用一些较新的 CSS3 语法时，应注意添加浏览器前缀（ FAIS 2 打包工具包含 CSS 预处理，固无需考虑此条）

【推荐】不要使用 input 的 line-height 来做垂直居中设置 line-height 为一个很高的值会导致 Safari 浏览器的输入光标变得巨大 (与 line-height 等高)

/* not good */

input {

height: 40px;

line-height: 40px;

}

/* good */

input {

height: 20px;

line-height: 20px;

padding: 10px 0;

}

选择器权重（样式覆盖）

权重的基本规则：

相同的权重：以后面出现的选择器为最后规则
不同的权重，权重值高则生效

详细了解权重计算方法

【强制】非通用样式使用嵌套方式进行编写，避免影响其他自己不了解样式，造成样式覆盖

【推荐】Vue 中样式谨慎使用 scoped，会影响样式选择器性能，请使用第一点进行特有样式编写

【推荐】样式需要修改时，尽量找到原样式声明进行修改

【强制】无法修改原样式声明时，应通过权重关系，编写权重更高的样式进行覆盖

【推荐】不使用!important，除非原样式使用内联样式或!important 且无法直接修改

声明简写

【推荐】当你不确定自己写的属性会否影响到其他属性时，应避免使用简写

/* error */

.element {

margin: 0 0 10px;

background: red;

background: url(“image.jpg”);

border-radius: 3px 3px 0 0;

}

/* good */

.element {

margin-bottom: 10px;

background-color: red;

border-top-left-radius: 3px;

border-top-right-radius: 3px;

}

【推荐】当你确定自己的声明不会影响到其他属性时，请使用简写提升代码简洁性

/* not good */

.element {

padding-top: 10px;

padding-right: 20px;

padding-bottom: 15px;

padding-left: 20px;

}

/* good */

.element {

padding: 10px 20px 15px;

}

CSS 动画

【推荐】不要使用 all 属性做动画

使用 transition 做动画的时候不要使用 all 所有属性，在有一些浏览器上面可能会有一些问题，如下： +

transition: all 2s linear;

在 Safari 上面可能会有一些奇怪的抖动，正确的做法是要用哪个属性做动画就写哪个，如果有多个就用隔开，如下代码所示：

transition: transform 2s linear, opacity 2s linear;

【推荐】位移动画使用 transform 替代 position （提升动画性能）

【推荐】使用 CSS 动画替代 JS 动画

声明顺序

【参考】相关的属性声明按以下顺序做分组处理，组之间需要有一个空行

Positioning（影响其他元素和自身位置相关声明）
Box model（自身盒模型相关声明）
Typographic（文本相关声明）
Visual（自身样式）
Misc（其他声明）

.declaration-order {

/* Positioning */

position: absolute;

top: 0;

right: 0;

bottom: 0;

left: 0;

z-index: 100;

/* Box-model */

display: block;

float: right;

width: 100px;

height: 100px;

/* Typography */

font: normal 13px “Helvetica Neue”, sans-serif;

line-height: 1.5;

color: #333;

text-align: center;

/* Visual */

background-color: #f5f5f5;

border: 1px solid #e5e5e5;

border-radius: 3px;

/* Misc */

opacity: 1;

}

JavaScript 编码规范

命名

【强制】标准变量采用驼峰式命名（考虑与后台交换数据的情况，对象属性可灵活命名）

【强制】常量全大写，用下划线连接

【强制】变量名不应过短，要能准确完整地描述该变量所表述的事物

//不好的变量名

inp

day1, day2, param1

obj

tId

handler

//好的变量名

input, priceInput

today, tomorrow

userId, orderId

orderData, houseInfos

removeMsgTimerId

submitHandler, searchHandler

【强制】变量名不要使用计算机术语，如 texareaData，应该取和业务相关的名字，如 leaveMsg

【强制】变量名的对仗要明确，如 up/down、begin/end、opened/closed、visible/invisible、scource/target

【强制】变量名使用正确的语法

不要使用中文拼音，如 shijianchuo 应改成 timestamp ；如果是复数的话加 s，或者加上 List，如 orderList、menuItems；而过去式的加上 ed，如 updated/found 等；如果正在进行的加上 ing，如 calling；

【推荐】使用临时变量时请结合实际需要进行变量命名

有些喜欢取 temp 和 obj 之类的变量，如果这种临时变量在两行代码内就用完了，接下来的代码就不会再用了，还是可以接受的，如交换数组的两个元素。但是有些人取了个 temp，接下来十几行代码都用到了这个 temp，这个就让人很困惑了。所以应该尽量少用 temp 类的变量

// not good

let temp = 10;

let leftPosition = currentPosition + temp，

topPosition = currentPosition - temp;

// good

let adjustSpace = 10;

let leftPosition = currentPosition + adjustSpace，

topPosition = currentPosition - adjustSpace;

【推荐】波尔变量可以结合实际语境使用 done/found/successs/ok/available/complete 等修饰词

// good

let ajaxDone = true,

fileFound = false,

resourceUpdated = true;

【推荐】波尔变量名应使用肯定的布尔变量名，不要使用否定的名词，如 notOk、notReady，因为否定的词取反的时候就会比较奇怪，如 if (!notOk)

语法

【强制】变量不要先使用后声明

【强制】不要声明了变量却不使用

【强制】不要在同个作用域下声明同名变量

【强制】一个函数作用域中所有的变量声明尽量提到函数首部，可根据代码进行分组，但不允许出现两个连续的变量声明

// not good

let registerForm = null;

let question = “”;

let calculateResult = 0;

// good

let registerForm = null,

question = “”,

calculateResult = 0;

【强制】为了快速知晓变量类型，声明变量时要赋值

// not good

let registerForm,

question,

calculateResult;

// good

let registerForm = null,

question = “”,

calculateResult = 0;

. 【强制】单一函数的返回值类型要确定（如下无法确定该函数的最终返回类型）

// not good

function calculatePrice(seatCount){

if (seatCount <= 0) {

return “”;

} else {

return seatCount * 79;

}

【强制】debugger 不要出现在提交的代码里

【推荐】使用=代替，!==代替!=（==会自动进行类型转换，可能会出现奇怪的结果）

null == undefined //true

‘’ == ‘0’ //false

0 == ‘’ //true

0 == ‘0’ //true

’ \t\r\n ’ == 0 //true

new String(“abc”) == “abc” //true

new Boolean(true) == true //true

true == 1 //true

【推荐】使用三目运算代替简单的 if-else

// not good

let seatDiscount = 100;

if (seat < 5) {

seatDiscount = 90;

} else if(seat < 10) {

seatDiscount = 80;

} else {

seatDiscount = 70;

}

// good

let seatDiscount = seat < 5 ? 90 : seat < 10 ? 80 : 70;

【推荐】使用 let 定义变量，const 定义常量

【推荐】使用箭头函数取代简单的函数

// not good

let _this = this;

setTimeout(function() {

_this.foo = “bar”;

}, 2000);

// good

setTimeout(() => this.foo = “bar”, 2000);

【推荐】在必要的地方添加非空判断以提高代码的稳健性

【推荐】将复杂的函数分解成多个子函数，方便维护和复用

代码风格

此处大部分工作将由代码格式化工具完成（参见环境要求），一般无需考虑

【强制】缩进使用两个空格代替 Tab

【强制】统一使用双引号""（与 Prettier 默认格式化配置持一致）

【强制】以下几种情况后需加分号;

变量声明
表达式
return
throw
break
continue
do-while

【强制】以下几种情况不需要空格：

对象的属性名后
前缀一元运算符后
后缀一元运算符前
函数调用括号前
无论是函数声明还是函数表达式，’('前不要空格
数组的’[‘后和’]'前
对象的’{‘后和’}'前
运算符’(‘后和’)'前

【强制】以下几种情况需要空格：

二元运算符前后
三元运算符’?:'前后
代码块’{'前
下列关键字前：else, while, catch, finally
下列关键字后：if, else, for, while, do, switch, case, try,catch, finally, with, return, typeof
单行注释’//‘后（若单行注释和代码同行，则’//‘前也需要），多行注释’*'后
对象的属性值前
for 循环，分号后留有一个空格，前置条件如果有多个，逗号后留一个空格
无论是函数声明还是函数表达式，’{'前一定要有空格
函数的参数之间

数组、对象

【强制】对象属性名不需要加引号

【强制】对象以缩进的形式书写，不要写在一行

【强制】数组中不要存在空元素

【强制】不要用 for in 循环数组

【推荐】数组、对象最后不要有逗号

// not good

let a = {

‘b’: 1

};

let a = { b: 1 };

let a = {

b: 1,

c: 2,

};

// good

let a = {

b: 1,

c: 2

};

使用 null

【强制】正确使用 null

适用场景：

初始化一个将来可能被赋值为对象的变量
与已经初始化的变量做比较
作为一个参数为对象的函数的调用传参
作为一个返回对象的函数的返回值
不要用 null 来判断函数调用时有无传参
不要与未初始化的变量做比较

// not good

function test(a, b) {

if (b === null) {

// not mean b is not supply

// …

}

let a;

if (a === null) {

// …

}

// good

let a = null;

if (a === null) {

// …

}

使用 undefined

【强制】正确使用 undefined

不要给变量赋值 undefined（undefined 本身就表示一个变量未定义）
不要直接使用 undefined 进行变量判断
使用 typeof 和字符串 ‘undefined’ 对变量进行判断

// not good

if (person === undefined) {

// …

}

// good

if (typeof person === ‘undefined’) {

// …

}

文档注释

【参考】各类标签 @param, @method 等请参考 usejsdoc 和 JSDoc Guide；

建议在以下情况下使用：所有常量、所有函数、所有类

/**

@func
@desc 一个带参数的函数
@param {string} a - 参数a
@param {number} b=1 - 参数b默认值为1
@param {string} c=1 - 参数c有两种支持的取值1—表示x2—表示xx
@param {object} d - 参数d为一个对象
@param {string} d.e - 参数d的e属性
@param {string} d.f - 参数d的f属性
@param {object[]} g - 参数g为一个对象数组
@param {string} g.h - 参数g数组中一项的h属性
@param {string} g.i - 参数g数组中一项的i属性
@param {string} [j] - 参数j是一个可选参数

function foo(a, b, c, d, g, j) {

// …

}

Vue 组件编码规范

命名

【强制】组件名应该始终是多个单词的，根组件 App 除外

// not good

Vue.component(‘todo’, {

// …

})

export default {

// …

}

// good

Vue.component(‘todo-item’, {

// …

})

export default {

// …

}

【强制】单文件组件的文件名应该要么始终是单词大写开头（ PascalCase ），要么始终是横线连接（ kebab-case ）

// not good

components/

|- mycomponent.vue

components/

|- myComponent.vue

// good

components/

|- MyComponent.vue

components/

|- my-component.vue

【推荐】应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头，比如 Base、App 或 V

// not good

components/

最后

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数初中级Android工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。

因此收集整理了一份《2024年Web前端开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Android开发知识点！不论你是刚入门Android开发的新手，还是希望在技术上不断提升的资深开发者，这些资料都将为你打开新的学习之门！

如果你觉得这些内容对你有帮助，需要这份全套学习资料的朋友可以戳我获取！！

由于文件比较大，这里只是将部分目录截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新！
ring} a - 参数a

@param {number} b=1 - 参数b默认值为1
@param {string} c=1 - 参数c有两种支持的取值1—表示x2—表示xx
@param {object} d - 参数d为一个对象
@param {string} d.e - 参数d的e属性
@param {string} d.f - 参数d的f属性
@param {object[]} g - 参数g为一个对象数组
@param {string} g.h - 参数g数组中一项的h属性
@param {string} g.i - 参数g数组中一项的i属性
@param {string} [j] - 参数j是一个可选参数

function foo(a, b, c, d, g, j) {

// …

}

Vue 组件编码规范

命名

【强制】组件名应该始终是多个单词的，根组件 App 除外

// not good

Vue.component(‘todo’, {

// …

})

export default {

// …

}

// good

Vue.component(‘todo-item’, {

// …

})

export default {

// …

}

【强制】单文件组件的文件名应该要么始终是单词大写开头（ PascalCase ），要么始终是横线连接（ kebab-case ）

// not good

components/

|- mycomponent.vue

components/

|- myComponent.vue

// good

components/

|- MyComponent.vue

components/

|- my-component.vue

【推荐】应用特定样式和约定的基础组件 (也就是展示类的、无逻辑的或无状态的组件) 应该全部以一个特定的前缀开头，比如 Base、App 或 V

// not good

components/

最后

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数初中级Android工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。

[外链图片转存中…(img-I7Okwe9M-1715821292895)]

[外链图片转存中…(img-Om57fmx7-1715821292896)]

[外链图片转存中…(img-rtMGOZR6-1715821292896)]

如果你觉得这些内容对你有帮助，需要这份全套学习资料的朋友可以戳我获取！！

由于文件比较大，这里只是将部分目录截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新！