前端编码规范

半城云前端开发规范

前言

这里只列出半城云特殊约定的规范、或者是 eslint、prettier 难以限制的规则。其它未提及的可参考airbnb javascript 代码规范。

组件

文件大小限制

单文件不能超过 600 行，若超过应进行拆分。

组件编写顺序

1. 常量、变量、hooks 函数 (按照相关性)

2. 工具函数、事件处理函数

3. render

// 正例
const [visible, setVisible] = useState < boolean > false;

const [submitting, setSubmitting] = useState(false);
const handleSubmit = async (values: LoginParamsType) => {
  setSubmitting(true);
};

const { status } = data;
return <div className={styles.container}>{status}</div>;

事件处理函数

建议使用 handleSomething 命名形式，以及按照逻辑顺序排序

// 正例
const handleStep1 = () => {};
const handleStep2 = () => {};

return (
  <>
    <button onClick={handleStep1}>第1步</button>
    <button onClick={handleStep2}>第2步</button>
  </>
);

// 反例
const step2 = () => {};
const step1 = () => {};

return (
  <>
    <button onClick={step1}>第1步</button>
    <button onClick={step2}>第2步</button>
  </>
);

属性书写规范

1. 小驼峰命名

2. 布尔值为 true 可省略

3. 事件放在最后

// 正例
<Button loading htmlType="submit" onClick={() => {}}>
  btn
</Button>

// 反例
<Button loading={true} onClick={() => {}} htmltype="submit">
  btn
</Button>

尽量不要手动操作 DOM

尽量（不到万不得已）不要手动操作 DOM，包括：增删改 dom 元素、以及更改样式、添加事件等。

css

属性顺序

1. 展示类型及文档流相关/Display & Flow

2. 定位信息/Positioning

3. 边距/Margins, Padding

4. 元素尺寸/Dimensions

5. 边框/Borders, Outline

6. 文字排版/Typographic Styles

7. 背景/Backgrounds

8. 其他如透明度，光标样式及衍生内容/Opacity, Cursors, Generated Content

/* 正例 */
display: inline-block;
position: releative;
margin: 1em 0;
padding: 1em 4em;
width: 100px;
height: 100px;
font-size: 3em;
font-family: Avenir, Helvetica, Arial, sans-serif;
text-align: center;
text-transform: uppercase;
text-decoration: none;
color: #fff;
background: #196e76;
border: 0.25em solid #196e76;
box-shadow: inset 0.25em 0.25em 0.5em rgba(0, 0, 0, 0.3), 0.5em 0.5em 0 #444;

不建议单一属性类

无太大意义，而且要写较多类名，以及无法获得编辑器补全提示。

/* 反例 */
.font-weight-400 {
  font-weight: 400;
}
.font-weight-500 {
  font-weight: 500;
}
.font-weight-600 {
  font-weight: 600;
}

约定前缀

bem 命名方式进行样式隔离时，可参考以下类名前缀 全局: g- 页面: p- 组件: c-

git

不建议忽略 package-lock.json

无法锁定版本，依赖版本不一致可能导致问题

rebase 代替 merge

html

语义化标签

HTML5 中新增很多语义化标签，所以优先使用语义化标签，避免一个页面都是 div 或者 p 标签

<!-- 正例 -->
<header></header>
<footer></footer>

<!-- 反例 -->
<div>
  <p></p>
</div>

js

避免名称冗余

// 正例
const car = {
  make: "Honda",
  model: "Accord",
  color: "Blue",
};

// 反例
const car = {
  carMake: "Honda",
  carModel: "Accord",
  carColor: "Blue",
};

命名适用动词+名词形式

// 正例
const getData = () => {};

// 反例
const dataGet = () => {};

命名严谨性

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。注意词性、单复数、时态等的准确表达。 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。

正例：henan / luoyang / rmb 等国际通用的名称，可视同英文。

反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

杜绝完全不规范的缩写，避免望文不知义

反例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。

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

说明：任何情形，没有必要插入多个空行进行隔开。

使用字面值创建对象

// 正例
let user = {};

// 反例
let user = new Object();

使用 ES6,7

必须优先使用 ES6,7 中新增的语法糖和函数。这将简化你的程序，并让你的代码更加灵活和可复用。

必须强制使用 ES6, ES7 的新语法，比如箭头函数、await/async ， 解构， let ， for...of 等等

条件判断和循环最多三层

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

其它

文件引用

按照外部包、公共文件、绝对路径、相对路径的顺序排序

import { Button, Divider, message, Input, Drawer } from "antd";
import React, { useState, useRef } from "react";
import { PageContainer, FooterToolbar } from "@ant-design/pro-layout";
import ProTable, { ProColumns, ActionType } from "@ant-design/pro-table";
import ProDescriptions from "@ant-design/pro-descriptions";
import test from "@/utils/utils";
import request from "../../utils/request";
import CreateForm from "./components/CreateForm";

另外要注意引用大小写问题，在一些对文件路径大小写敏感的系统会出问题。

控制台信息

留意排查项目报错或者警告信息，而不是能跑就行。

删除无用代码

使用了 git，对于无用代码必须及时删除，例如：一些调试的 console 语句、无用的弃用功能代码。

附： 函数方法常用的动词:

get 获取/set 设置,
add 增加/remove 删除
create 创建/destory 移除
start 启动/stop 停止
open 打开/close 关闭,
read 读取/write 写入
load 载入/save 保存,
create 创建/destroy 销毁
begin 开始/end 结束,
backup 备份/restore 恢复
import 导入/export 导出,
split 分割/merge 合并
inject 注入/extract 提取,
attach 附着/detach 脱离
bind 绑定/separate 分离,
view 查看/browse 浏览
edit 编辑/modify 修改,
select 选取/mark 标记
copy 复制/paste 粘贴,
undo 撤销/redo 重做
insert 插入/delete 移除,
add 加入/append 添加
clean 清理/clear 清除,
index 索引/sort 排序
find 查找/search 搜索,
increase 增加/decrease 减少
play 播放/pause 暂停,
launch 启动/run 运行
compile 编译/execute 执行,
debug 调试/trace 跟踪
observe 观察/listen 监听,
build 构建/publish 发布
input 输入/output 输出,
encode 编码/decode 解码
encrypt 加密/decrypt 解密,
compress 压缩/decompress 解压缩
pack 打包/unpack 解包,
parse 解析/emit 生成
connect 连接/disconnect 断开,
send 发送/receive 接收
download 下载/upload 上传,
refresh 刷新/synchronize 同步
update 更新/revert 复原,
lock 锁定/unlock 解锁
check out 签出/check in 签入,
submit 提交/commit 交付
push 推/pull 拉,
expand 展开/collapse 折叠
begin 起始/end 结束,
start 开始/finish 完成
enter 进入/exit 退出,
abort 放弃/quit 离开
obsolete 废弃/depreciate 废旧,
collect 收集/aggregate 聚集

附：常用的缩写:

常见编程命名缩写

项目

项目命名

全部采用小写方式， 以中划线分隔。

正例：mall-management-system

反例：mall_management-system / mallManagementSystem

目录命名

全部采用小写方式， 以中划线分隔，有复数结构时，要采用复数命名法

正例： scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts

反例： script / style / demo_scripts / demoStyles

【特殊】react 项目中的页面、组件目录，使用大驼峰命名

正例： HeadSearch / PageLoading

反例： head-search / page-loading / authorized / notice-icon

项目结构

参照 ant desiagn pro

├── src                    源码目录
|   ├── assets             静态资源目录
|   ├── components         基础组件目录
|   ├── pages              页面文件目录
|   ├── services           公用服务接口目录
|   ├── styles             公用样式目录
|   ├── utils              公用工具目录

页面、组件结构

├── Login                  主目录
|   ├── components         组件
|   ├── data.ts            数据
|   ├── index.less         样式
|   ├── index.tsx          入口
|   ├── service.ts         接口
|   ├── type.d.ts          类型定义
|   ├── util.ts            工具函数

基本原则

就近原则，相关的文件放一起。