feat: 🚀 优化代码注释 && 升级element到2.2.6

升级element解决tabs存在的bug

README.md

@@ -104,9 +104,9 @@ npm run commit
 
 #### 1、登录页：
 
-![login_bg03](https://iamge-1259297738.cos.ap-chengdu.myqcloud.com/md/login_bg03.png)
+![login-light](https://iamge-1259297738.cos.ap-chengdu.myqcloud.com/md/login-light.png)
 
-![login_dark01](https://iamge-1259297738.cos.ap-chengdu.myqcloud.com/md/login_dark01.png)
+![login-dark](https://iamge-1259297738.cos.ap-chengdu.myqcloud.com/md/login-dark.png)
 
 #### 2、首页：
 

package.json

@@ -24,7 +24,7 @@
 		"axios": "^0.27.2",
 		"echarts": "^5.3.0",
 		"echarts-liquidfill": "^3.1.0",
-		"element-plus": "^2.2.5",
+		"element-plus": "^2.2.6",
 		"js-md5": "^0.7.3",
 		"nprogress": "^0.2.0",
 		"pinia": "^2.0.12",

src/api/config/servicePort.ts

@@ -1,3 +1,3 @@
-// 后端微服务端口名
+// * 后端微服务端口名
 export const PORT1 = "/geeker";
-export const PORT2 = "/user";
+export const PORT2 = "/hooks";

src/api/helper/axiosCancel.ts

@@ -13,6 +13,7 @@ export class AxiosCanceler {
 	/**
 	 * @description: 添加请求
 	 * @param {Object} config
+	 * @return void
 	 */
 	addPending(config: AxiosRequestConfig) {
 		// * 在请求开始前，对之前的请求做检查取消操作

src/api/helper/checkStatus.ts

@@ -1,8 +1,9 @@
 import { ElMessage } from "element-plus";
 
 /**
- * @description: 校验状态码
- * @param {number} status
+ * @description: 校验网络请求状态码
+ * @param {Number} status
+ * @return void
  */
 export const checkStatus = (status: number): void => {
 	switch (status) {

src/api/index.ts

@@ -6,15 +6,13 @@ import { ResultEnum } from "@/enums/httpEnum";
 import { checkStatus } from "./helper/checkStatus";
 import { ElMessage } from "element-plus";
 import { GlobalStore } from "@/store";
-
 import router from "@/routers";
 
 const globalStore = GlobalStore();
-
 const axiosCanceler = new AxiosCanceler();
 
 const config = {
-	// 默认地址
+	// 默认地址请求地址，可在 .env 开头文件中修改
 	baseURL: import.meta.env.VITE_API_URL as string,
 	// 设置超时时间（10s）
 	timeout: ResultEnum.TIMEOUT as number,

src/components/ImportExcel/index.vue

@@ -41,8 +41,8 @@ import { ElNotification } from "element-plus";
 
 export interface ExcelParameterProps {
 	title: string; // 标题
-	tempUrl: (params: any) => Promise<any>; // 下载模板的Api
-	importUrl: (params: any) => Promise<any>; // 批量导入的Api
+	tempApi: (params: any) => Promise<any>; // 下载模板的Api
+	importApi: (params: any) => Promise<any>; // 批量导入的Api
 	getTableList: () => Promise<any>; // 获取表格数据的Api
 }
 
@@ -61,24 +61,28 @@ const acceptParams = (params?: any): void => {
 	dialogVisible.value = true;
 };
 
-// Excel模板下载
+// Excel 导入模板下载
 const downloadTemp = () => {
-	if (!parameter.value.tempUrl) return;
-	useDownload(parameter.value.tempUrl, `${parameter.value.title}模板`);
+	if (!parameter.value.tempApi) return;
+	useDownload(parameter.value.tempApi, `${parameter.value.title}模板`);
 };
 
 // 文件上传
 const uploadExcel = async (param: any) => {
 	let excelFormData = new FormData();
 	excelFormData.append("file", param.file);
 	excelFormData.append("isCover", isCover.value as unknown as Blob);
-	const res = parameter.value.importUrl && (await parameter.value.importUrl(excelFormData));
+	if (!parameter.value.importApi) return;
+	const res = await parameter.value.importApi(excelFormData);
 	if (res.code !== 200) return param.onError();
 	parameter.value.getTableList && parameter.value.getTableList();
 	dialogVisible.value = false;
 };
 
-// 文件上传之前判断
+/**
+ * @description 文件上传之前判断
+ * @param file 上传的文件
+ * */
 const beforeExcelUpload = (file: any) => {
 	const isExcel =
 		file.type === "application/vnd.ms-excel" || file.type === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
@@ -106,6 +110,7 @@ const handleExceed = (): void => {
 		type: "warning"
 	});
 };
+
 // 上传错误提示
 const excelUploadError = (): void => {
 	ElNotification({
@@ -114,6 +119,7 @@ const excelUploadError = (): void => {
 		type: "error"
 	});
 };
+
 // 上传成功提示
 const excelUploadSuccess = (): void => {
 	ElNotification({

src/config/piniaPersist.ts

@@ -1,6 +1,10 @@
 import { PersistedStateOptions } from "pinia-plugin-persistedstate";
 
-// pinia持久化参数配置
+/**
+ * @description pinia持久化参数配置
+ * @param {String} key 存储到持久化的 name
+ * @return persist
+ * */
 const piniaPersistConfig = (key: string) => {
 	const persist: PersistedStateOptions = {
 		key,

src/directives/index.ts

@@ -1,4 +1,3 @@
-// import directives
 import { App } from "vue";
 import copy from "./modules/copy";
 import waterMarker from "./modules/waterMarker";
@@ -20,7 +19,7 @@ const directivesList: any = {
 const directives = {
 	install: function (app: App<Element>) {
 		Object.keys(directivesList).forEach(key => {
-			// 注册自定义指令
+			// 注册所有自定义指令
 			app.directive(key, directivesList[key]);
 		});
 	}

src/hooks/useDark.ts

@@ -8,6 +8,7 @@ export const useDark = () => {
 	const globalStore = GlobalStore();
 	const themeConfig = computed(() => globalStore.themeConfig);
 
+	// 切换模式
 	const switchTheme = () => {
 		const body = document.documentElement as HTMLElement;
 		if (themeConfig.value.isDark) body.setAttribute("class", "dark");

src/hooks/useDownload.ts

@@ -2,14 +2,15 @@ import { ElNotification } from "element-plus";
 
 /**
  * @description 接收数据流生成blob，创建链接，下载文件
- * @param url 导出表格的api地址(必传)
- * @param tempName 导出的文件名(必传)
- * @param params 导出的参数(默认为空对象)
- * @param isNotify 是否有导出消息提示(默认为 true)
- * @param fileType 导出的文件格式(默认为.xlsx)
+ * @param {Function} api 导出表格的api方法(必传)
+ * @param {String} tempName 导出的文件名(必传)
+ * @param {Object} params 导出的参数(默认为空对象)
+ * @param {Boolean} isNotify 是否有导出消息提示(默认为 true)
+ * @param {String} fileType 导出的文件格式(默认为.xlsx)
+ * @return void
  * */
 export const useDownload = async (
-	url: (param: any) => Promise<any>,
+	api: (param: any) => Promise<any>,
 	tempName: string,
 	params: any = {},
 	isNotify: boolean = true,
@@ -24,7 +25,7 @@ export const useDownload = async (
 		});
 	}
 	try {
-		const res = await url(params);
+		const res = await api(params);
 		// 这个地方的type,经测试不传也没事，因为zip文件不知道type是什么
 		// const blob = new Blob([res], {
 		// 	type: "application/vnd.ms-excel;charset=UTF-8"

src/hooks/useEcharts.ts

@@ -3,12 +3,13 @@ import * as echarts from "echarts";
 
 /**
  * @description 使用Echarts(只是为了添加图表响应式)
- * @param myChart Echarts实例(必传)
- * @param option 绘制Echarts的参数(必传)
+ * @param {Element} myChart Echarts实例(必传)
+ * @param {Object} options 绘制Echarts的参数(必传)
+ * @return void
  * */
-export const useEcharts = (myChart: echarts.ECharts, option: echarts.EChartsCoreOption) => {
-	if (option && typeof option === "object") {
-		myChart.setOption(option);
+export const useEcharts = (myChart: echarts.ECharts, options: echarts.EChartsCoreOption) => {
+	if (options && typeof options === "object") {
+		myChart.setOption(options);
 	}
 	const echartsResize = () => {
 		myChart && myChart.resize();

src/hooks/useHandleData.ts

@@ -3,13 +3,14 @@ import { HandleData } from "./interface";
 
 /**
  * @description 操作单条数据信息(二次确认【删除、禁用、启用、重置密码】)
- * @param {Function} apiUrl 操作数据接口的apiUrl(必传)
- * @param {object} prams 携带的参数 {id,params}(必传)
- * @param {string} message 提示信息(必传)
- * @param {string} confirmType icon类型(不必传,默认为 warning)
+ * @param {Function} api 操作数据接口的api方法(必传)
+ * @param {Object} params 携带的操作数据参数 {id,params}(必传)
+ * @param {String} message 提示信息(必传)
+ * @param {String} confirmType icon类型(不必传,默认为 warning)
+ * @return Promise
  */
 export const useHandleData = (
-	apiUrl: (params: any) => Promise<any>,
+	api: (params: any) => Promise<any>,
 	params: any,
 	message: string,
 	confirmType: HandleData.MessageType = "warning"
@@ -21,7 +22,7 @@ export const useHandleData = (
 			type: confirmType,
 			draggable: true
 		}).then(async () => {
-			const res = await apiUrl(params);
+			const res = await api(params);
 			if (!res) return reject(false);
 			ElMessage({
 				type: "success",

src/hooks/useOnline.ts

@@ -1,7 +1,7 @@
 import { ref, onMounted, onUnmounted } from "vue";
 
 /**
- * @description 用户网络是否可用
+ * @description 网络是否可用
  * */
 export const useOnline = () => {
 	const online = ref(true);

src/hooks/useSelection.ts

@@ -9,7 +9,7 @@ export const useSelection = () => {
 	// 选中的数据列表
 	const selectedList = ref([]);
 
-	// 当前选中的所有ids(数组)
+	// 当前选中的所有ids(数组)，可根据项目自行配置id字段
 	const selectedListIds = computed((): string[] => {
 		let ids: string[] = [];
 		selectedList.value.forEach(item => {

src/hooks/useTable.ts

@@ -3,12 +3,11 @@ import { reactive, computed, onMounted, toRefs } from "vue";
 
 /**
  * @description table 页面操作方法封装
- * @param apiUrl 获取表格数据 ApiUrl(必传)
- * @param initParam 获取数据初始化参数(不必传，默认为{})
- * @param isPageable 是否有分页(不必传，默认为true)
- * @param tableRef 当前表格的DOM(不必传，默认为“”)
+ * @param {Function} api 获取表格数据 api 方法(必传)
+ * @param {Object} initParam 获取数据初始化参数(不必传，默认为{})
+ * @param {Boolean} isPageable 是否有分页(不必传，默认为true)
  * */
-export const useTable = (apiUrl: (params: any) => Promise<any>, initParam: any = {}, isPageable: boolean = true) => {
+export const useTable = (api: (params: any) => Promise<any>, initParam: object = {}, isPageable: boolean = true) => {
 	const state = reactive<Table.TableStateProps>({
 		// 表格数据
 		tableData: [],
@@ -46,7 +45,7 @@ export const useTable = (apiUrl: (params: any) => Promise<any>, initParam: any =
 		}
 	});
 
-	// 设置表单查询默认值 && 获取表格数据(reset函数的作用刚好是这两个功能)
+	// 初始化的时候需要做的事情就是 设置表单查询默认值 && 获取表格数据(reset函数的作用刚好是这两个功能)
 	onMounted(() => {
 		reset();
 	});
@@ -57,10 +56,10 @@ export const useTable = (apiUrl: (params: any) => Promise<any>, initParam: any =
 	 * */
 	const getTableList = async () => {
 		try {
-			// 更新查询参数
+			// 先更新查询参数
 			updatedTotalParam();
 			Object.assign(state.totalParam, initParam);
-			const { data } = await apiUrl(state.totalParam);
+			const { data } = await api(state.totalParam);
 			state.tableData = isPageable ? data.datalist : data;
 			// 解构后台返回的分页数据(如果有分页更新分页信息)
 			const { pageNum, pageSize, total } = data;
@@ -90,7 +89,7 @@ export const useTable = (apiUrl: (params: any) => Promise<any>, initParam: any =
 
 	/**
 	 * @description 更新分页信息
-	 * @param resPageable 后台返回的分页数据
+	 * @param {Object} resPageable 后台返回的分页数据
 	 * @return void
 	 * */
 	const updatePageable = (resPageable: Table.Pageable) => {
@@ -122,7 +121,7 @@ export const useTable = (apiUrl: (params: any) => Promise<any>, initParam: any =
 
 	/**
 	 * @description 每页条数改变
-	 * @param val 当前条数
+	 * @param {Number} val 当前条数
 	 * @return void
 	 * */
 	const handleSizeChange = (val: number) => {
@@ -133,7 +132,7 @@ export const useTable = (apiUrl: (params: any) => Promise<any>, initParam: any =
 
 	/**
 	 * @description 当前页改变
-	 * @param val 当前页
+	 * @param {Number} val 当前页
 	 * @return void
 	 * */
 	const handleCurrentChange = (val: number) => {

src/layout/Footer/index.vue

@@ -4,8 +4,6 @@
 	</div>
 </template>
 
-<script setup lang="ts"></script>
-
 <style scoped lang="scss">
 @import "./index.scss";
 </style>

src/layout/Header/components/Avatar.vue

@@ -28,7 +28,7 @@ import { GlobalStore } from "@/store";
 const router = useRouter();
 const globalStore = GlobalStore();
 
-// logout
+// 退出登录
 const logout = () => {
 	ElMessageBox.confirm("您是否确认退出登录?", "温馨提示", {
 		confirmButtonText: "确定",
@@ -49,7 +49,7 @@ interface DialogExpose {
 }
 const infoRef = ref<null | DialogExpose>(null);
 const passwordRef = ref<null | DialogExpose>(null);
-// openDialog
+// 打开修改密码和个人信息弹窗
 const openDialog = (refName: string) => {
 	if (refName == "infoRef") return infoRef.value?.openDialog();
 	passwordRef.value?.openDialog();