feat: 添加功能注释

src/views/systems/menu/utils/hook.tsx

@@ -10,15 +10,29 @@ import { useRenderIcon } from "@/components/ReIcon/src/hooks";
 import { cloneDeep, isAllEmpty, deviceDetection } from "@pureadmin/utils";
 // import { c } from "node_modules/vite/dist/node/moduleRunnerTransport.d-CXw_Ws6P";
 
+/**
+ * 自定义 Hook，用于管理菜单相关的状态和操作
+ * @returns 包含菜单相关状态和操作的对象
+ */
 export function useMenu() {
+  // 定义表单数据，使用 reactive 创建响应式对象，初始包含菜单名称字段
   const form = reactive({
     name: ""
   });
 
+  // 定义表单引用，用于获取表单实例
   const formRef = ref();
+  // 定义菜单数据列表，使用 ref 创建响应式对象，初始为空数组
   const dataList = ref([]);
+  // 定义加载状态，使用 ref 创建响应式对象，初始为 true 表示正在加载
   const loading = ref(true);
 
+  /**
+   * 根据菜单类型返回对应的标签类型或文本描述
+   * @param type - 菜单类型，取值为 1, 2, 3, 4
+   * @param text - 是否返回文本描述，默认为 false
+   * @returns 标签类型或文本描述
+   */
   const getMenuType = (type, text = false) => {
     switch (type) {
       case 1:
@@ -32,11 +46,13 @@ export function useMenu() {
     }
   };
 
+  // 定义表格列配置，用于渲染菜单表格
   const columns: TableColumnList = [
     {
       label: "菜单名称",
       prop: "name",
       align: "left",
+      // 自定义单元格渲染函数，显示菜单图标和名称
       cellRenderer: ({ row }) => (
         <>
           <span class="inline-block mr-1">
@@ -52,6 +68,7 @@ export function useMenu() {
       label: "菜单类型",
       prop: "type",
       width: 100,
+      // 自定义单元格渲染函数，显示菜单类型标签
       cellRenderer: ({ row, props }) => (
         <el-tag size={props.size} type={getMenuType(row.type)} effect="plain">
           {getMenuType(row.type, true)}
@@ -65,6 +82,7 @@ export function useMenu() {
     {
       label: "组件路径",
       prop: "component",
+      // 自定义格式化函数，若组件路径为空则显示路由路径
       formatter: ({ path, component }) =>
         isAllEmpty(component) ? path : component
     },
@@ -80,6 +98,7 @@ export function useMenu() {
     {
       label: "隐藏",
       prop: "visible",
+      // 自定义格式化函数，将布尔值转换为中文描述
       formatter: ({ visible }) => (visible ? "是" : "否"),
       width: 100
     },
@@ -91,46 +110,76 @@ export function useMenu() {
     }
   ];
 
+  /**
+   * 处理表格选中项变化的事件
+   * @param val - 选中项的值
+   */
   function handleSelectionChange(val) {
     console.log("handleSelectionChange", val);
   }
 
+  /**
+   * 重置表单数据并重新搜索菜单
+   * @param formEl - 表单实例
+   */
   function resetForm(formEl) {
     if (!formEl) return;
     // 手动清空菜单名称
     form.name = "";
+    // 重置表单字段
     formEl.resetFields();
+    // 重新搜索菜单
     onSearch();
   }
 
+  /**
+   * 搜索菜单数据
+   */
   async function onSearch() {
+    // 设置加载状态为正在加载
     loading.value = true;
+    // 请求菜单列表数据
     const { data } = await getMenuList({ name: "", pageNum: 1, pageSize: 100 }); // 这里是返回一维数组结构，前端自行处理成树结构，返回格式要求：唯一id加父节点parentId，parentId取父节点id
+    // 获取返回数据中的记录列表
     let newData = (data as any).records;
     if (!isAllEmpty(form.name)) {
-      // 前端搜索菜单名称
+      // 前端搜索菜单名称，过滤出包含搜索关键词的菜单
       newData = newData.filter(item =>
         transformI18n(item.name).includes(form.name)
       );
     }
-    dataList.value = handleTree(newData); // 处理成树结构
+    // 将一维数组数据处理成树结构
+    dataList.value = handleTree(newData);
     console.log("dataList", dataList.value);
+    // 模拟加载延迟，500ms 后设置加载状态为完成
     setTimeout(() => {
       loading.value = false;
     }, 500);
   }
 
+  /**
+   * 格式化上级菜单选项，将菜单数据转换为可用于下拉选择的选项
+   * @param treeList - 菜单树状数据
+   * @returns 格式化后的菜单选项数组
+   */
   function formatHigherMenuOptions(treeList) {
     if (!treeList || !treeList.length) return;
     const newTreeList = [];
     for (let i = 0; i < treeList.length; i++) {
+      // 对菜单名称进行国际化处理
       treeList[i].name = transformI18n(treeList[i].name);
+      // 递归处理子菜单
       formatHigherMenuOptions(treeList[i].children);
       newTreeList.push(treeList[i]);
     }
     return newTreeList;
   }
 
+  /**
+   * 打开新增或编辑菜单的对话框
+   * @param title - 对话框标题，默认为 "新增"
+   * @param row - 要编辑的菜单数据，可选
+   */
   function openDialog(title = "新增", row?: FormItemProps) {
     addDialog({
       title: `${title}菜单`,
@@ -168,10 +217,17 @@ export function useMenu() {
       fullscreen: deviceDetection(),
       fullscreenIcon: true,
       closeOnClickModal: false,
+      // 对话框内容渲染函数，渲染编辑表单
       contentRenderer: () => h(editForm, { ref: formRef, formInline: null }),
+      // 对话框确认前的回调函数
       beforeSure: (done, { options }) => {
+        // 获取表单实例
         const FormRef = formRef.value.getRef();
+        // 获取表单数据
         const curData = options.props.formInline as FormItemProps;
+        /**
+         * 处理成功操作后的通用任务，如提示消息、关闭对话框、刷新表格数据
+         */
         function chores() {
           message(
             `您${title}了菜单名称为${transformI18n(curData.name)}的这条数据`,
@@ -179,15 +235,19 @@ export function useMenu() {
               type: "success"
             }
           );
-          done(); // 关闭弹框
-          onSearch(); // 刷新表格数据
+          // 关闭对话框
+          done();
+          // 刷新表格数据
+          onSearch();
         }
+        // 验证表单
         FormRef.validate(valid => {
           if (valid) {
             // 表单规则校验通过
             if (title === "新增") {
               curData.visible =
                 curData.visible || curData.visible === 0 ? 1 : 0;
+              // 调用新增菜单接口
               addMenu(curData).then(res => {
                 if ((res as any).code === "0") {
                   chores();
@@ -201,6 +261,7 @@ export function useMenu() {
               curData.id = row?.id;
               curData.visible =
                 curData.visible || curData.visible === 0 ? 1 : 0;
+              // 调用更新菜单接口
               updateMenu(curData).then(res => {
                 if ((res as any).code === "0") {
                   chores();
@@ -214,17 +275,23 @@ export function useMenu() {
     });
   }
 
+  /**
+   * 处理删除菜单的操作
+   * @param row - 要删除的菜单数据
+   */
   function handleDelete(row) {
     console.log("handleDelete", row.id);
     if (!row.id) {
       message("id不能为空", { type: "error" });
       return;
     }
+    // 调用删除菜单接口
     deleteMenu({ id: row.id }).then(res => {
       if ((res as any).code === "0") {
         message(`您删除了菜单名称为${transformI18n(row.title)}的这条数据`, {
           type: "success"
         });
+        // 刷新表格数据
         onSearch();
       } else {
         message((res as any).msg, { type: "error" });
@@ -232,6 +299,7 @@ export function useMenu() {
     });
   }
 
+  // 组件挂载后执行搜索操作
   onMounted(() => {
     onSearch();
   });