IIDP前端开发规范

Image not found

前言

希望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、全局变量，全局方法名称使用应用名称+功能名称

正例:

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 + 名称（可选）+ 动词

正例：

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

反例：

<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重新安装指定版本正例：

// 固定(指定)的版本号
{
  "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",
  }
}

反例：

// 不固定的版本号，（不推荐）
{
  "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

工程结构规范

工程结构说明

|— apps
  |— base                            // 业务App 根据实际情况命名
    |— common                        // 公共总扩展，一般情况不用操作，后面会展开讲解
      |— common - 公共总扩展
      |— assetImport.js - 内部导入连接资源扩展入口
      |— asset.json - 外部url连接资源扩展入口
      |— common.js - 应用公共配置扩展入口
      |— comps.js - 定制组件扩展入口
      |— extendView.js - 合并视图扩展入口
      |— hook.js - 功能钩子扩展入口
      |— schema.js - 初始视图结构扩展入口
      |— index.js - 公共扩展总入口
    |— views                         // 纯js格式编辑视图，通过视图的扩展能力合并的主视图中
      |— rbacUser                    // 业务定制的扩展视图，名称根据实际情况定义
        |— tview__base__rbac_user.js // 扩展文件，后面会展开讲解 命名规则：[自定义业务名].js
      |— ...
      |— index.js                    // 扩展视图的入口
    |— config                        // 当前App的额外配置，如全局变量
      |— app.json
    |— resource                      // 语言包，皮肤 等资源
    |— static-resource               // 静态资源
    |— index.js                      // 扩展引入入口
  |— component                       // 公共业务组件
|— config
  |— nginx
  |— apps.json
|— build                            // 各种环境的打包入口

工程运行起来后，以下文件夹是工程临时生成文件不用处理： resource、static-resouorce、views、dist、distApp、distTmp

资源引入规范

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、涉及代理转发的不需要设置跨域

web-front-standard