前端项目规范

菜狗小仪

已于 2022-12-22 09:19:32 修改

阅读量473

点赞数

分类专栏：好用文章标签：前端 javascript vue.js

于 2022-09-28 09:50:21 首次发布

本文链接：https://blog.csdn.net/ewl0116/article/details/127083595

版权

好用专栏收录该内容

3 篇文章 0 订阅

订阅专栏

前端项目规范

版本:version-1.0

编写:Nova

命名规范-简洁版

项目名/JavaScript/Typescript文件/CSS文件/HTML文件:全部小写,中横线分割
图片/svg文件:全部小写,下划线分割
vue
1. vue文件命名:大驼峰
2. 单例文件统一前缀The
3. 基础组件统一前缀Base
4. 紧密耦合组件以父组件名作为前缀命名
5. 完整单词拼写
参数代码命名
1. name:组件名应是多个单词，大驼峰
2. prop:小驼峰
3. route:中横线分割
4. HTML模板的组件:大驼峰
5. 变量:小驼峰
6. 常量:大写+ ‘_’ 下划线分割
7. 方法:小驼峰
8. Vue自定义事件(传值):中横线划分
9. Vue事件方法:小驼峰

1.代码规范

不管有多少人共同参与同一项目，努力做到每一行代码都像是同一个人编写的。

1.1 代码规范-命名规范

1.1.1 项目文件命名

1.1.1.1 项目命名

全部采用小写方式，以中划线分隔。例： my-project-name(按照npm包的命名规范)

1.1.1.2 目录名

参照项目命名规则，有复数结构时，要采用复数命名法。例：docs、assets、components、directives、mixins、utils、views。

1.1.1.3 JavaScript/Typescript文件命名

全部采用小写方式，所有js文件名，多个单词组成时，采用中划线连接方式。例：账号模型文件 account-model.js

1.1.1.4 CSS文件命名

全部采用小写方式，多个单词组成时，采用中划线连接方式：retina-sprites.scss

1.1.1.5 HTML文件命名

全部采用小写方式，多个单词组成时，采用中划线连接方式: error-report.html

1.1.1.6 图片/svg命名

全部采用小写方式，以下划线分隔。例： app-logo.jpg

上述规则可以快速记忆为“静态文件下划线，编译文件短横线”。

1.1.2 VUE文件命名

全部采用大驼峰方式,单文件组件的文件名是单词大写开头 (PascalCase) MyApp.vue

1.2.1 单例组件

只拥有单个活跃实例的组件应该以 The 前缀命名，以示其唯一性。

这不意味着组件只可用于一个单页面，而是每个页面只使用一次。这些组件永远不接受任何 prop，因为它们是为你的应用定制的。如果你发现有必要添加 prop，那就表明这实际上是一个可复用的组件，只是目前在每个页面里只使用一次。

比如，头部和侧边栏组件几乎在每个页面都会使用，不接受 prop，该组件是专门为该应用所定制的。

components/
|- TheHeading.vue
|- TheSidebar.vue

1.2.2 基础组件

基础组件全部以一个特定的前缀开头 —— Base

基础组件：不包含业务，独立、具体功能的基础组件，比如日期选择器、模态框等。这类组件作为项目的基础控件，会被大量使用，因此组件的 API 进行过高强度的抽象，可以通过不同配置实现不同的功能。

应用特定样式和约定的基础组件(也就是展示类的、无逻辑的或无状态、不掺杂业务逻辑的组件) 应该全部以一个特定的前缀开头 —— Base。基础组件在一个页面内可使用多次，在不同页面内也可复用，是高可复用组件。

components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue

1.2.3 紧密耦合的组件名

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。 因为编辑器通常会按字母顺序组织文件，所以这样做可以把相关联的文件排在一起。

components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue

1.2.4 完整单词的组件名

组件名应该倾向于而不是缩写。 编辑器中的自动补全已经让书写长命名的代价非常之低了，而其带来的明确性却是非常宝贵的。不常用的缩写尤其应该避免。

components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue

1.2 参数代码命名

1.2.1 name

组件名应该始终是多个单词，应该始终是大驼峰( PascalCase) 的。 根组件 App 以及 ``、之类的 Vue 内置组件除外。这样做可以避免跟现有的以及未来的 HTML 元素相冲突，因为所有的 HTML 元素名称都是单个单词的。

export default {
  name: 'ToDoList',
  // ...
}
复制代码

1.2.2 prop

**在声明 prop 的时候，其命名应该始终使用小驼峰( camelCase)，而在模板和 JSX 中应该始终使用中横线(kebab-case) **。我们单纯的遵循每个语言的约定，在 JavaScript 中更自然的是小驼峰 (camelCase)。而在 HTML 中则是中横线(kebab-case)。

<WelcomeMessage greeting-text="hi"/>

export default {
  name: 'MyComponent',
  // ...
  props: {
    greetingText: {
      type: String,
      required: true,
      // 可选
      validator: function (value) {
        return ['syncing', 'synced',].indexOf(value) !== -1
      }
    }
  }
}

1.2.3 router

Vue Router Path 命名采用中横线(kebab-case) 格式。 用 Snake（如：/user_info）或 camelCase（如：/userInfo)的单词会被当成一个单词，搜索引擎无法区分语义。

// bad
{
  path: '/user_info', // user_info 当成一个单词
  name: 'UserInfo',
  component: UserInfo,
  meta: {
    title: ' - 用户',
    desc: ''
  }
},

// good
{
  path: '/user-info', // 能解析成 user info
  name: 'UserInfo',
  component: UserInfo,
  meta: {
    title: ' - 用户',
    desc: ''
  }
},

1.2.3 模板中组件

对于绝大多数项目来说，在单文件组件和字符串模板中组件名应该总是大驼峰(PascalCase)的，但是在 DOM 模板中总是 kebab-case 的。

<!-- 在单文件组件和字符串模板中 --> 
<MyComponent/>

<!-- 在 DOM 模板中 --> 
<my-component></my-component>

1.2.4 自闭合组件

在单文件组件、字符串模板和 JSX 中没有内容的组件应该是自闭合的——但在 DOM 模板里永远不要这样做。

<!-- 在单文件组件和字符串模板中 -->
<MyComponent/>

<!-- 在所有地方 -->
<my-component></my-component>

1.2.5 变量

命名方法：camelCase
命名规范：类型 + 对象描述或属性的方式


let tableTitle = "LoginTable"
let mySchool = "我的学校"

1.2.6 常量

命名方法：全部大写下划线分割
命名规范：使用大写字母和下划线来组合命名，下划线用以分割单词

const MAX_COUNT = 10
const URL = 'http://test.host.com'

1.2.7 方法

命名方法：camelCase
命名规范：统一使用动词或者动词 + 名词形式

// 1、普通情况下，使用动词 + 名词形式
// bad
go、nextPage、show、open、login

// good
jumpPage、openCarInfoDialog

// 2、请求数据方法，以 data 结尾
// bad
takeData、confirmData、getList、postForm

// good
getListData、postFormData

// 3、单个动词的情况
init、refresh

动词	含义	返回值
can	判断是否可执行某个动作 (权 )	函数返回一个布尔值。true：可执行；false：不可执行；
has	判断是否含有某个值	函数返回一个布尔值。true：含有此值；false：不含有此值；
is	判断是否为某个值	函数返回一个布尔值。true：为某个值；false：不为某个值；
get	获取某个值	函数返回一个非布尔值
set	设置某个值	无返回值、返回是否设置成功或者返回链式对象

1.2.8 Vue自定义事件

自定义事件应始终使用中横线(kebab-case)的事件名。

不同于组件和 prop，事件名不存在任何自动化的大小写转换。而是触发的事件名需要完全匹配监听这个事件所用的名称。

this.$emit('my-event')
复制代码
<MyComponent @my-event="handleDoSomething" />
复制代码

不同于组件和 prop，事件名不会被用作一个 JavaScript 变量名或 property 名，所以就没有理由使用 camelCase 或 PascalCase 了。并且 v-on 事件监听器在 DOM 模板中会被自动转换为全小写 (因为 HTML 是大小写不敏感的)，所以 v-on:myEvent 将会变成 v-on:myevent——导致 myEvent 不可能被监听到。

原生事件参考列表

由原生事件可以发现其使用方式如下：

<div
  @blur="toggleHeaderFocus"
  @focus="toggleHeaderFocus"
  @click="toggleMenu"
  @keydown.esc="handleKeydown"
  @keydown.enter="handleKeydown"
  @keydown.up.prevent="handleKeydown"
  @keydown.down.prevent="handleKeydown"
  @keydown.tab="handleKeydown"
  @keydown.delete="handleKeydown"
  @mouseenter="hasMouseHoverHead = true"
  @mouseleave="hasMouseHoverHead = false">
</div>

而为了区分原生事件和自定义事件在 Vue 中的使用，建议除了多单词事件名使用 kebab-case 的情况下，命名还需遵守为 on + 动词 的形式，如下：

<!-- 父组件 -->
<div
  @on-search="handleSearch"
  @on-clear="handleClear"
  @on-clickoutside="handleClickOutside">
</div>
复制代码
// 子组件
export default {
  methods: {
    handleTriggerItem () {
      this.$emit('on-clear')
    }
  }
}
复制代码

1.2.9 事件方法

命名方法：camelCase
命名规范：handle + 名称（可选）+ 动词

<template>
  <div
    @click.native.stop="handleItemClick()"
    @mouseenter.native.stop="handleItemHover()">
  </div>
</template>

<script>

export default {
  methods: {
    handleItemClick () {
      //...
    },
    handleItemHover () {
      //...
    }
  }
}
</script>

1.3代码规范-注释规范

1.3.1 JavaScript 文件注释

单行注释

单行注释使用 //，注释应单独一行写在被注释对象的上方，不要追加在某条语句的后面。

推荐：

// is current tab
const active = true

不推荐：

const active = true // is current tab

注释行的上方需要有一个空行（除非注释行上方是一个块的顶部），以增加可读性。

推荐：

function getType () {  
  console.log('fetching type...')
  
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}

// 注释行上面是一个块的顶部时不需要空行
function getType () {  
  // set the default type to 'no type'
  const type = this.type || 'no type'			
  return type
}

不推荐：

function getType () {  
  console.log('fetching type...')
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}

多行注释

如未安装插件多行注释使用 /** ... */，而不是多行的 //。

推荐：

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...

  return element
}

不推荐：

// make() returns a new element
// based on the passed in tag name
function make (tag) {
  // ...

  return element
}

已经安装koroFileHeader插件使用快捷键 ctrl+windows+t

	/**
     * @description: 
     * @param {*} param1
     * @param {*} param2
     * @return {*}
     */    
    function foo(param1: string, param2: string) {
      console.log(param1, param2);
    }
    return {}

注释空格

注释内容和注释符之间需要有一个空格，以增加可读性。eslint: spaced-comment。

推荐：

// is current tab
const active = true

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}

不推荐：

//is current tab
const active = true

/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}

特殊标记

已经安装TODO Highlight插件

有时我们发现某个可能的 bug，但因为一些原因还没法修复；或者某个地方还有一些待完成的功能，这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。常用的特殊标记有两种：

// FIXME : 说明问题是什么
// TODO : 说明还要做什么或者问题的解决方案

class Calculator extends Abacus {
  constructor () {
    super ()

      // FIXME: shouldn’t use a global here
      total = 0

      // TODO: total should be configurable by an options param
      this.total = 0
  }
}

注意事项

当业务代码逻辑极其复杂时,需要进行业务注释,不可只进行单一方法注释

1.4代码规范-提交规范

1.4.1 svn提交规范

提交顺序:
- 先更新后提交
提交前检查:
- 查看本次修改内容
- 是否影响原有功能
- 是否有漏提/误提交操作
- 是否有多余的文件/打印信息未删除
提交频率:
- 独立模块整体完成后提交
冲突解决:
- 一定不能直接覆盖
- 需要进行冲突解决,可以同事进行沟通
注意事项:
- 需要写明本次提交功能
- SVN中的代码始终应保持为生产环境代码
- 实际生产环境的代码不能高于SVN的版本

2. 协作规范

2.1 前后端协作规范

前端/后端开发之前需要有好的沟通数据格式
一般情况下前端不进行超过3层以上的复杂数据加工处理
前端需要进行一定程度的边界情况处理
对象某一字段不论是否为null或者为空,后端应始终返回字段,不要去除此字段,避免赋值报错
接口出参要一致

2.2 前端UI协作规范

UI图需要按照UI设计图进行还原,不能凭借感觉开发
UI图只是原型图,如不确定各模块实际情况,需要与项目组长/经理进行沟通后进行开发,避免出现返工情况

2.3 部署规范

非脚手架项目应有config.js配置文件,通过生产/开发环境标志位进行更改生产/开发环境配置,不建议每次手动更改url等信息
部署前修改过的代码须在测试环境中试运行后再进行部署
演示等特殊情况下部署需要备份好代码,防止出现错误后生产环境无法使用

3. 项目组织

3.1 项目组织

待补充

3.2 vue 项目组织

export default {
    name: '',
    /*1. Vue扩展 */
    extends: '', // extends和mixins都扩展逻辑，需要重点放前面
    mixins: [],   
    components: {},
    /* 2. Vue数据 */
    props: {},
    model: { prop: '', event: '' }, // model 会使用到 props
    data () {
        return {}
    },
    computed: {},
    watch:{}, // watch 监控的是 props 和 data，有必要时监控computed
    /* 3. Vue资源 */
    filters: {},
    directives: {},
    /* 4. Vue生命周期 */
    created () {},
    mounted () {},
    destroy () {},
    /* 5. Vue方法 */
    methods: {}, // 所有的方法应该被放在最后
}

3.3 prettier文档规范(.prettierrc.js)

module.exports = {
    // 一行最多多少个字符
    printWidth: 150,
    // 指定每个缩进级别的空格数
    tabWidth: 4,
    // 使用制表符而不是空格缩进行
    useTabs: false,
    // 在语句末尾打印分号
    semi: true,
    // 使用单引号而不是双引号
    singleQuote: true,
    // 更改引用对象属性的时间 可选值"<as-needed|consistent|preserve>"
    quoteProps: 'as-needed',
    // 在JSX中使用单引号而不是双引号
    jsxSingleQuote: false,
    // 多行时尽可能打印尾随逗号。（例如，单行数组永远不会出现逗号结尾。） 可选值"<none|es5|all>"，默认none
    trailingComma: 'es5',
    // 在对象文字中的括号之间打印空格
    bracketSpacing: true,
    // jsx 标签的反尖括号需要换行
    jsxBracketSameLine: false,
    // 在单独的箭头函数参数周围包括括号 always：(x) => x \ avoid：x => x
    arrowParens: 'always',
    // 这两个选项可用于格式化以给定字符偏移量（分别包括和不包括）开始和结束的代码
    rangeStart: 0,
    rangeEnd: Infinity,
    // 指定要使用的解析器，不需要写文件开头的 @prettier
    requirePragma: false,
    // 不需要自动在文件开头插入 @prettier
    insertPragma: false,
    // 使用默认的折行标准 always\never\preserve
    proseWrap: 'preserve',
    // 指定HTML文件的全局空格敏感度 css\strict\ignore
    htmlWhitespaceSensitivity: 'css',
    // Vue文件脚本和样式标签缩进
    vueIndentScriptAndStyle: false,
    // 换行符使用 lf 结尾是 可选值"<auto|lf|crlf|cr>"
    endOfLine: 'lf',
};

其他

常用工具

截图工具-snipaste

基本用法:
- F1截屏
- F3贴屏
- 按C粘贴颜色值
- 按shift切换rgb/HEX
gif录制工具-gifcam
文件搜索工具-Listary
github加速工具-fastgithub
远程工具-ToDesk
文件夹管理-QTTabBar https://zhuanlan.zhihu.com/p/37012044

VS CODE 推荐插件

Element UI Snippets
HTML CSS Support
JavaScript (ES6) code snippets
Vue VSCode Snippets
Chinese (Simplified) (简体中文) Language Pack for Visual Studio Code:中文包
Comment tagged templates:js文件中template模板高亮显示,使用方式参考文档
Comment Translate:悬浮/选中中文翻译
CSS Peek:Ctrl + F class标签跳转相应css
Auto Rename Tag:自动重命名标签
Guides:缩进线
koroFileHeader:自动生成文件头部注释(Ctrl + Alt +i),一键生成函数注释(Ctrl + Alt + t)
Live Sass Compiler:sass/scss编译成css文件
Prettier - Code formatter:代码格式化插件
px to rem & rpx & vw (cssrem):px单位转换为rem插件
Rainbow Brackets:彩虹括号
TODO Highlight:注释高亮,详情见1.3.1特殊标记
vscode-icons:好看的文件图标
Vue Language Features (Volar):vue3

webstorm推荐插件

待补充

学习|社区|博客

掘金
Echarts社区 https://www.makeapie.cn/echarts
github/gitee
阮一峰公众号
张鑫旭(css)
Anthony Fu (vue3/vite/开源)
coderwhy公众号

菜狗小仪

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
前端项目规范

自定义事件应始终使用中横线(kebab-case)的事件名。不同于组件和 prop，事件名不存在任何自动化的大小写转换。而是触发的事件名需要完全匹配监听这个事件所用的名称。this . $emit('my-event') 复制代码 < MyComponent @my - event = "handleDoSomething" / > 复制代码。
复制链接

扫一扫