web-front-standard

default

markdown

# IIDP前端开发规范

[[http://192.168.175.198:10003/iidpminio/home/logo.png]]

# 前言

希望IIDP开发者通过阅读本手册，能够充分利用IIDP平台进行开发，避免常见的错误和陷阱，写出高质量的代码，提高开发效率。让我们一起码出高效、码出质量的软件系统。

# 开发规范

## 命名规范

### 项目文件命名

1、项目文件名

【推荐】命名方法：kebab-case 字母小写短横线连接

正例：whclould-smart-port / my-project-name

反例：My-Project

2、目录名

【推荐】有复数结构时，要采用复数命名法

正例：assets、components、directives、mixins、utils、views

### 组件命名

1.【强制】 组件命名规范，组件名称必须唯一

说明：在IIDP平台中，确保组件名称的唯一性，便于识别和管理。 tech-作为名称前缀，具体的组件名作为后缀名称。

正例：tech-button / tech-dialog / tech-upload / tech-custom-multi-input 使用时type：button

反例：custom-multi-input 没有tech-作为名称前缀，会导致使用时type：custom-multi-input不显示这个组件

2、单文件组件名

【推荐】单文件组件名应该始终是单词大写开头 (PascalCase)，大驼峰式命名法。

正例：CustomComponent.vue

反例：my-Component.vue

3、基础组件名

【推荐】基础组件在一个页面内可使用多次，在不同页面内也可复用，是高可复用组件。应该全部以一个特定的前缀开头 —— Base

正例：BaseButton.vue/ BaseInput.vue

反例：myButton.vue

4、业务组件

【推荐】掺杂了复杂业务的组件（拥有自身 data、prop 的相关处理）即业务组件应该以 Custom 前缀命名。

正例：CustomCard.vue

反例：myCard.vue

5、组件名中单词顺序

【推荐】组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾。组件名尽量以完整单词命名，单词尽量语义化，方便阅读。

正例：SearchContent.vue

反例：ContSech.vue

### 代码参数命名
1、【推荐】在声明 prop 的时候，其命名应该始终使用 camelCase(小驼峰式命名)，而在模板和 JSX 中应该始终使用 kebab-case(短横线连接式)。我们单纯的遵循每个语言的约定，在 JavaScript 中更自然的是 camelCase。而在 HTML 中则是 kebab-case

正例：camelCase

反例：camel-Case

2、router属性

【推荐】Vue Router Path 命名采用 kebab-case (短横线连接式)格式。或者PascalCase(大驼峰命名)，推荐使用kebab-case 短横线。 用 Snake(下划线连接式)（如：/user_info）或 camelCase(小驼峰命名)（如：/userInfo)的单词会被当成一个单词，搜索引擎无法区分语义

3、模板中组件

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

4、全局变量，全局方法名称使用应用名称+功能名称

正例:
```js 
  const IOT_THEME_OPTIONS = ['blue', 'red', 'green']

function iotGetSearchParams(params){
    console.log(params)
  }
```

反例： const MY_TE = ['blue', 'red', 'green']

5、变量

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

正例：camelCase

6、常量

命名规范：使用大写字母和下划线来组合命名，下划线用以分割单词，力求语义表达完整清楚

正例：const MAX_COUNT = 10 //全部大写下划线分割

反例： const MC = 10

7、方法

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

正例：jumpPage、loginIn、openDialog、getListApi、refresh

反例：pageGet

8、事件方法

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

正例：
```js
<el-pagination
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
    :current-page.sync="currentPage"
    :page-size="100"
    layout="total, prev, pager, next"
    :total="1000">
</el-pagination>
```

反例：
```js
<el-pagination
    @size-change="change"
    @current-change="currentChange"
    :current-page.sync="currentPage1"
    :page-size="100"
    layout="total, prev, pager, next"
    :total="1000">
</el-pagination>
```
## 代码规范
【强制】为 v-for 设置键值，在组件上必须用 key 搭配 v-for，以便维护内部组件及其子树的状态。

【强制】v-if 和 v-for 互斥，永远不要把 v-if 和 v-for 同时用在同一个元素上。

【强制】多个 attribute 的元素应该分多行撰写，每个 attribute 一行。视情况而定

【强制】模板中简单的表达式，组件模板应该只包含简单的表达式，复杂的表达式则应该重构为计算属性或方法。

复杂表达式会让你的模板变得不那么声明式。我们应该尽量描述应该出现的是什么，而非如何计算那个值。而且计算属性和方法使得代码可以重用。

【强制】指令缩写

用 : 表示 v-bind:

用 @ 表示 v-on:

用 # 表示 v-slot

【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

【推荐】条件判断能使用三目运算符和逻辑运算符解决的，就不要使用条件判断，但不要写太长的三目运算符。如果超过 3 层请抽成函数，并写清楚注释。

【推荐】慎用 console.log，因 console.log 大量使用会有性能问题，调试完最终提交前清除掉

## 注释规范
注释的原则：提高代码的可读性，从而提高代码的可维护性
如无必要，勿增注释 ( As short as possible )
如有必要，尽量详尽 ( As long as necessary )

1、HTML 文件注释

【推荐】单行注释:一般用于简单的描述，如某些状态描述、属性描述等。注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。

2、模块注释

【推荐】一般用于描述模块的名称以及模块开始与结束的位置。 注释内容前后各一个空格字符

## 扩展规范

1、主题扩展

【强制】对页面顶部，侧边栏，菜单等公共模块的扩展

需独立新增app内扩展，可以单独自行安装卸载，以免影响全局

2.【推荐】扩展名称使用应用名称+菜单名+功能名称

正例：iot_iiot_program_menu_search_extend

反例：unit_test_extend_view 不明确生效的位置和功能

3、样式扩展

【强制】对框架使用的Element的样式修改时，使用局部作用域，以免影响全局样式

4、关于扩展选择的节点id

【强制】在选择扩展的节点id时，对于id中包含undefined的节点不能直接扩展，请咨询平台人员

5、关于扩展注释

【推荐】在对某节点扩展时，补充注释信息，说明页面节点，功能描述等信息，方便阅读、定位

# 版本管理规范

## 关于版本更新
为了确保线上使用的依赖版本与开发时的版本一致，有以下几项注意事项：

1、执行npm run update:tech、npm run update:beta、npm update等命令升级后依赖版本中会带有 ^ 等符号，如果需要使用固定版本，需要手动修删除 ^ 符号，使用固定的具体的版本号，并执行npm run init:tech重新安装指定版本
正例：

```json
// 固定(指定)的版本号
{
  "dependencies": {
    "@tech/t-base": "1.0.11",
    "@tech/t-build": "1.0.1",
    "@tech/t-core": "1.0.9",
    "@tech/t-el-ui": "1.0.9",
  }
}
```
反例：

```json
// 不固定的版本号，（不推荐）
{
  "dependencies": {
    "@tech/t-base": "^1.0.11",
    "@tech/t-build": "^1.0.1",
    "@tech/t-core": "^1.0.9",
    "@tech/t-el-ui": "^1.0.9",
  }
}
```

2、为了保证打包稳定，请直接使用当前开发环境所安装的依赖，不需要执行 npm run update:tech 或者 npm run update:beta

# 工程结构规范

## 资源引入规范
1、资源引入

【强制】前端依赖的第三方库，或组件库的资源地址引入需要做以下配置：

外部资源需要在./apps/[自己的扩展应用]/common/assets.json配置引入

内部资源需要在./apps/[自己的扩展应用]/common/assetsImport.js配置引入

2、资源扩展

asset.json资源引入扩展，会根据定义里面的 title 作为唯一标识覆盖合并

assetImport.js资源引入扩展，会根据定义里面的 key 值作为唯一标识覆盖合并， 例如上面的 assetImport.js 引入组件库的key值为 my-ui。

# 部署规范

1、底座的更新只能通过更新服务器中前端工程。

2、app 的更新可通过应用市场更新，可也以通过服务器部署更新

3、打包外部依赖 app 和本地开发的 app 到./dist/umdComps中。适用于通过应用市场上传安装

【强制】主服务器的 nginx 需要增加允许跨域

1、所有的涉及静态资源转发的都需要配置允许跨域

2、涉及代理转发的不需要设置跨域

Uploading file...

Edit message:

Cancel

Editing web-front-standard

Sidebar