a2bei4-utils 1.0.6 → 1.0.8

package/dist/a2bei4.utils.cjs.js

@@ -357,7 +357,111 @@ function getAllSearchParams() {
 function getSearchParam(key) {
     const params = getAllSearchParams();
     return params[key];
-}
+}
+
+/**
+ * 全屏操作辅助工具对象
+ * @namespace fullscreenHelper
+ */
+const fullscreenHelper = {
+    /**
+     * 请求进入全屏模式
+     * @param {Element} element - 要全屏显示的元素
+     * @returns {Promise<void> | undefined} 全屏请求 Promise（如支持）
+     */
+    requestFullscreen: (element) => {
+        if (!element) {
+            console.warn("未提供有效的 DOM 元素");
+            return;
+        }
+        if (element.requestFullscreen) {
+            return element.requestFullscreen();
+        } else if (element.mozRequestFullScreen) {
+            return element.mozRequestFullScreen();
+        } else if (element.webkitRequestFullscreen) {
+            return element.webkitRequestFullscreen();
+        } else if (element.msRequestFullscreen) {
+            return element.msRequestFullscreen();
+        } else {
+            console.warn("当前浏览器不支持全屏 API");
+        }
+    },
+
+    /**
+     * 退出全屏模式
+     * @returns {Promise<void> | undefined} 退出全屏请求 Promise（如支持）
+     */
+    exitFullscreen: () => {
+        if (document.exitFullscreen) {
+            return document.exitFullscreen();
+        } else if (document.mozCancelFullScreen) {
+            return document.mozCancelFullScreen();
+        } else if (document.webkitExitFullscreen) {
+            return document.webkitExitFullscreen();
+        } else if (document.msExitFullscreen) {
+            return document.msExitFullscreen();
+        }
+    },
+
+    /**
+     * 获取当前全屏元素
+     * @returns {Element | null} 当前处于全屏模式的元素，无则返回 null
+     */
+    getFullscreenElement: () => {
+        return document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement || document.msFullscreenElement || null;
+    },
+
+    /**
+     * 检测当前是否处于全屏模式
+     * @returns {boolean} 是否全屏中
+     */
+    isFullscreen: () => {
+        return !!(document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement || document.msFullscreenElement);
+    },
+
+    /**
+     * 检测浏览器是否支持全屏 API
+     * @returns {boolean} 是否支持全屏
+     */
+    isFullscreenEnabled: () => {
+        return !!(document.fullscreenEnabled || document.mozFullScreenEnabled || document.webkitFullscreenEnabled || document.msFullscreenEnabled);
+    },
+
+    /**
+     * 切换指定元素的全屏状态
+     * @param {Element} element - 要切换全屏的元素
+     * @returns {Promise<void> | undefined} 全屏操作 Promise
+     */
+    toggleFullscreen: (element) => {
+        if (fullscreenHelper.isFullscreen()) {
+            return fullscreenHelper.exitFullscreen();
+        } else {
+            return fullscreenHelper.requestFullscreen(element);
+        }
+    },
+
+    /**
+     * 监听全屏变化事件
+     * @param {Function} callback - 全屏状态变化时的回调函数，参数为 isFullscreen: boolean
+     * @returns {Function} 取消监听的函数
+     */
+    onFullscreenChange: (callback) => {
+        const handler = () => {
+            callback(fullscreenHelper.isFullscreen());
+        };
+        document.addEventListener("fullscreenchange", handler);
+        document.addEventListener("webkitfullscreenchange", handler);
+        document.addEventListener("mozfullscreenchange", handler);
+        document.addEventListener("msfullscreenchange", handler);
+
+        return () => {
+            document.removeEventListener("fullscreenchange", handler);
+            document.removeEventListener("webkitfullscreenchange", handler);
+            document.removeEventListener("mozfullscreenchange", handler);
+            document.removeEventListener("msfullscreenchange", handler);
+        };
+    }
+};
 
 //#region 数据类型判断
 
@@ -1224,6 +1328,9 @@ async function fetchOrDownloadByUrl(url, fileName) {
             const urlPathname = new URL(url).pathname;
             // 获取路径的最后一部分作为文件名，并移除可能的查询参数
             fileName = urlPathname.substring(urlPathname.lastIndexOf("/") + 1).split("?")[0];
+            if (fileName) {
+                fileName = decodeURIComponent(fileName);
+            }
         } catch (e) {}
         // 如果提取后文件名为空（例如 URL 以 '/' 结尾），也使用时间戳
         if (!fileName) {
@@ -1899,6 +2006,64 @@ function extractFullyCheckedKeys(treeData, selectedKeys, idKey = "id", childrenK
         checked: [...checked],
         halfChecked: [...halfChecked]
     };
+}
+
+/**
+ * 在树形结构中查找目标节点的完整路径（从根节点到目标节点，含目标节点自身）。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} nodes - 树形结构森林（支持多根）
+ * @param {any} targetValue - 目标节点的 key 值
+ * @param {string} [key='id'] - 节点唯一标识字段
+ * @param {string} [parentKey='pid'] - 父节点标识字段（指向父节点的 key 值）
+ * @param {string} [childrenKey='children'] - 子节点数组字段
+ * @returns {T[]} 从根到目标节点的路径数组；未找到返回空数组
+ *
+ * @example
+ * const tree = [
+ *   { id: 1, pid: null, children: [
+ *     { id: 2, pid: 1, children: [
+ *       { id: 3, pid: 2 }
+ *     ]}
+ *   ]}
+ * ];
+ * findTreeNodePath(tree, 3); // [{id:1, ...}, {id:2, ...}, {id:3, ...}]
+ */
+function findTreeNodePath(nodes, targetValue, key = "id", parentKey = "pid", childrenKey = "children") {
+    if (!Array.isArray(nodes) || nodes.length === 0 || targetValue == null) {
+        return [];
+    }
+
+    // 1. 建立节点索引
+    const index = new Map();
+    const stack = [...nodes];
+
+    while (stack.length) {
+        const node = stack.pop();
+        if (!node || typeof node !== "object") continue;
+
+        index.set(node[key], node);
+
+        const children = node[childrenKey];
+        if (Array.isArray(children)) {
+            stack.push(...children);
+        }
+    }
+
+    // 2. 回溯路径（防循环引用）
+    const path = [];
+    const visited = new Set();
+    let cur = index.get(targetValue);
+
+    while (cur && !visited.has(cur[key])) {
+        visited.add(cur[key]);
+        path.push(cur);
+
+        const parentValue = cur[parentKey];
+        cur = parentValue != null ? index.get(parentValue) : undefined;
+    }
+
+    return path.reverse();
 }
 
 /**
@@ -2324,8 +2489,10 @@ exports.extractFullyCheckedKeys = extractFullyCheckedKeys;
 exports.fetchOrDownloadByUrl = fetchOrDownloadByUrl;
 exports.findObjAttrValueById = findObjAttrValueById;
 exports.findTreeNodeById = findTreeNodeById;
+exports.findTreeNodePath = findTreeNodePath;
 exports.flatCompleteTree2NestedTree = flatCompleteTree2NestedTree;
 exports.formatTimeForLocale = formatTimeForLocale;
+exports.fullscreenHelper = fullscreenHelper;
 exports.getAllSearchParams = getAllSearchParams;
 exports.getDataType = getDataType;
 exports.getFunctionArgNames = getFunctionArgNames;