# map_web

**Repository Path**: rjxyzdh/map_web

## Basic Information

- **Project Name**: map_web
- **Description**: 新建map_web项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-10-26
- **Last Updated**: 2024-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

| 修改日期 | 修改人 | 修改内容 | 版本 |
| --- | --- | --- | --- |
| 2021-11-28 | 李承辉 | 文档创建 | 1.0 | --- | --- | --- | --- |
| 2022-08-15 | 李承辉 | vue3补充 | 2.0 |
## 前言
此版本是继上个版本修改细化了需要注意的地方，删减了一些作为前端开发人员的基础要求。

但就目前的项目情况，规范起来工作量将会很大，暂时先慢慢维护、调整，要求新的开发任务请严格按照规范执行，后期有时间了可能会考虑某些产品化项目大范围重构。
* 规范执行过程中产生的问题以及有一些好的想法，可以讨论进行补充或修改。
* 开发过程有时会要面临技术选型，开发难点时，需要集中讨论给出方案，不可自行决定。
* 有业务涉及到框架底层代码逻辑，常规化组件修改的，汇总到具体框架、组件的设计开发人员处修改。

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

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

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

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

## 目录规范
目的是为了使用简便易懂，能快速找到对应文件，提高协作效率。
```
/pubilc（静态资源）
/src（开发相关目录）
    /api(接口相关)
    /assets(静态资源)
    /components(组件封装)
    /composables(组合式api)
    /layout(公共模块)
    /router(路由)
    /store(Vuex)
    /styles(样式)
    /utils(工具类)
    /types(ts类型推断)
    /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整体放大页面内容，能有很好的显示效果，但是由于浏览器的字体大小是有下限的，只能保证页面整体向上兼容，所以在设计开发之前就确定好兼容最低分辨率是多少，防止后期返工。

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

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

不要使用margin: 5%;width: 98%;height: 36%;这种样式写法，不能保证在各个分辨率下的展示正常。

## VUE3.x补充
经过一段时间的迭代完善，使用vue3.0 + vite + ts 在后端的协调下，开发出的一套包含基础后台功能的框架，而我们只需关注业务本身的代码进行开发。
与vue2的对比方面，从稳定运行，代码逻辑，依赖下载，打包体积各等各方面均得到了很大提升。

##### 关于Ts
可以理解为js升级版，需要编译成js才能在浏览器运行。
1.丰富的类型定义，大部分的函数看看类型声明就知道如何使用。
2.编译期间代码检查，部分错误在开发阶段就能捕获，增加稳定性
3.VsCode天生就能很好支持，代码补全、接口提示、跳转定义等
4.类型自动推断

前期需要定义类型，短期看来增加了代码量，但对于需要团队协作长期维护的项目，可以降低很大维护成本，不熟悉业务逻辑也能很好的上手开发。

对于快速迭代的项目，前期暂时可以忽略少的类型定义，后期有时间补全，形成习惯。

##### VsCode插件
1.volar （vue3 + ts 语法支持，需要禁用vue2的vuter）
2.eslint（项目内置eslint配置，不按格式书写运行报错，最后目的是培养开发习惯）

##### 核心依赖
- 框架Vue3.x
- 构建工具Vite
- css扩展Sass
- UI组件Element-plus
- 类型检查TypeScript
- 格式检查EsLint
- 路由VueRouter@next
- 状态管理Vuex@next

##### 内置组件
    组件做了自动引入配置、按照命名规范创建，无需引入在vue就可使用，参数可以在组件内声明里看到注释
- 动态生成无限级路由（后台配置）
- 权限控制，精确到按钮（后台配置）
- 行政区划、组织机构、数据字典状态缓存（后台配置）
- 动态配置主题色（黑、白）
- 内置多套导航布局，动态配置
- 符合现代化后台表格页功能的表格组件（高度集成、CURD）
- 弹框组件，统一样式
- 上传文件组件，支持多文件类型
- Tinymce富文本编辑器
- svg图标集合
- 本地播放器插件集成
- 二、三维地图组件