# vite_admin

**Repository Path**: cxs1992/vite_admin

## Basic Information

- **Project Name**: vite_admin
- **Description**: vite + vue3 + typescript + element-plus
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2022-03-11
- **Last Updated**: 2022-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 前端开发规范文档
## 修订记录

| 修改日期 | 修改人 | 修改内容 | 版本 |
| --- | --- | --- | --- |
| 2021-11-28 | 李承辉 | 文档创建 | 1.0 |
## 前言
制作本文档的初衷是目前公司前端团队处于混乱状态，都在负责的项目中跟进维护，根据项目需求，各自使用各自的开发风格，开发新项目时也有直接拿其他的项目的代码，不管是否有多余的功能未做清除，都是自行决定，甚至还有改动底层框架满足需求，重复创建组件，这边用TableModule、那边又用TableModule1，为了完成功能，代码只有自己才能看懂，越写越乱。
此版本是继上个版本修改细化了需要注意的地方，删减了一些作为前端开发人员的基础要求。
但就目前的项目情况，规范起来工作量将会很大，暂时先慢慢维护、调整，要求新的开发任务请严格按照规范执行，后期有时间了可能会考虑某些产品化项目大范围重构。
* 规范执行过程中产生的问题以及有一些好的想法，可以讨论进行补充或修改。
* 开发过程有时会要面临技术选型，开发难点时，也需要集中讨论给出方案，不可自行决定。
* 有业务涉及到框架底层代码逻辑，常规化组件修改的，汇总到具体框架、组件的设计开发人员处修改。

## 使用框架
大多项目框架均使用Webpack + Vue2.x版本构建，前后端分离形式开发，原有项目无法进行版本升级或工作量巨大的可以考虑重构，有多个项目尽量用一套代码控制，方便管理，除非差异化巨大可以进行分支。

经过Vue3的版本更新，加上新推出的Vite新一代的构建工具，是下一代前端开发框架，预计将在新项目中使用。
目前正在研究开发基建，基于Vue3 + Vite + TypeScript，敬请期待。
**这里要求相关开发人员提前去熟悉一下相关知识**
* Vue3 Setup 组合式api写法，以及新特性；
* Vite 打包构建，配置相关知识；
* TypeScript 使用方法；
* 适应并了解Eslint代码格式检查；

**另原有的少数JSP项目，并不适用此文档，如需维护仅以功能实现为主。**

## 开发工具
> 建议统一使用Vscode，功能健全，辅助开发功能强大，社区丰富，是当下前端大环境下的主流开发工具。
> 配合相关插件能极大提高开发效率，开发配置也能随时共享。

## 目录规范
目的是为了使用简便易懂，能快速找到对应文件，提高协作效率。
```
/pubilc（静态资源）
/src（开发相关目录）
    /api(接口相关)
    /assets(静态资源)
    /components(组件封装)
    /composables(组合式api，vue3相关，vue2忽略)
    /layout(公共模块)
    /router(路由)
    /store(Vuex)
    /style(样式)
    /utils(工具类)
    /vendor(导出excle)
    /types(ts类型推断)
    /iconfonts(svg图标)
    /views(路由)
    main.js(入口文件)
```
## 引入资源
以下列出都是项目中频繁使用的资源库推荐（除框架默认加载库），其他功能根据项目情况选择开源组件或自行开发，避免重复造轮子。

**需要注意的是**
* 既使用MVVM方式开发，就应遵守相关规范避免使用其他方式进行开发，例如JQuery；
* 安装组件库视情况使用按需加载的方式，避免全部引入，实际仅使用了其中的某项功能；
* 推荐优先选择，并尽可能的熟悉组件使用方法，降低使用成本；
```
    axios(接口)
    echarts(图表)
    element-ui(ui框架)
    element-plus(vue3版本)
    js-md5(md5转换)
    moment(日期格式转换)
    swiper(轮播滚动组件)
    viewerjs(图片控制)
    animejs（动画）
    node-sass(scss解析)
    sass-loader(scss文件处理loader)
    sass(vite使用)
    nprogress(加载进度条)
```
## 组件
> 开发组件的目的是为了简化代码层级，抽象业务功能以及重复使用的，只有当满足某些具体条件时可以使用组件。

### 组件定义
* 同样功能出现次数大于等于2次；
* 页面功能复杂，代码量过大，不易维护；
* 页面功能需要进行拆分重组的；

### 组件命名
* 至少2个单词以上命名，以单词大写开头，采用驼峰式命名规则。一般是多个单词全拼，减少简写的情况，例如：HomeSearch。
* 组件都放到/components文件夹下，单个页面独立一个文件夹，用来放相对应的vue文件以及页面相关的文件，样式少可直接写到页面组件里边，更符合组件化的思想。
* 在具体页面目录中进行单独拆分，为了方便识别组件归属，名称以组件名开头。
例如：首页需要拆分组件，同级目录下新建/components，名称以Home开头，H大写表示组件。
```
 /views
    /home
        /components
            HomeLeft.vue
            HomeRight.vue
        home.vue
```
## 注释
> 每一个代码块，函数体，功能点必须加上注释，函数参数的意义描述，props参数注释，注释格式为代码开头另起一行，也可以适当给html、css大块的功能点适当添加注释。

单行注释：//　快捷键： ctrl+/
多行注释：/**/ 快捷键： ctrl+shift+/

``` javascript
    // 搜索功能
    /*
        搜索功能
        form: object - 表单
    */
    function search(form) {...}
    const form = {
        name: '', // 姓名
        mobile: '' // 手机号
    }
    porps: {
        // 是否显示
        visible: {
            type: Boolean,
            default: false
        }   
    }
```

## 代码规范
> 要求代码开发简单明了，逻辑合理，功能完成后应自查代码，保证在不影响功能的前提下尽可能的进行压缩、简化。
> 这样，既提升了自己的编码水平，也会提高团队整体开发效率。

* 变量、函数体使用首字母小写驼峰命名法，例如：searchForm、openUrl()；
* 常量全大写，例如：APIHOST；
* 类命名首字母大写，例如：class MyVue{}；
* 命名语义化，尽可能利用英文单词或其缩写；
* 代码结构明了，提高函数重用率；
* 防止过度依赖UI组件，差异化较大的需求尽量使用常规代码实现；
* 如非必要不允许写过多的行内样式；
* css命名规则
```
// class类命名以横线连接
.head-logo { ... } /*页面头部logo的类名*/
.nav-li { ... } /*导航条上list的类名*/
.link-panel_h2 { ... } /*链接模块的标题*/

// 尽量语义化，例如：内容左边标题
.content-left_title { ... }
// 单词过长使用缩写
.c-left_title { ... }

// id 命名采用驼峰
#panelContent { ... }

// 可以将一些常用的类单独提取出来，例如字体大小，颜色等，按照规则声明方便使用
.red { ... }
.f20 { font-size: 20px; }
.t-left { text-align: left; }

```
* 代码风格统一引入eslint，使用 [standard](https://fungleo.blog.csdn.net/article/details/77934448) 风格约束代码格式，具体细则可以参考官方文档说明；

**eslint初始化配置参考**
```
// 安装eslint
npm install eslint -D

// 初始化eslint
npx eslint --init
// 选择检验规范，选第三项，强制代码风格
? How would you like to use ESLint? … 
? How would you like to use ESLint? … 
  To check syntax only
  To check syntax and find problems
❯ To check syntax, find problems, and enforce code style

// 模块化规范，选第一项
? What type of modules does your project use? … 
❯ JavaScript modules (import/export)
  CommonJS (require/exports)
  None of these

// 前端框架，选第二项
? Which framework does your project use? … 
  React
❯ Vue.js
  None of these
 
// 是否使用Ts，根据项目情况选择
? Does your project use TypeScript? › No / Yes

// 代码运行环境，选第一个，浏览器环境
? Where does your code run? …  (Press <space> to select, <a> to toggle all, <i> to invert selection)
✔ Browser
✔ Node

// 代码风格，选第一个，使用当下主流格式规范
? How would you like to define a style for your project? … 
❯ Use a popular style guide
  Answer questions about your style
  Inspect your JavaScript file(s)

// 代码规范，选第二个 Standard
? Which style guide do you want to follow? … 
  Airbnb: https://github.com/airbnb/javascript
❯ Standard: https://github.com/standard/standard
  Google: https://github.com/google/eslint-config-google
  XO: https://github.com/xojs/eslint-config-xo

// 代码配置文件格式，选第一个
? What format do you want your config file to be in? … 
❯ JavaScript
  YAML
  JSON
  
// 最后就是是否自动安装依赖包，选则yes即可
Checking peerDependencies of eslint-config-standard@latest
The config that you've selected requires the following dependencies:

eslint-plugin-vue@latest eslint-config-standard@latest eslint@^7.12.1 eslint-plugin-import@^2.22.1 eslint-plugin-node@^11.1.0 eslint-plugin-promise@^4.2.1 || ^5.0.0
? Would you like to install them now with npm? › No / Yes
```
## 兼容性
随着网络的快速发展，各种集成的开发框架数不胜数，只需要稍加改动、配置从各个方面就能解决很多问题，浏览器的兼容问题也在逐渐变小，使得大部分项目基本使用主流Chrome浏览器开发测试即可，除个别需要兼容某些特定浏览器除外。

既然代码兼容性问题不需要考虑，就需要把关注点集中在显示分辨率的自适应，以及如何更快速的加载页面，更流畅的进行交互，更简易的后期维护，这也是出这套规范的原因。

关于分辨率自适应的问题，目前用的最多的是以rem + 弹性布局 + 百分比的方式，通过控制顶层rem整体放大页面内容，能有很好的显示效果，但是由于浏览器的字体大小是有下限的，只能保证页面整体向上兼容，所以在设计开发之前就确定好兼容最低分辨率是多少，防止后期返工。

开发页面前，想好布局方式，给外层整体设定宽高，内层弹性布局，内边距，外边距统一处理。

开发过程中使用到的图片资源，能以代码完成的就不要使用图片，原则是尽可能少的使用图片，图片中包含文字的，使用背景图的方式，文字用代码叠加上去，避免文字出现变形，影响整体效果。

## 绩效考核
开发一个页面可能只需要花10分钟，也可能花100分钟，同一个功能可能只需要写10行代码，也能写100行，考虑越全面，越费时间，但是能达到的效果显而易见，这体现了开发者对待工作的态度，以及自身开发能力。

为了规范开发原则，自发布生效后进行的开发，修改将全部按照规范执行，不定期随机抽查开发者代码。
设定考核如下：

1. 代码格式规范
考核内容： 代码的简洁和规范程度，功能点实现方式是否合理，项目稳定运行；

| 分值 | 评分标准 |
| --- | --- |
| 40-50 | 代码逻辑思路清晰，格式规范，一目了然或仅存在小部分不合理部分 |
| 30-40 | 部分代码不符合规范要求，但不影响项目运行 |
| 15-30 | 大部分代码不符合规范，运行不稳定有隐患 |
| 0-15 | 存在严重逻辑问题，基本不符合标准 |

2. 兼容性（自适应）
考核内容：设计资源还原度，以及是否能在基础分辨率向上兼容，样式定义规范。


| 分值 | 评分标准 |
| --- | --- |
| 40-50 | 设计还原度95%以上，常用分辨率下显示正常，样式灵活可控复用率高 |
| 30-40 | 设计还原度80%以上，样式设定较为混乱 |
| 15-30 | 设计还原度低于80%，分辨率改动后样式错乱，出现换行等，滥用图片资源 |
| 0-15 | 设计还原度低于80%，大范围行内样式，很难进行维护扩展 |

分值参考

| 分值 | 结果 |
| --- | --- |
| 90 - 100 | 优秀 |
| 80 - 90 | 合格 |
| 60 - 80 | 有待改进 |
| 0 - 60 | 不合格 |