Roland.E
HomeTimelineTags

Roshi-ERP 前端编程规约——基本规范

1 文件及文件夹

[强制] 一切命名严禁使用拼音，使用统一的英文单词或缩写命名

1.1 项目目录

xml
my-project-name/
|- node_modules   // 下载的依赖包
|- public         // 静态页面目录
    |- index.html // 项目入口
|- src            // 源码目录
    |- api        // http 请求目录
    |- styles        // 全局样式目录
        |- global.scss  // 公共样式
        |- reset.scss   // 重置第三方UI库样式
    |- assets     // 静态资源目录，这里的资源会被wabpack构建
        |- icon   // icon 存放目录
        |- img    // 图片存放目录
    |- components     // 组件
    |- enums         // 枚举
    |- filters        // 过滤器（仅Vue2）
    |- directives     // Vue全局指令
    |- layout         // 最外层布局（可选）
    |- router         // 路由
    |- store          // 全局状态管理
    |- utils          // 工具存放目录
        |- request.js // 公共请求工具
        |- index.js   // 公共方法
    |- views          // 页面存放目录
    |- App.vue        // 根组件
    |- main.js        // 入口文件
|- .eslintignore  // eslint 忽略规则
|- .eslintrc.js   // eslint 规则
|- .gitignore     // git 忽略规则
|- package-lock.json
|- package.json // 依赖
|- README.md // 项目 README
|- vue.config.js // webpack 配置
|- vite.config.js // vite 配置

[推荐] views目录全部采用kebab-case命名 (除node_modules)， 以中划线分隔，有复数结构时，要采用复数命名法，缩写不用复数

例：layouts, demo-styles

[推荐] components下的组件使用UpperCamelCase命名

例：Layouts, FileDownloader, BaseButton, BaseSelect

[推荐] emuns下的枚举文件使用lowerCamelCase方式命名，文件名附带Enum后缀

例：commonEnum, userEnum

1.2 JS, TS, CSS, HTML, PNG 文件命名

[推荐] 全部使用kebab-case命名法

例： render-dom.js / sign-up.css / index.html / company-logo.png

2 DOM结构

2.1 标签

[推荐] 优先使用HTML5语义化标签，避免整页div的情况出现

例：

语义化标签—布局规范.jpg

html
<template>
  <header id="header">
      <!-- 头部 -->
  </header>
  <nav>
      <!-- 菜单栏 -->
  </nav>
  <main>
      <!-- 主体 -->
    <article>
        <!-- 主要部分 -->
      <article>
          <!-- 子模块 -->
      </article>
      <article></article>
    </article>
    <aside>
          <!-- 次要部分 -->
    </aside>
  </main>
  <footer id="footer">
      <!-- 底部 -->
  </footer>
</template>

​

2.2 组件

[强制] template中组件使用UpperCamelCase方式调用，同时尽可能使用单标签

例：<RsSearch />, <BaseButton />

Bad：

javascript
<base-button />
<BaseButton></BaseButton>

Good:

<BaseButton />

3 CSS

  1. [强制] 类名使用kebab-case方式命名，ID使用lowerCamelCase方式命名

  2. [推荐] scss中的变量，函数使用lowerCamelCase方式命名

  3. [推荐] ID 和 class 的名称总是使用可以反映元素目的和用途的名称，或其他通用的名称，禁止使用晦涩难懂的名称

  4. [强制] 禁止使用静态的行内样式

  5. css语句的顺序需要注意，最先表达元素的位置，如position、top、transform:translate，其次依次为从外到内的盒模型边距：margin、border、padding，之后表达元素的尺寸，如width、max-width，其他样式放在最后

    css
    .article-wrap {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  margin: 0;
  border: 1px solid #ccc;
  padding: 20px;
  width: 50vw;
  height: 300px;
  min-width: 450px;
  display: block;
  background-color: #f2f6fc;
  font-size: 16px;
  color: #333;
  border-radius: 5px;
  box-sizing: border-box;
  opacty: .8;
}

  6. [推荐] 在css权重不足时，尽可能扩宽选择器的长度，非必要情况避免使用important规则。

    css
    // 权重不足
#header .nav-item {
  height: 100px;
}

// ✓ GOOD
#header >.navbar >.nav-item {
  height: 100px;
}

// ✗ BAD
#header .nav-item {
  height: 100px !important;
}

4 JS

4.1 变量

使用lowerCamelCase方式命名，不能以下划线或美元符号开始或结束

命名规范为类型 + 描述或属性

4.2 方法

使用lowerCamelCase方式命名

命名规范为动词或者动词 + 名词

例：getData(), editResume(), submitForm()

4.3 常量

[推荐] 常量名以SNAKE_CASE方式命名，表达尽可能清晰完整，名字长度无所谓

例：RONGYUN_IM_DEV_APPKEY

[推荐] 枚举类使用UpperCamelCase方式命名，其成员以SNAKE_CASE方式命名

javascript
export enum GenderEnum {
  MALE = 1, // 男
  FEMALE, // 女
}

4.4 this

[推荐] 对this的转换命名优先使用_this

例：let _this = this

5 Vue相关

5.1 组件命名及传参

5.1.1 组件命名

  • 组件name尽量使用多个单词组成，避免与HTML元素冲突，且使用UpperCamelCase方式命名 例：name: 'ImageUpload'

  • 基础组件文件名以base开头 例：BaseButton.vue, BaseTabs.vue

  • 只拥有单个活动实例的组件，应以The开头 例：TheHeader.vue

  • 和父组件紧密耦合的子组件应该以父组件名作为前缀命名 例：BaseSearch.vue, BaseSearchOption.vue

5.1.2 组件名中单词顺序

组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾

xml
components/
|- BaseSelect.vue
|- BaseSelectInput.vue
|- BaseSelectOption.vue
|- SearchButton.vue
|- SearchButtonRun.vue

5.1.3 组件的属性与事件

属性在定义时使用lowerCamelCase，但在template中调用时使用kebab-case

事件的定义与调用始终使用kebab-case

javascript
// 子组件
props: {
    collapseTags: {
        type: String,
        required: true,
        validator: function (value) {
            return ['syncing', 'synced',].indexOf(value) !== -1
        }
    }
},
emits: ['node-click']
html
<!-- 父组件 -->
<BaseSelect :collapse-tags="true" @node-click="handleNodeClick" />

5.1.4 组件name命名

组件的name选项以UpperCamelCase方式命名，且尽可能使用复数单词，对组件的用途进行尽可能详细的概括

javascript
export default {
    name: 'UserList'
}

5.1.5 组件引用

引用组件时，使用UpperCamelCase

javascript
import TheSideMenu from '@/components/layout/TheSideMenu';

export default {
    components: {
        TheSideMenu
    }
}

5.1.6 其他

在项目相对较大、组件过多的情况下，可以考虑将同一功能类型的组件放入同一个文件夹中

例：

xml
components/
|- BaseSelect
    |- BaseSelect.vue
    |- BaseSelectInput.vue
    |- BaseSelectOption.vue
|- Search
    |- SearchButton.vue
    |- SearchButtonRun.vue

5.2 路由

路由的path使用kebab-case命名，name即组件的name

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