common-ui/开发规范.md

前端开发规范

[TOC]

规范目的

• 规范代码一致性，提升团队代码整体质量；
• 便于工程维护有据可循，让新手快速融入开发团队；

规范说明

• 规范前未说明，为强制规范，须严格遵守，若有场景规范不适用的，请在非规范旁注解说明并反馈;
• 规范前标记推荐的，为推荐规范；

规范内容

命名规范

命名原则

• 命名使用英文单词，难以翻译的中文名称可使用中文拼音首字母拼接命名，如‘派单综资’，命名为'pdzz'
• 命名的单词数量最多为4个
• 较长单词可考虑使用缩写
• 命名体现本身作用、意义，及区分作用
  • 不使用无意义命名，或数字：1.png, 2.png等
  • [推荐]避免使用广义名称单词：如name, content，可更换为user-name, tab-content

命名法

• 小写中划线分隔命名：单词小写，多个单词以中划线分隔，如：user.js, user-add.js
• 以下列表使用上面命名方式
  • 文件目录
  • 样式类文件（css、scss、less等）
  • 普通js文件
  • 图片文件
  • html文件
  • css中class
  • css函数定义
  • 路由路径
• 大陀峰命名：所有单词首字母大写，多个单词直接拼接，如：Login.vue， AccountRegister.Vue
• 以下列表使用上面方式
  • Vue文件
  • js类定义文件
  • 路由名称
• 小陀峰命名：首单词小写，其它单词首字母大写拼接,如：userName, myAge
• 以下列表使用上面方式
  • js方法
  • 普通变量
• 常量命名：单词大写，多个单词以下划线分隔，如：USER_NAME， AGE
• 以下列表使用上面方式
  • 常量

命名修饰

• 内部使用修饰：以下划线'_'开头修饰命名，如_components定义模块为当前目录使用组件，非对外
  • 用此修复法修饰非对外暴露目录、文件、方法、属性等

目录规范

工程结构

public                               入口页面和非打包静态资源目录
src                                  源码目录
|-- api                              接口目录
|   | -- common                      接口服务公共业务封装
|   | -- xx-xx-api.js                模块接口服务定义
|   | -- index.js                    接口服务统一入口，所有接口服务模块通过此文件暴露
|-- i18n                             (可选)国际化资源
|-- assets                           打包静态资源
|   |-- images                       图标
|   |-- styles                       样式定义目录
|   |   |-- common.xxx               项目公用样式
|   |   |-- index.xxx                样式入口文件
|   |   |-- reset.xxx                样式重置
|   |   |-- mixin.xxx                样式函数定义
|   |   |-- variable.xxx             样式变量定义       
|   |   |-- ipu.scss                 通用样式（跨项目通用）  
|   |-- fonts                        字体文件
|-- components                       (可选)项目公用组件
|-- filters                          (可选)过滤器
|-- mock                             (可选) 模拟接口，不打入生产环境
|   |-- 接口调用模拟
|   |-- 插件调用模拟
|-- router                           路由定义
|-- store                            数据存储定义
|-- util                             项目公共方法、常量定义 
|-- |---constant                     项目常量定义
|   |-- common                       公共工具方法
|   |-- index.js                     通用模块暴露入口
|-- views                            视图目录
|   |-- accont                       视图模块名
|   |   |-- Login.vue                模块入口页面
|   |   |-- _components              模块通用组件文件夹
|   |   |-- index.js                 模块路由配置
|   |   |-- style                    模块内样式共用
|   |-- index.js                     项目路由配置

api

• api/index.js为所有接口服务模块统一入口
• common目录定义接口服务公共封装，如统一出错处理、请求时加载框效果等
• 接口服务模块划分与后端接口模块一致
• 接口服务文件命名以-api结尾，如user-manager-api.js
• 接口服务模块内接口请求路径统一定义在paths对象中
• paths中定义接口路径名称与接口方法名称一致

assets/images

• common 公共图片目录
• 其它子目录与views模块一致
• 移动端切图尺寸为实际展示尺寸2倍，比如展示区域为10px * 10px，使用切图尺寸为20px * 20px
• 根目录不直接放图片

assets/styles

• class命名说明
  • 项目公用样式以'common-'前缀
  • 通用样式以'ipu-'为class前缀
• variable.scss变量命名说明
  • [推荐]通用变量以css属性为前缀，如$color-primary, $color-warning
  • [推荐]组件或业务变量以组件或业务名称为前缀，如$button-color, $button-font-size
• 移动端0.5px边框问题
  • 不能直接使用0.5px定义边框，在部分设备上可能不显示，统一使用伪元素处理
  • 预定义上下左右边框class: ipu-fn-bd-t,i pu-fn-bd-b,ipu-fn-bd-l,ipu-fn-bd-r，边框颜色为变量\$borderline-color
  • 边框颜色与\$borderline-color定义不同时，可调用函数 @include borderline(边框位置，颜色值)生成边框样式代码

views

• 目录命名
  • 按模块功能命名，推荐使用单个名词，如account， dashbord等
• vue文件命名
  • 以大驼峰方式命名，如Login.vue, UserRegister.vue
  • 多个单词时，名词在前，动词在后方式命名，如UserRegister.vue
• 路由配置
  • 模块目录下有index.js文件，用来暴露此模块下页面路由配置信息
  • view/index.js汇总模块路由并暴露
  • 路由名称与文件名一致
• _components 模块下业务组件，非通用组件

其它

[推荐]Vue组件选项定义顺序

  - 自定义
  - components
  - setup
  - props
  - data
  - computed
  - watch
  - created
  - mounted
  - methods

数据状态定义枚举使用常量

• 对数据状态枚举值定义为常量，不在代码直接使用枚举值数字或字符，因为状态值0难以提现状态值的真正意义 export const subnumStatusValues = { NO_ACCOUNT: '1', // 小号还未开户成功 UNACTIVE: '2', // 小号还未激活，请先激活 UNBIND: '3', // 小号未绑定成功，请联系运营商 OK: '4', // 小号正常可使用状态 CANCEL: '5' // 此小号已销户 }

eslint

• 代码具体风格以项目eslint为准，编译时不规范的请求，请自行修改

git

• 勿使用git push -f，不要强制推送
• 会自己解决代码问题，不会的请自行练习（如码云上申请个人仓库练习）