hz/ebiz-sunful-eco-h5-weixin

Fork 0

Files

陈昱达 b440f8a3ef 微信项目

2025-07-01 10:00:31 +08:00

50 KiB

Raw Permalink Blame History

一、文件命名规范

1.1 文件夹以及文件命名

规则：用简短有意义的英文（不能出现中文命名）来命名。

1、文件夹名称全部小写。如需连接可使用中横线“-”连字符。

正例：

反例：

2、vue文件采用大驼峰形式。即第一个单词首字母大写，之后每个单词首字母大写。也可views —> 文件夹名称 —> Index.vue（文件夹可多级）

正例：

反例：

3、html、css、js文件命全部小写。如需连接可使用中横线“-”连字符。

正例：

反例：

4、图片命名规则：全部小写，如需要可用下划线“_”连字符。

正例：

反例：

1.2 vue文件内css的命名规则

规则：用简短有意义的英文来命名。如需连接可使用中横线“-”连字符。

1、规定html/vue的每一个容器都要加入对应的名字 ps（container一个页面只能有一个，如需所有的container有公共样式可如下图，如不需要可只保留对应的名字+container类名）

2、需加入scoped防止污染全局，如需覆盖框架样式加入::v-deep 即可。

1.3 vue文件内js的命名规则

1、常量命名有固定指意的全部大写，并用下划线分隔单词。无特定指意可采用小驼峰形式。

正例：

反例：

2、变量命名采用小驼峰且使用let。

正例：

反例：

3、Class、构造函数命名采用大驼峰。

正例：

反例：

4、函数命名采用小驼峰。

正例：

反例：

动词	含义	返回值
can	判断是否可执行某个动作	true---可执行，false---不可执行
has	判断是否含有某个值	true---含有此值，false---无此值
is	判断是否为某个值	true---是此值，false---不是此值
get	获取某个或某些值	-----
set	设置某个或某些值	-----

二、编码规范

2.1 sass 规范

2.1.1 Sass 目录规范

2.1.2 目录说明

1、common.scss

初始化样式、样式出口文件，要在入口文件App.vue引入。

2、vant-ui.scss

如果vant某些样式不是你需要的，在 vant-ui.scss 里可以重写来覆盖vant样式。

如果你只想重写当前组件的样式，可在直接在组件里重写，如设置了style的scoped属性导致修改样式无效，可以使用::v-deep ，方法如下：

3、mixin.scss

@mixin 指令允许我们定义一个可以在整个样式表中重复使用的样式。

@include 指令可以将混入（定义的@mixin，可理解为sass模块）引入到文档中，实例如下：

可向混入传递变量，实例如下：

常用内外边距及类名缩写列表

常用边距模块

配合循环语句和判断语句来匹配并引入。

CSS输出

4、transition.scss

如果你需要在多处使用同一个固定CSS3动画，统一写在 transition.scss，如：

5、utils.scss

工具样式文件，如果你需要在多处使用同一个固定样式时可以写在此文件中，如：

6、variables.scss

如需声明变量，统一写在 variables.scss，用 $ 加变量名声明，如：

2.1.3 全局CSS样式

1、浮动、清除浮动

.fl 左浮动
.fr 右浮动
.chearfix 清除浮动

2、字体样式

.fs12 字体尺寸 12px
.fs14 字体尺寸 14px
.fs16 字体尺寸 16px
.fs18 字体尺寸 18px
.fw600 字体粗细 600
.fwb 字体粗细 bold

3、布局定位

.relative 相对于其正常位置进行定位
.absolute 相对于 static 定位以外的第一个父元素进行定位
.fixed 相对于浏览器窗口定位
.mh-auto 块级元素水平居中
.hide 元素隐藏，但仍占用空间
.hidden 元素隐藏，不占用空间
.flex 弹性盒模型布局，块级元素
.inline-flex 弹性盒模型布局，内联块元素
.inline-b 内联块元素，表现为同行显示并可修改宽高内外边距等属性
.justify-content-c 弹性项目居中填充
.align-items-c 元素位于容器的中心。弹性盒子元素在该行的侧轴（纵轴）上居中放置

4、常用文字颜色

.c-gray-base 文字颜色 #999
.c-gray-dark 文字颜色 #666
.c-gray-darker 文字颜色 #333
.green 文字颜色 green
.red 文字颜色 red
.yellow 文字颜色 yellow
.gray 文字颜色 gray
.white 文字颜色白色

4、背景颜色

.bg-black 背景颜色黑色 black
.bg-white 背景颜色白色 white
.bg-none 背景颜色透明 transparent

5、文字位置设置

.text-left 左对齐
.text-right 右对齐
.text-center 居中对其
.text-underline 文字下划线

6、垂直方向对齐方式

.v-top 把元素的顶端与行中最高元素的顶端对齐 vertical-align: top
.v-middle 把此元素放置在父元素的中部 vertical-align: middle
.v-bottom 把元素的顶端与行中最低的元素的顶端对齐 vertical-align: bottom
.v-baseline 默认，元素放置在父元素的基线上 vertical-align: baseline

7、单行省略

.ellipsis 单行省略

可根据宽度自适应显示文字长度

8、宽度、高度、内外边距、圆角弧度、透明度

我们在 variables.scss 文件里声明了** 宽度、高度、内外边距、圆角弧度、透明度** 常用的一些数值，以及一些类名缩写

在 mixin.scss 文件定义了混入函数，通过传参的方式，根据类名缩写及数值来匹配相应的样式。

并在样式出口文件 common.scss中引入，这样全局都可使用这些类名缩写来使用这些样式。

文档如下：

宽度、高度

类名缩写：w，h

常用数值：40 50 60 70 80 86 100 110 120 140 150 155 160 180 192 200 220 260 280 315 325 350 400 440 445 450 550 700 1340

使用方法：类名 + 数值

例如：

宽度为100：

高度为100：

圆角弧度

类名缩写：radius

常用数值：1 2 3 4 5 6 7 8 9 10 12 15 18 20 50 100

使用方法：类名 + 数值

例如：

圆角弧度为10：

透明度

类名缩写：opacity

常用数值：0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

使用方法：类名 + 数值

例如：

透明度为0.9：

内外边距

类名缩写：m, mv, mh, mt, ml, mr, mb, p, pv, ph, pt, pl, pr, pb, top, left, right, bottom

m margin 外边距
mv margin-top margin-bottom 上下外边距
mh margin-left margin-right 左右外边距
mt margin-top 上外边距
ml margin-left 左外边距
mr margin-right 右外边距
mb margin-bottom 下外边距
p padding 内边距
pv padding-top padding-bottom 上下内边距
ph padding-left padding-right 左右内边距
pt padding-top 上内边距
pl padding-left 左内边距
pr padding-right 右内边距
pb padding-bottom 下内边距
top 定位属性 top
left 定位属性 left
right 定位属性 right
bottom 定位属性 bottom

常用数值：0 1 2 5 6 8 9 10 12 15 20 25 30 35 40 45 50 60 80 86 90 100

使用方法：类名 + 数值

例如：

左右外边距为30：

上下内边距为30：

定位属性top为30：

2.1.4 使用实例

代码为：

输出为：

代码为：

输出为：

2.2 vue 编码规范

2.2.1 vue 文件基本结构

组件顶级元素顺序按 <template>、<script>、<style> 的顺序放置。

2.2.2 template

在template里的最外层放置容器，类名为 组件名+container，例如：

2.2.3 script

各个属性、周期，需按照如下顺序放置name、components、props、data、周期函数、methods、computed、watch、filter，其他规范如下：

name：组件命名必填，和组件文件名保持一致，始终是 PascalCase，在DOM模板中应该是kebab-case

props：定义需指定其类型，命名应该始终使用 camelCase，而在模板和 JSX 中应该始终使用 kebab-case

**data：**变量注释规范在变量后单行注释说明

methods

建议使用扩展运算符拷贝对象

提交数据时不可直接使用页面渲染对象，推荐使用扩展运算符

**computed：**复杂计算应使用计算属性 computed。

理论上，computed 所有实现可以使用 methods 完全替换。computed 只有在与它相关或者需要的数据发生改变时才会重新求值。

调用computed的方法时不需要加**（）**。

watch：当需要在数据变化时执行异步或开销较大的操作时应使用侦听器 watch。

上图中初始 fullName是没有值的，watch默认不会执行，只有当侦听的数据发生改变时才会执行，通过声明 immediate 选项为 true，可以立即执行一次 handler。

不使用 deep 时，当我们改变 obj.a 的值时，watch不能监听到数据变化，默认情况下，handler 只监听属性引用的变化，也就是只监听了一层，但修改对象内部的属性是监听不到的。

通过使用 deep: true 进行深入观察，这时，我们监听 obj，会把 obj 下面的属性层层遍历，都加上监听事件，这样做，性能开销也会变大，只要修改 obj 中任意属性值，都会触发 handler。

2.2.4 style

声明语言 lang="scss" ，为了避免样式冲突，添加 **scoped **属性，并避免出现元素选择器。

以嵌套的方式在父容器类里写你需要的样式，因为我们声明了很多公用的全局CSS样式，所以组件里的样式尽量不超过20行。

如果你想重写当前组件vant的样式，可使用** ::v-deep ** 重写，示例如下

2.2.5 指令规范

指令有缩写一律采用缩写形式，如v-bind、v-on简写成 : 、@。

v-for 循环必须加上 key 属性，在整个 for 循环中 key 需要唯一避免 v-if 和 v-for 同时用在一个元素上（性能问题），可把 v-if 放在父容器上。

2.2.6 注释规范

代码注释在一个项目的后期维护中显的尤为重要，使用注释是良好的编程实践，它可以帮助他人理解代码的意图和功能，也方便自己在以后阅读代码时理解思路。

注释的内容主要包含这样三个方面：做什么、为什么、怎么做。对于一些复杂的组件和接口，我们可能还需要写明“如何用”。

文件和函数一定要写注释，而且要写得尽可能全面详细。函数内部的注释要相对少一些，一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码可读性。

**单行注释：**可以在语句之前和之后使用

alert('Hello, JavaScript'); // 输出Hello, JavaScript

**多行注释：**用于跨多行注释代码片段

/*
This is a multi-line comment.
It can span across multiple lines.
*/

.html/.js/.vue/.css文件注释

文件顶部必须包含文件注释，用 @name 标识文件说明。标识符冒号与内容之间必须保留一个空格。新增的情况

当该业务项目主要由固定的一个或多个人负责时，需要添加**@author**标识，一方面是尊重劳动成果，另一方面方便在需要时快速定位责任人。

/*
 * @name 文件名或模块名
 * @author 作者姓名
 * @created_date 创建时间 2018.07.05
 * @description 文件或模块描述
 */

修该的情况（追加）

/*
 * @modified by 修改者姓名
 * @modified_date 修该时间2018.07.05
 * @description 修该点
 */

常量：每个常量都需要添加说明注释

data: data 数据必须添加单行注释

data () {
    return {
      name: 'zhangsan', // 姓名
      age: 18, // 年龄
      sex: '男', // 性别
      address: '北京市' // 地址
    }
}

公共配置文件中的部分函数/方法/过滤器等（css 或者样式选填）

/*
 * @name 函数名
 * @author 作者姓名
 * @created_date 创建时间 2018.07.05
 * @description 函数功能和使用描述
 * @param {参数类型} 参数名称，如: date 字符串日期 “20200101”
 * @param {参数类型} 参数名称
 * @return 没有返回信息写 void / 有返回信息 {返回类型} 描述信息
 */

修该的情况（追加）

/*
 * @modified by 修改者姓名
 * @modified_date 修该时间2018.07.05
 * @description 修该点
 */

**函数：**每个 js 函数添加注释，js函数的关键逻辑（流程、判断、变量处理方式等)添加注释说明

/*
 * 函数名
 * @description 函数功能和使用描述
 * @param {参数类型} 参数名称，如: date 字符串日期 “20200101”
 * @param {参数类型} 参数名称
 * @return 没有返回信息写 void / 有返回信息 {返回类型} 描述信息
 */

// 判断 xxxx， 如果xxxx，则xxxx
if（xxxx) {

} else {

}

TODO 标记

如果某段代码有功能未实现，或者有待完善，必须添加 **TODO **标记，TODO 后应留一个空格。例如：

submit () {
  // TODO 今天偷懒了，明天补上
}

开发中不允许写死数据，如需测试数据，要添加 **TODO **标记备注，如：

userName: '小明' // TODO 测试数据，待修改

2.3 样式规范

2.3.1 数值与单位

当属性值或颜色参数为 0 - 1 之间的数时，省略小数点前的 0

~~color: rgba(255, 255, 255, 0.5)~~

color: rgba(255, 255, 255, .5);

当长度值为 0 时省略单位。

~~margin: 0px auto left: 0px;~~~~ ~~

margin: 0 auto; left: 0;

十六进制的颜色属性值使用小写和尽量简写。

~~color: #ffcc00~~

color: #fc0;

2.3.2 样式属性顺序

单个样式规则下的属性在书写时，应按功能进行分组，并以 Positioning Model > Box Model > Typographic > Visual 的顺序书写，提高代码的可读性。

如果包含 **content **属性，应放在最前面；
**Positioning Model **布局方式、位置，相关属性包括：position / top / right / bottom / left / z-index / display / float / ...
Box Model 盒模型，相关属性包括：width / height / padding / margin / border / overflow / ...
**Typographic **文本排版，相关属性包括：font / line-height / text-align / word-wrap / ...
Visual 视觉外观，相关属性包括：color / background / list-style / transform / animation / transition / ...

Positioning 处在第一位，因为他可以使一个元素脱离正常文本流，并且覆盖盒模型相关的样式。盒模型紧跟其后，因为他决定了一个组件的大小和位置。其他属性只在组件内部起作用或者不会对前面两种情况的结果产生影响，所以他们排在后面。

2.3.3 合理使用使用引号

在某些样式中，会出现一些含有空格的关键字或者中文关键字。

font-family 内使用引号

当字体名字中间有空格，中文名字体及 Unicode 字符编码表示的中文字体，为了保证兼容性，都建议在字体两端添加单引号：

background-image 的 url内使用引号

如果路径里面有空格，旧版 IE 是无法识别的，会导致路径失效，所以不管是否有空格，都加上单引号：

2.3.4 避免使用!important

!important 的存在会给后期维护以及多人协作带来噩梦般的影响。当存在样式覆盖层叠时，如果你发现新定义的一个样式无法覆盖一个旧的样式，只有加上 !important 才能生效时，是因为你新定义的选择器的优先级不够旧样式选择器的优先级高。所以，合理的书写新样式选择器，是完全可以规避一些看似需要使用 !important 的情况的。

2.3.5 避免使用行内样式

行内样式指的是将CSS代码直接写在标签的style属性中，这种写法虽然简单，但是可能会造成代码混乱，难以维护。

2.3.6 避免不同样式应用方法混杂

在一个页面中保证只使用一种方法进行样式引入，以保证代码的整洁和一致，提高代码的可读性和可维护性

2.3.7 避免使用 Id 选择器进行样式绑定

在 Vue.js 和其他现代前端框架中，通常推荐以组件为单位进行样式的定义和管理，而组件的特性是可重用和可复制的，但是 ID 在一个 HTML 文档中必须是唯一的，所以如果你在组件的样式中使用 ID 选择器，当这个组件被重复使用时，就会造成 ID 冲突。

因此，应该尽量避免在 Vue.js 组件的样式中使用 ID 选择器。取而代之的是，你可以使用类选择器或属性选择器来定义样式，这样既可以保证样式的优先级不会过高，也可以避免 ID 冲突的问题。

2.4 JavaScrpit 规范

变量声明、表达式、return、throw、break、continue、do-while结束要加分号。
用'===', '!=='代替'==', '!='；
不要在同个作用域下声明同名变量；不要使用未声明的变量；不要声明了变量却不使用。

三、注意事项

3.1 通用事项

开发时添加注释，新增或修改.html/.js/.vue/.css 文件等，添加注释，注意格式（参照2.2.6）
调用对象方法/CSS3/HTML5 考虑兼容性,防止页面布局错乱（document.body.clientWidth || document.documentElement.clientWidth）
调用接口时，注意上送参数格式（如金额、日期）
开发过程中，页面中 data 里的变量必须添加注释
前端获取重要数据在页面展示时，防止后端数据未返回，前端需考虑对此字段做缺省值处理，非判空处理
new Date(date).getTime()方法获取时间戳，在苹果手机上不兼容，返回 NAN，原因：ios 下只能解析反斜杠/而无法解析-导致的，解决办法：new Date(date.replace(/-/g,'/')).getTime()
神策埋点事件名（可不一致），属性名一致情况下，该属性值类型必须保持一致，否则导致后者埋点失败，若提供的神策埋点存在此问题，及时与模块负责人同步
开发、测试、回归环境合并代码若存在冲突处理，再冲突处理完成后进行代码比对
判空处理需与提供方（后端-接口、客户端-插件）确认为空返回的数据格式，切勿自行认定
多考虑不同场景，做好影响性分析，切勿影响存量逻辑，或修改通用规则，全量排查后进行修改，切勿遗漏
未登录场景调用接口，需与后端确认接口是否支持未登录调用
接口涉及上送金额，统一使用公共方法（$Fw.util.Format.formatAmt）做金额格式转换接口金额字段要求：字符串、保留 2 位小数、反格式化

3.2 手机银行事项

3.2.1 公共 js

涉及金额计算，请使用公共方法（$Fw.add，$Fw.Numsub，$Fw.mul，$Fw.division）进行加减乘除-避免精度问题
通过公共方法（$Fw.util.Format.getToday）进行获取前几日、几月、几年-页面中若使用 getToday 获取前几日/天/年方法，存在问题,对于特殊月份 2 月取值计算有误
接口涉及上送金额，统一使用公共方法（$Fw.util.Format.formatAmt）做金额格式转换接口金额字段要求：字符串、保留 2 位小数、反格式化-所有接口涉及上送金额字段，需要保留两位小数上送，如客户输入 100，接口上送时需要上送 100.00，否则导致接口报错

3.2.2 页面渲染

账号、金额等涉及接口上送字段，在页面使用过滤器进行格式化处理，不改变原有值-js 中进行格式化处理，在上送时需反格式化处理，易遗漏
若需展示人民币符号，请复制粘贴"¥"此符号进行替换-手动输入为错误符号￥，安卓机型可复现问题
调用接口，若字段为空，返回数据中无此字段，需做判空处理-若返回无此字段，页面展示undefined

3.2.3 代码规范

删除页面多余的代码（模拟数据、方法）
代码中判断条件语句不要用中文作为判断依据
严格按照 eslint 规范，类型判断是 string 还是 number 类型要区分清楚
css、js、文件命名统一按照规范文档命名

3.2.4 功能逻辑

交易完成后跳转结果页面，结果页需返回至首页，不可返回上页（根据功能区分），不可出现死循环跳转
添加埋点时，调用接口 fail 回调中加埋点变量时，需加报错弹窗 -fail 自定义设置后，会默认不提示错误信息，需手动弹窗提示
调用接口若有 loading 加载框，fail 回调中需主动关闭 loading
功能需求修改，需分析游客，非游客，登录，非登录，强弱认证以及当前页面接口数据是否返回为空对页面加载是否有影响-不同条件会影响页面加载
新增功能需考虑是否支持未登录、游客身份客户，是否支持村行，功能优化需考虑是否涉及温情版改造
功能界面若需登录/或游客认证，应考虑是否存在营销广告位、在线客服等不可控登录/游客入口进入

3.2.5 交互设计

首次查询时不应展示上拉加载组件，应加判断条件，接口查询出数据后展示
点击范围区域扩大
功能首页涉及内容较多建议分组件开发、维护，各组件的生命周期中写对应方法—局部加载
tab 页面，仅首次点击时需做查询，无需每次点击时反复请求，非首次切换后，客户可手动下拉刷新，上拉加载；点击同一个 tab 页签，不做刷新处理
页面涉及多接口调用，可自定义控制 loading 展示以及关闭，避免加载断层
涉及下一步展示密码弹窗场景，需自动弹起键盘，无需客户手动再次点击，此项纳入概要设计、代码检查规范中

50 KiB Raw Permalink Blame History Unescape Escape

一、文件命名规范

1.1 文件夹以及文件命名

1.2 vue文件内css的命名规则

1.3 vue文件内js的命名规则

二、编码规范

2.1 sass 规范

2.1.1 Sass 目录规范

2.1.2 目录说明

2.1.3 全局CSS样式

2.1.4 使用实例

2.2 vue 编码规范

2.2.1 vue 文件基本结构

2.2.2 template

2.2.3 script

2.2.4 style

2.2.5 指令规范

2.2.6 注释规范

2.3 样式规范

2.3.1 数值与单位

2.3.2 样式属性顺序

2.3.3 合理使用使用引号

2.3.4 避免使用!important

2.3.5 避免使用行内样式

2.3.6 避免不同样式应用方法混杂

2.3.7 避免使用 Id 选择器进行样式绑定

2.4 JavaScrpit 规范

三、注意事项

3.1 通用事项

3.2 手机银行事项

3.2.1 公共 js

3.2.2 页面渲染

3.2.3 代码规范

3.2.4 功能逻辑

3.2.5 交互设计

50 KiB

Raw Permalink Blame History