前端开发规范梳理

一、通用规范

1. 目录构建规范

• src/api 模块的请求方法。应该参考 src/views 中的直接子文件夹的结构，做映射。

• src/assets 项目的静态资源文件。虽然是静态文件(图片，字体，等)，但是还是经过 webpack 处理会好一些，因为有些比较小的文件会被打包到文件，减少请求和压缩第三方包。这个模块的文件，如果还需要扩展，一个单词作为文件夹名字！保持简洁性。

• src/common 公共的动态的脚本、样式。在实际中，样式可能是各种预处理语言写的，请自行组织目录结构。

• src/components 公共组件。放置项目中抽象的基础和业务组件。你应该为每个组件都单独建一个文件夹，以做好组件之间的隔离，并且有一个默认的文件：index.vue 文件，以便引入组件时少写几个字母。默认组件中的文件是一个最小的单位，不应该有依赖其他组件，或操作 state 状态等行为。

• src/http 主要是关于请求方法的封装。建议开发过程中不要修改，因为会影响到全局。

• src/store 数据中心。这部分内容比较多，独立出来，详情参考：数据中心

• src/router 页面路由。默认所有路由映射写在一个文件，如果需要路由模块化，请自行组织。

• src/views 所有业务逻辑的页面。

── project-name

├── public 项目公共目录

│ ├── favicon.ico Favourite 图标

│ └── index.html 页面入口 HTML 模板

├── src 项目源码目录

│ ├── main.js 入口js文件

│ ├── App.vue 根组件

│ ├── api 把所有请求数据的接口，按照模块在单独的JS文件中

│ │ ├── home.js 首页接口

│ │ ├── detail.js 详情页接口，等等

│ │ ···

│ ├── assets 静态资源目录，公共的静态资源，图片，字体等

│ │ ├── fonts 字体资源

│ │ ├── images 图片资源

│ │ ···

│ ├── common 公共脚本，样式，配置，等动态信息

│ │ ├── js 公共脚本

│ │ │ │── utlis.js 公共 JS 工具函数

│ │ │ │── config.js 公共配置

│ │ │ ···

│ │ ├── style 公共样式，可以是各种预处理语言

│ │ │ │── index.css 样式主文件

│ │ │ │── reset.css 重置样式

│ │ │ ···

│ │ ···

│ ├── components 公共组件目录

│ │ ├── confirm 弹框组件

│ │ │ └── index.vue

│ │ ├── scroll 局部内容滚动组件

│ │ │ └── index.vue

│ │ ···

│ ├── http 封装的 HTTP 请求方法

│ │ ├── axios.js Axios 的封装

│ │ ├── jsonp.js JSONP 的封装

│ │ ···

│ ├── store 数据中心

│ │ ├── state.js state 数据源，数据定义

│ │ ├── mutations.js 同步修改 state 数据的方法定义

│ │ ├── mutation-types.js 定义 Mutations 的类型

│ │ ├── actions.js 异步修改 state 数据的方法定义

│ │ ├── getters.js 获取数据的方法定义

│ │ └── index.js 数据中心入口文件

│ ├── routes 前端路由

│ │ └── index.js

│ └── views 页面目录，所有业务逻辑的页面都应该放这里

│ ├── home 应用首页

│ │ └── index.vue

│ ···

├── .env.development Vue 开发环境的配置

├── .env.production Vue 生成环境的配置

├── .eslintrc.js Eslint 配置文件

├── .gitignore Git 忽略文件

├── package.json 包依赖文件

├── package-lock.json 依赖包版本管理文件

├── README.md 项目介绍

├── vue.config.js vue/cli 项目脚手架配置

···复制代码

1. 组件/实例的选项顺序

• name
• components / directives / filters
• extends / mixins
• model / props / propsData
• data / computed
• watch / 生命周期钩子
• methods

<script>

export default {

name: 'ExampleName', // 这个名字推荐：大写字母开头驼峰法命名。

props: {}, // Props 定义。

components: {}, // 组件定义。

directives: {}, // 指令定义。

mixins: [], // 混入 Mixin 定义。

data () { // Data 定义。

return {

dataProps: '' // Data 属性的每一个变量都需要在后面写注释说明用途

}

},

computed: {}, // 计算属性定义。

created () {}, // 生命钩子函数，按照他们调用的顺序。

mounted () {}, // 挂载到元素。

activated () {}, // 使用 keep-alive 包裹的组件激活触发的钩子函数。

deactivated () {}, // 使用 keep-alive 包裹的组件离开时触发的钩子函数。

watch: {}, // 属性变化监听器。

methods: { // 组件方法定义。

publicbFunction () {} // 公共方法的定义，可以提供外面使用

_privateFunction () {} // 私有方法，下划线定义，仅供组件内使用。

}

}

</script>复制代码

1. 元素特性的顺序

• is

• v-for / v-if / v-else-if / v-else / v-show / v-cloak

• v-pre / v-once

• id

• ref / key / slot

• v-model

• v-on

• v-html / v-text

4. 基本原则：结构、样式、行为分离

• 尽量确保文档和模板只包含 HTML 结构，样式都放到 css 样式表里，行为都放到 js 脚本里
• 标记应该是结构良好、语义正确。
• Javascript应该起到渐进式增强用户体验的作用 。

1. 注释

写注释时请一定要注意：写明代码的作用，重要的地方一定记得写注释。 没必要每份代码都描述的很充分，它会增重HTML和CSS的代码。这取决于该项目的复杂程度。

5.1 单行注释说明：

单行注释以两个斜线开始，以行尾结束

// 调用了一个函数

setTitle();var maxCount = 10; // 设置最大量复制代码

5.2 多行注释

/*

* 代码执行到这里后会调用setTitle()函数

* setTitle()：设置title的值

*/复制代码

5.3 函数注释

/**

* 以星号开头，紧跟一个空格，第一行为函数说明

* @param {类型} 参数 单独类型的参数

* @param {[类型|类型|类型]} 参数 多种类型的参数

* @param {类型} [可选参数] 参数 可选参数用[]包起来

* @return {类型} 说明

* @author 作者 创建时间 修改时间（短日期）改别人代码要留名

* @example 举例（如果需要）

*/复制代码

5.4 文件头注释

推荐：VScode 文件头部自动生成注释插件：koroFileHeader

5.5 条件注释

<!--[if IE 9]>

.... some HTML here ....

<![endif]-->复制代码

二.HTML规范

1. 通用约定

标签

• 自闭合（self-closing）标签，无需闭合 ( 例如： ​img​ ​input​ ​br​ ​hr​ 等 )；
• 可选的闭合标签（closing tag），需闭合 ( 例如：​
​ 或 ​​ )；
• 尽量减少标签数量；

例：

Class 与 ID

• class 应以功能或内容命名，不以表现形式命名；
• class 与 id 单词字母小写，多个单词组成时，采用中划线-分隔；
• 使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class；

<!-- Not recommended --><div class="item-hook left contentWrapper"></div>

<!-- Recommended --><div id="item-hook" class="sidebar content-wrapper"></div>复制代码

属性顺序 HTML 属性应该按照特定的顺序出现以保证易读性。

• id
• class
• name
• data-xxx
• src, for, type, href
• title, alt
• aria-xxx, role

<a id="..." class="..." data-modal="toggle" href="###"></a>

<input class="form-control" type="text">

<img src="..." alt="...">复制代码

嵌套

​​不允许嵌套 ​