a2bei4-utils 1.0.7 → 1.0.8

package/dist/browser.cjs

@@ -52,8 +52,113 @@ 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);
+        };
+    }
+};
 
+exports.fullscreenHelper = fullscreenHelper;
 exports.getAllSearchParams = getAllSearchParams;
 exports.getSearchParam = getSearchParam;
 exports.getViewportSize = getViewportSize;

package/dist/browser.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"browser.cjs","sources":["../src/source/browser.js"],"sourcesContent":["/**\r\n * 视口尺寸对象。\r\n * @typedef {Object} ViewportDimensions\r\n * @property {number} w 视口宽度，单位像素。\r\n * @property {number} h 视口高度，单位像素。\r\n */\r\n\r\n/**\r\n * 获取当前视口（viewport）的宽高。\r\n *\r\n * 兼容策略：\r\n * 1. 优先使用 `window.innerWidth/innerHeight`（现代浏览器）。\r\n * 2. 降级到 `document.documentElement.clientWidth/clientHeight`（IE9+ 及怪异模式）。\r\n * 3. 最后降级到 `document.body.clientWidth/clientHeight`（IE6-8 怪异模式）。\r\n *\r\n * @returns {ViewportDimensions} 包含 `w`（宽度）和 `h`（高度）的对象，单位为像素。\r\n *\r\n * @example\r\n * const { w, h } = getViewportSize();\r\n * console.log(`视口尺寸：${w} × ${h}`);\r\n */\r\nexport function getViewportSize() {\r\n    const d = document,\r\n        root = d.documentElement,\r\n        body = d.body;\r\n\r\n    return {\r\n        w: window.innerWidth || root.clientWidth || body.clientWidth,\r\n        h: window.innerHeight || root.clientHeight || body.clientHeight\r\n    };\r\n}\r\n\r\n/**\r\n * 将当前页面 URL 的 query 部分解析成键值对对象。\r\n *\r\n * @returns {Record<string, string>} 所有查询参数组成的平凡对象\r\n *                                   （同名 key 仅保留最后一项）\r\n */\r\nexport function getAllSearchParams() {\r\n    const urlSearchParams = new URLSearchParams(location.search);\r\n    return Object.fromEntries(urlSearchParams.entries());\r\n}\r\n\r\n/**\r\n * 根据 key 获取当前页面 URL 中的单个查询参数。\r\n *\r\n * @param {string} key - 要提取的参数名\r\n * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`\r\n */\r\nexport function getSearchParam(key) {\r\n    const params = getAllSearchParams();\r\n    return params[key];\r\n}\r\n"],"names":[],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,eAAe,GAAG;AAClC,IAAI,MAAM,CAAC,GAAG,QAAQ;AACtB,QAAQ,IAAI,GAAG,CAAC,CAAC,eAAe;AAChC,QAAQ,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;AACtB;AACA,IAAI,OAAO;AACX,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW;AACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY;AACvE,KAAK,CAAC;AACN,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,kBAAkB,GAAG;AACrC,IAAI,MAAM,eAAe,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjE,IAAI,OAAO,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;AACzD,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,cAAc,CAAC,GAAG,EAAE;AACpC,IAAI,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;AACxC,IAAI,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACvB;;;;;;"}
+{"version":3,"file":"browser.cjs","sources":["../src/source/browser.js"],"sourcesContent":["/**\r\n * 视口尺寸对象。\r\n * @typedef {Object} ViewportDimensions\r\n * @property {number} w 视口宽度，单位像素。\r\n * @property {number} h 视口高度，单位像素。\r\n */\r\n\r\n/**\r\n * 获取当前视口（viewport）的宽高。\r\n *\r\n * 兼容策略：\r\n * 1. 优先使用 `window.innerWidth/innerHeight`（现代浏览器）。\r\n * 2. 降级到 `document.documentElement.clientWidth/clientHeight`（IE9+ 及怪异模式）。\r\n * 3. 最后降级到 `document.body.clientWidth/clientHeight`（IE6-8 怪异模式）。\r\n *\r\n * @returns {ViewportDimensions} 包含 `w`（宽度）和 `h`（高度）的对象，单位为像素。\r\n *\r\n * @example\r\n * const { w, h } = getViewportSize();\r\n * console.log(`视口尺寸：${w} × ${h}`);\r\n */\r\nexport function getViewportSize() {\r\n    const d = document,\r\n        root = d.documentElement,\r\n        body = d.body;\r\n\r\n    return {\r\n        w: window.innerWidth || root.clientWidth || body.clientWidth,\r\n        h: window.innerHeight || root.clientHeight || body.clientHeight\r\n    };\r\n}\r\n\r\n/**\r\n * 将当前页面 URL 的 query 部分解析成键值对对象。\r\n *\r\n * @returns {Record<string, string>} 所有查询参数组成的平凡对象\r\n *                                   （同名 key 仅保留最后一项）\r\n */\r\nexport function getAllSearchParams() {\r\n    const urlSearchParams = new URLSearchParams(location.search);\r\n    return Object.fromEntries(urlSearchParams.entries());\r\n}\r\n\r\n/**\r\n * 根据 key 获取当前页面 URL 中的单个查询参数。\r\n *\r\n * @param {string} key - 要提取的参数名\r\n * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`\r\n */\r\nexport function getSearchParam(key) {\r\n    const params = getAllSearchParams();\r\n    return params[key];\r\n}\r\n\r\n/**\r\n * 全屏操作辅助工具对象\r\n * @namespace fullscreenHelper\r\n */\r\nexport const fullscreenHelper = {\r\n    /**\r\n     * 请求进入全屏模式\r\n     * @param {Element} element - 要全屏显示的元素\r\n     * @returns {Promise<void> | undefined} 全屏请求 Promise（如支持）\r\n     */\r\n    requestFullscreen: (element) => {\r\n        if (!element) {\r\n            console.warn(\"未提供有效的 DOM 元素\");\r\n            return;\r\n        }\r\n        if (element.requestFullscreen) {\r\n            return element.requestFullscreen();\r\n        } else if (element.mozRequestFullScreen) {\r\n            return element.mozRequestFullScreen();\r\n        } else if (element.webkitRequestFullscreen) {\r\n            return element.webkitRequestFullscreen();\r\n        } else if (element.msRequestFullscreen) {\r\n            return element.msRequestFullscreen();\r\n        } else {\r\n            console.warn(\"当前浏览器不支持全屏 API\");\r\n        }\r\n    },\r\n\r\n    /**\r\n     * 退出全屏模式\r\n     * @returns {Promise<void> | undefined} 退出全屏请求 Promise（如支持）\r\n     */\r\n    exitFullscreen: () => {\r\n        if (document.exitFullscreen) {\r\n            return document.exitFullscreen();\r\n        } else if (document.mozCancelFullScreen) {\r\n            return document.mozCancelFullScreen();\r\n        } else if (document.webkitExitFullscreen) {\r\n            return document.webkitExitFullscreen();\r\n        } else if (document.msExitFullscreen) {\r\n            return document.msExitFullscreen();\r\n        }\r\n    },\r\n\r\n    /**\r\n     * 获取当前全屏元素\r\n     * @returns {Element | null} 当前处于全屏模式的元素，无则返回 null\r\n     */\r\n    getFullscreenElement: () => {\r\n        return document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement || document.msFullscreenElement || null;\r\n    },\r\n\r\n    /**\r\n     * 检测当前是否处于全屏模式\r\n     * @returns {boolean} 是否全屏中\r\n     */\r\n    isFullscreen: () => {\r\n        return !!(document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement || document.msFullscreenElement);\r\n    },\r\n\r\n    /**\r\n     * 检测浏览器是否支持全屏 API\r\n     * @returns {boolean} 是否支持全屏\r\n     */\r\n    isFullscreenEnabled: () => {\r\n        return !!(document.fullscreenEnabled || document.mozFullScreenEnabled || document.webkitFullscreenEnabled || document.msFullscreenEnabled);\r\n    },\r\n\r\n    /**\r\n     * 切换指定元素的全屏状态\r\n     * @param {Element} element - 要切换全屏的元素\r\n     * @returns {Promise<void> | undefined} 全屏操作 Promise\r\n     */\r\n    toggleFullscreen: (element) => {\r\n        if (fullscreenHelper.isFullscreen()) {\r\n            return fullscreenHelper.exitFullscreen();\r\n        } else {\r\n            return fullscreenHelper.requestFullscreen(element);\r\n        }\r\n    },\r\n\r\n    /**\r\n     * 监听全屏变化事件\r\n     * @param {Function} callback - 全屏状态变化时的回调函数，参数为 isFullscreen: boolean\r\n     * @returns {Function} 取消监听的函数\r\n     */\r\n    onFullscreenChange: (callback) => {\r\n        const handler = () => {\r\n            callback(fullscreenHelper.isFullscreen());\r\n        };\r\n        document.addEventListener(\"fullscreenchange\", handler);\r\n        document.addEventListener(\"webkitfullscreenchange\", handler);\r\n        document.addEventListener(\"mozfullscreenchange\", handler);\r\n        document.addEventListener(\"msfullscreenchange\", handler);\r\n\r\n        return () => {\r\n            document.removeEventListener(\"fullscreenchange\", handler);\r\n            document.removeEventListener(\"webkitfullscreenchange\", handler);\r\n            document.removeEventListener(\"mozfullscreenchange\", handler);\r\n            document.removeEventListener(\"msfullscreenchange\", handler);\r\n        };\r\n    }\r\n};\r\n"],"names":[],"mappings":"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"}

package/dist/browser.js

@@ -50,7 +50,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);
+        };
+    }
+};
 
-export { getAllSearchParams, getSearchParam, getViewportSize };
+export { fullscreenHelper, getAllSearchParams, getSearchParam, getViewportSize };
 //# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sources":["../src/source/browser.js"],"sourcesContent":["/**\r\n * 视口尺寸对象。\r\n * @typedef {Object} ViewportDimensions\r\n * @property {number} w 视口宽度，单位像素。\r\n * @property {number} h 视口高度，单位像素。\r\n */\r\n\r\n/**\r\n * 获取当前视口（viewport）的宽高。\r\n *\r\n * 兼容策略：\r\n * 1. 优先使用 `window.innerWidth/innerHeight`（现代浏览器）。\r\n * 2. 降级到 `document.documentElement.clientWidth/clientHeight`（IE9+ 及怪异模式）。\r\n * 3. 最后降级到 `document.body.clientWidth/clientHeight`（IE6-8 怪异模式）。\r\n *\r\n * @returns {ViewportDimensions} 包含 `w`（宽度）和 `h`（高度）的对象，单位为像素。\r\n *\r\n * @example\r\n * const { w, h } = getViewportSize();\r\n * console.log(`视口尺寸：${w} × ${h}`);\r\n */\r\nexport function getViewportSize() {\r\n    const d = document,\r\n        root = d.documentElement,\r\n        body = d.body;\r\n\r\n    return {\r\n        w: window.innerWidth || root.clientWidth || body.clientWidth,\r\n        h: window.innerHeight || root.clientHeight || body.clientHeight\r\n    };\r\n}\r\n\r\n/**\r\n * 将当前页面 URL 的 query 部分解析成键值对对象。\r\n *\r\n * @returns {Record<string, string>} 所有查询参数组成的平凡对象\r\n *                                   （同名 key 仅保留最后一项）\r\n */\r\nexport function getAllSearchParams() {\r\n    const urlSearchParams = new URLSearchParams(location.search);\r\n    return Object.fromEntries(urlSearchParams.entries());\r\n}\r\n\r\n/**\r\n * 根据 key 获取当前页面 URL 中的单个查询参数。\r\n *\r\n * @param {string} key - 要提取的参数名\r\n * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`\r\n */\r\nexport function getSearchParam(key) {\r\n    const params = getAllSearchParams();\r\n    return params[key];\r\n}\r\n"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,eAAe,GAAG;AAClC,IAAI,MAAM,CAAC,GAAG,QAAQ;AACtB,QAAQ,IAAI,GAAG,CAAC,CAAC,eAAe;AAChC,QAAQ,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;AACtB;AACA,IAAI,OAAO;AACX,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW;AACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY;AACvE,KAAK,CAAC;AACN,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,kBAAkB,GAAG;AACrC,IAAI,MAAM,eAAe,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjE,IAAI,OAAO,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;AACzD,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,cAAc,CAAC,GAAG,EAAE;AACpC,IAAI,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;AACxC,IAAI,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACvB;;;;"}
+{"version":3,"file":"browser.js","sources":["../src/source/browser.js"],"sourcesContent":["/**\r\n * 视口尺寸对象。\r\n * @typedef {Object} ViewportDimensions\r\n * @property {number} w 视口宽度，单位像素。\r\n * @property {number} h 视口高度，单位像素。\r\n */\r\n\r\n/**\r\n * 获取当前视口（viewport）的宽高。\r\n *\r\n * 兼容策略：\r\n * 1. 优先使用 `window.innerWidth/innerHeight`（现代浏览器）。\r\n * 2. 降级到 `document.documentElement.clientWidth/clientHeight`（IE9+ 及怪异模式）。\r\n * 3. 最后降级到 `document.body.clientWidth/clientHeight`（IE6-8 怪异模式）。\r\n *\r\n * @returns {ViewportDimensions} 包含 `w`（宽度）和 `h`（高度）的对象，单位为像素。\r\n *\r\n * @example\r\n * const { w, h } = getViewportSize();\r\n * console.log(`视口尺寸：${w} × ${h}`);\r\n */\r\nexport function getViewportSize() {\r\n    const d = document,\r\n        root = d.documentElement,\r\n        body = d.body;\r\n\r\n    return {\r\n        w: window.innerWidth || root.clientWidth || body.clientWidth,\r\n        h: window.innerHeight || root.clientHeight || body.clientHeight\r\n    };\r\n}\r\n\r\n/**\r\n * 将当前页面 URL 的 query 部分解析成键值对对象。\r\n *\r\n * @returns {Record<string, string>} 所有查询参数组成的平凡对象\r\n *                                   （同名 key 仅保留最后一项）\r\n */\r\nexport function getAllSearchParams() {\r\n    const urlSearchParams = new URLSearchParams(location.search);\r\n    return Object.fromEntries(urlSearchParams.entries());\r\n}\r\n\r\n/**\r\n * 根据 key 获取当前页面 URL 中的单个查询参数。\r\n *\r\n * @param {string} key - 要提取的参数名\r\n * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`\r\n */\r\nexport function getSearchParam(key) {\r\n    const params = getAllSearchParams();\r\n    return params[key];\r\n}\r\n\r\n/**\r\n * 全屏操作辅助工具对象\r\n * @namespace fullscreenHelper\r\n */\r\nexport const fullscreenHelper = {\r\n    /**\r\n     * 请求进入全屏模式\r\n     * @param {Element} element - 要全屏显示的元素\r\n     * @returns {Promise<void> | undefined} 全屏请求 Promise（如支持）\r\n     */\r\n    requestFullscreen: (element) => {\r\n        if (!element) {\r\n            console.warn(\"未提供有效的 DOM 元素\");\r\n            return;\r\n        }\r\n        if (element.requestFullscreen) {\r\n            return element.requestFullscreen();\r\n        } else if (element.mozRequestFullScreen) {\r\n            return element.mozRequestFullScreen();\r\n        } else if (element.webkitRequestFullscreen) {\r\n            return element.webkitRequestFullscreen();\r\n        } else if (element.msRequestFullscreen) {\r\n            return element.msRequestFullscreen();\r\n        } else {\r\n            console.warn(\"当前浏览器不支持全屏 API\");\r\n        }\r\n    },\r\n\r\n    /**\r\n     * 退出全屏模式\r\n     * @returns {Promise<void> | undefined} 退出全屏请求 Promise（如支持）\r\n     */\r\n    exitFullscreen: () => {\r\n        if (document.exitFullscreen) {\r\n            return document.exitFullscreen();\r\n        } else if (document.mozCancelFullScreen) {\r\n            return document.mozCancelFullScreen();\r\n        } else if (document.webkitExitFullscreen) {\r\n            return document.webkitExitFullscreen();\r\n        } else if (document.msExitFullscreen) {\r\n            return document.msExitFullscreen();\r\n        }\r\n    },\r\n\r\n    /**\r\n     * 获取当前全屏元素\r\n     * @returns {Element | null} 当前处于全屏模式的元素，无则返回 null\r\n     */\r\n    getFullscreenElement: () => {\r\n        return document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement || document.msFullscreenElement || null;\r\n    },\r\n\r\n    /**\r\n     * 检测当前是否处于全屏模式\r\n     * @returns {boolean} 是否全屏中\r\n     */\r\n    isFullscreen: () => {\r\n        return !!(document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement || document.msFullscreenElement);\r\n    },\r\n\r\n    /**\r\n     * 检测浏览器是否支持全屏 API\r\n     * @returns {boolean} 是否支持全屏\r\n     */\r\n    isFullscreenEnabled: () => {\r\n        return !!(document.fullscreenEnabled || document.mozFullScreenEnabled || document.webkitFullscreenEnabled || document.msFullscreenEnabled);\r\n    },\r\n\r\n    /**\r\n     * 切换指定元素的全屏状态\r\n     * @param {Element} element - 要切换全屏的元素\r\n     * @returns {Promise<void> | undefined} 全屏操作 Promise\r\n     */\r\n    toggleFullscreen: (element) => {\r\n        if (fullscreenHelper.isFullscreen()) {\r\n            return fullscreenHelper.exitFullscreen();\r\n        } else {\r\n            return fullscreenHelper.requestFullscreen(element);\r\n        }\r\n    },\r\n\r\n    /**\r\n     * 监听全屏变化事件\r\n     * @param {Function} callback - 全屏状态变化时的回调函数，参数为 isFullscreen: boolean\r\n     * @returns {Function} 取消监听的函数\r\n     */\r\n    onFullscreenChange: (callback) => {\r\n        const handler = () => {\r\n            callback(fullscreenHelper.isFullscreen());\r\n        };\r\n        document.addEventListener(\"fullscreenchange\", handler);\r\n        document.addEventListener(\"webkitfullscreenchange\", handler);\r\n        document.addEventListener(\"mozfullscreenchange\", handler);\r\n        document.addEventListener(\"msfullscreenchange\", handler);\r\n\r\n        return () => {\r\n            document.removeEventListener(\"fullscreenchange\", handler);\r\n            document.removeEventListener(\"webkitfullscreenchange\", handler);\r\n            document.removeEventListener(\"mozfullscreenchange\", handler);\r\n            document.removeEventListener(\"msfullscreenchange\", handler);\r\n        };\r\n    }\r\n};\r\n"],"names":[],"mappings":"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"}

package/dist/tree.cjs

@@ -179,11 +179,70 @@ 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();
 }
 
 exports.extractFullyCheckedKeys = extractFullyCheckedKeys;
 exports.findObjAttrValueById = findObjAttrValueById;
 exports.findTreeNodeById = findTreeNodeById;
+exports.findTreeNodePath = findTreeNodePath;
 exports.flatCompleteTree2NestedTree = flatCompleteTree2NestedTree;
 exports.nestedTree2IdMap = nestedTree2IdMap;
 //# sourceMappingURL=tree.cjs.map

package/dist/tree.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"tree.cjs","sources":["../src/source/tree.js"],"sourcesContent":["/**\r\n * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} data - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表\r\n */\r\nexport function nestedTree2IdMap(data, idKey = \"id\", childrenKey = \"children\") {\r\n    const retObj = {};\r\n    function fn(nodes) {\r\n        if (Array.isArray(nodes) && nodes.length > 0) {\r\n            nodes.forEach((node) => {\r\n                retObj[node[idKey]] = { ...node };\r\n                retObj[node[idKey]][childrenKey] = null;\r\n\r\n                fn(node[childrenKey]);\r\n            });\r\n        }\r\n    }\r\n    fn(data);\r\n    return retObj;\r\n}\r\n\r\n/**\r\n * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）\r\n * @param {number | string} [parentId=0] - 根节点标识值\r\n * @param {Object} [opts] - 字段映射配置\r\n * @param {string} [opts.idKey='id'] - 节点主键\r\n * @param {string} [opts.parentKey='parentId'] - 父节点外键\r\n * @param {string} [opts.childrenKey='children'] - 存放子节点的字段\r\n * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林\r\n */\r\nexport function flatCompleteTree2NestedTree(nodes, parentId = 0, { idKey = \"id\", parentKey = \"parentId\", childrenKey = \"children\" } = {}) {\r\n    const map = new Map(); // id -> node\r\n    const items = []; // 多根森林\r\n\r\n    // 1. 初始化：保证每个节点都有 children，并存入 map\r\n    for (const item of nodes) {\r\n        const node = { ...item, [childrenKey]: [] };\r\n        map.set(item[idKey], node);\r\n    }\r\n\r\n    // 2. 建立父子关系\r\n    for (const item of nodes) {\r\n        const node = map.get(item[idKey]);\r\n        const parentIdVal = item[parentKey];\r\n\r\n        if (parentIdVal === parentId) {\r\n            // 根层\r\n            items.push(node);\r\n        } else {\r\n            // 非根层：找到父节点，把自己挂上去\r\n            const parent = map.get(parentIdVal);\r\n            if (parent) parent[childrenKey].push(node);\r\n            // 如果 parent 不存在，说明数据不完整，可自定义处理\r\n        }\r\n    }\r\n\r\n    return items;\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {T | undefined} 找到的节点；未找到返回 `undefined`\r\n */\r\nexport function findTreeNodeById(id, arr, idKey = \"id\", childrenKey = \"children\") {\r\n    if (Array.isArray(arr) && arr.length > 0) {\r\n        for (let i = 0; i < arr.length; i++) {\r\n            const item = arr[i];\r\n            if (item[idKey]?.toString() === id?.toString()) {\r\n                return item;\r\n            } else if (Array.isArray(item[childrenKey]) && item[childrenKey].length > 0) {\r\n                const result = findTreeNodeById(id, item[childrenKey], idKey, childrenKey);\r\n                if (result) {\r\n                    return result;\r\n                }\r\n            }\r\n        }\r\n    }\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点，并返回其指定属性值。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [resultKey='name'] - 需要返回的字段\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {any} 找到的值；未找到返回 `undefined`\r\n */\r\nexport function findObjAttrValueById(id, arr, resultKey = \"name\", idKey = \"id\", childrenKey = \"children\") {\r\n    return findTreeNodeById(id, arr, idKey, childrenKey)?.[resultKey];\r\n}\r\n\r\n/**\r\n * 从服务端返回的已选 id 数组里，提取出\r\n * 1. 叶子节点\r\n * 2. 所有子节点都被选中的父节点\r\n * 其余父节点一律丢弃（由前端 Tree 自动算半选）\r\n *\r\n * @param {Array}  treeData     完整树\r\n * @param {Array}  selectedKeys 后端给的选中 id 数组\r\n * @param {String} idKey        节点唯一字段\r\n * @param {String} childrenKey  子节点字段\r\n * @returns {{checked: string[], halfChecked: string[]}}\r\n */\r\nexport function extractFullyCheckedKeys(treeData, selectedKeys, idKey = \"id\", childrenKey = \"children\") {\r\n    const selectedSet = new Set(selectedKeys);\r\n    const checked = new Set();\r\n    const halfChecked = new Set();\r\n\r\n    /* 返回值含义\r\n        0 - 未选中\r\n        1 - 半选\r\n        2 - 全选\r\n        */\r\n    function dfs(node) {\r\n        const nodeId = node[idKey];\r\n        const children = node[childrenKey] || [];\r\n\r\n        // 叶子\r\n        if (!children.length) {\r\n            if (selectedSet.has(nodeId)) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            return 0;\r\n        }\r\n\r\n        // 非叶子\r\n        let allChecked = true;\r\n        let someChecked = false;\r\n\r\n        children.forEach((child) => {\r\n            const childState = dfs(child);\r\n            if (childState !== 2) allChecked = false;\r\n            if (childState >= 1) someChecked = true;\r\n        });\r\n\r\n        // 当前节点本身在 selectedKeys 里，但子节点未全选 → 只能算半选\r\n        if (selectedSet.has(nodeId)) {\r\n            if (allChecked) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n\r\n        // 当前节点不在 selectedKeys 里，看子节点\r\n        if (allChecked) {\r\n            checked.add(nodeId);\r\n            return 2;\r\n        }\r\n        if (someChecked) {\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n        return 0;\r\n    }\r\n\r\n    treeData.forEach(dfs);\r\n    return {\r\n        checked: [...checked],\r\n        halfChecked: [...halfChecked]\r\n    };\r\n}\r\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"tree.cjs","sources":["../src/source/tree.js"],"sourcesContent":["/**\r\n * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} data - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表\r\n */\r\nexport function nestedTree2IdMap(data, idKey = \"id\", childrenKey = \"children\") {\r\n    const retObj = {};\r\n    function fn(nodes) {\r\n        if (Array.isArray(nodes) && nodes.length > 0) {\r\n            nodes.forEach((node) => {\r\n                retObj[node[idKey]] = { ...node };\r\n                retObj[node[idKey]][childrenKey] = null;\r\n\r\n                fn(node[childrenKey]);\r\n            });\r\n        }\r\n    }\r\n    fn(data);\r\n    return retObj;\r\n}\r\n\r\n/**\r\n * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）\r\n * @param {number | string} [parentId=0] - 根节点标识值\r\n * @param {Object} [opts] - 字段映射配置\r\n * @param {string} [opts.idKey='id'] - 节点主键\r\n * @param {string} [opts.parentKey='parentId'] - 父节点外键\r\n * @param {string} [opts.childrenKey='children'] - 存放子节点的字段\r\n * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林\r\n */\r\nexport function flatCompleteTree2NestedTree(nodes, parentId = 0, { idKey = \"id\", parentKey = \"parentId\", childrenKey = \"children\" } = {}) {\r\n    const map = new Map(); // id -> node\r\n    const items = []; // 多根森林\r\n\r\n    // 1. 初始化：保证每个节点都有 children，并存入 map\r\n    for (const item of nodes) {\r\n        const node = { ...item, [childrenKey]: [] };\r\n        map.set(item[idKey], node);\r\n    }\r\n\r\n    // 2. 建立父子关系\r\n    for (const item of nodes) {\r\n        const node = map.get(item[idKey]);\r\n        const parentIdVal = item[parentKey];\r\n\r\n        if (parentIdVal === parentId) {\r\n            // 根层\r\n            items.push(node);\r\n        } else {\r\n            // 非根层：找到父节点，把自己挂上去\r\n            const parent = map.get(parentIdVal);\r\n            if (parent) parent[childrenKey].push(node);\r\n            // 如果 parent 不存在，说明数据不完整，可自定义处理\r\n        }\r\n    }\r\n\r\n    return items;\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {T | undefined} 找到的节点；未找到返回 `undefined`\r\n */\r\nexport function findTreeNodeById(id, arr, idKey = \"id\", childrenKey = \"children\") {\r\n    if (Array.isArray(arr) && arr.length > 0) {\r\n        for (let i = 0; i < arr.length; i++) {\r\n            const item = arr[i];\r\n            if (item[idKey]?.toString() === id?.toString()) {\r\n                return item;\r\n            } else if (Array.isArray(item[childrenKey]) && item[childrenKey].length > 0) {\r\n                const result = findTreeNodeById(id, item[childrenKey], idKey, childrenKey);\r\n                if (result) {\r\n                    return result;\r\n                }\r\n            }\r\n        }\r\n    }\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点，并返回其指定属性值。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [resultKey='name'] - 需要返回的字段\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {any} 找到的值；未找到返回 `undefined`\r\n */\r\nexport function findObjAttrValueById(id, arr, resultKey = \"name\", idKey = \"id\", childrenKey = \"children\") {\r\n    return findTreeNodeById(id, arr, idKey, childrenKey)?.[resultKey];\r\n}\r\n\r\n/**\r\n * 从服务端返回的已选 id 数组里，提取出\r\n * 1. 叶子节点\r\n * 2. 所有子节点都被选中的父节点\r\n * 其余父节点一律丢弃（由前端 Tree 自动算半选）\r\n *\r\n * @param {Array}  treeData     完整树\r\n * @param {Array}  selectedKeys 后端给的选中 id 数组\r\n * @param {String} idKey        节点唯一字段\r\n * @param {String} childrenKey  子节点字段\r\n * @returns {{checked: string[], halfChecked: string[]}}\r\n */\r\nexport function extractFullyCheckedKeys(treeData, selectedKeys, idKey = \"id\", childrenKey = \"children\") {\r\n    const selectedSet = new Set(selectedKeys);\r\n    const checked = new Set();\r\n    const halfChecked = new Set();\r\n\r\n    /* 返回值含义\r\n        0 - 未选中\r\n        1 - 半选\r\n        2 - 全选\r\n        */\r\n    function dfs(node) {\r\n        const nodeId = node[idKey];\r\n        const children = node[childrenKey] || [];\r\n\r\n        // 叶子\r\n        if (!children.length) {\r\n            if (selectedSet.has(nodeId)) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            return 0;\r\n        }\r\n\r\n        // 非叶子\r\n        let allChecked = true;\r\n        let someChecked = false;\r\n\r\n        children.forEach((child) => {\r\n            const childState = dfs(child);\r\n            if (childState !== 2) allChecked = false;\r\n            if (childState >= 1) someChecked = true;\r\n        });\r\n\r\n        // 当前节点本身在 selectedKeys 里，但子节点未全选 → 只能算半选\r\n        if (selectedSet.has(nodeId)) {\r\n            if (allChecked) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n\r\n        // 当前节点不在 selectedKeys 里，看子节点\r\n        if (allChecked) {\r\n            checked.add(nodeId);\r\n            return 2;\r\n        }\r\n        if (someChecked) {\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n        return 0;\r\n    }\r\n\r\n    treeData.forEach(dfs);\r\n    return {\r\n        checked: [...checked],\r\n        halfChecked: [...halfChecked]\r\n    };\r\n}\r\n\r\n/**\r\n * 在树形结构中查找目标节点的完整路径（从根节点到目标节点，含目标节点自身）。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} nodes - 树形结构森林（支持多根）\r\n * @param {any} targetValue - 目标节点的 key 值\r\n * @param {string} [key='id'] - 节点唯一标识字段\r\n * @param {string} [parentKey='pid'] - 父节点标识字段（指向父节点的 key 值）\r\n * @param {string} [childrenKey='children'] - 子节点数组字段\r\n * @returns {T[]} 从根到目标节点的路径数组；未找到返回空数组\r\n *\r\n * @example\r\n * const tree = [\r\n *   { id: 1, pid: null, children: [\r\n *     { id: 2, pid: 1, children: [\r\n *       { id: 3, pid: 2 }\r\n *     ]}\r\n *   ]}\r\n * ];\r\n * findTreeNodePath(tree, 3); // [{id:1, ...}, {id:2, ...}, {id:3, ...}]\r\n */\r\nexport function findTreeNodePath(nodes, targetValue, key = \"id\", parentKey = \"pid\", childrenKey = \"children\") {\r\n    if (!Array.isArray(nodes) || nodes.length === 0 || targetValue == null) {\r\n        return [];\r\n    }\r\n\r\n    // 1. 建立节点索引\r\n    const index = new Map();\r\n    const stack = [...nodes];\r\n\r\n    while (stack.length) {\r\n        const node = stack.pop();\r\n        if (!node || typeof node !== \"object\") continue;\r\n\r\n        index.set(node[key], node);\r\n\r\n        const children = node[childrenKey];\r\n        if (Array.isArray(children)) {\r\n            stack.push(...children);\r\n        }\r\n    }\r\n\r\n    // 2. 回溯路径（防循环引用）\r\n    const path = [];\r\n    const visited = new Set();\r\n    let cur = index.get(targetValue);\r\n\r\n    while (cur && !visited.has(cur[key])) {\r\n        visited.add(cur[key]);\r\n        path.push(cur);\r\n\r\n        const parentValue = cur[parentKey];\r\n        cur = parentValue != null ? index.get(parentValue) : undefined;\r\n    }\r\n\r\n    return path.reverse();\r\n}\r\n"],"names":[],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,gBAAgB,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE;AAC/E,IAAI,MAAM,MAAM,GAAG,EAAE,CAAC;AACtB,IAAI,SAAS,EAAE,CAAC,KAAK,EAAE;AACvB,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE;AACtD,YAAY,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK;AACpC,gBAAgB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;AAClD,gBAAgB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;AACxD;AACA,gBAAgB,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;AACtC,YAAY,CAAC,CAAC,CAAC;AACf,QAAQ,CAAC;AACT,IAAI,CAAC;AACL,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AACb,IAAI,OAAO,MAAM,CAAC;AAClB,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,2BAA2B,CAAC,KAAK,EAAE,QAAQ,GAAG,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,EAAE,SAAS,GAAG,UAAU,EAAE,WAAW,GAAG,UAAU,EAAE,GAAG,EAAE,EAAE;AAC1I,IAAI,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;AAC1B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;AACrB;AACA;AACA,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;AAC9B,QAAQ,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC,WAAW,GAAG,EAAE,EAAE,CAAC;AACpD,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AACnC,IAAI,CAAC;AACL;AACA;AACA,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;AAC9B,QAAQ,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1C,QAAQ,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;AAC5C;AACA,QAAQ,IAAI,WAAW,KAAK,QAAQ,EAAE;AACtC;AACA,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,QAAQ,CAAC,MAAM;AACf;AACA,YAAY,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AAChD,YAAY,IAAI,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvD;AACA,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA,IAAI,OAAO,KAAK,CAAC;AACjB,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE;AAClF,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE;AAC9C,QAAQ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;AAC7C,YAAY,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAChC,YAAY,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE;AAC5D,gBAAgB,OAAO,IAAI,CAAC;AAC5B,YAAY,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE;AACzF,gBAAgB,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;AAC3F,gBAAgB,IAAI,MAAM,EAAE;AAC5B,oBAAoB,OAAO,MAAM,CAAC;AAClC,gBAAgB,CAAC;AACjB,YAAY,CAAC;AACb,QAAQ,CAAC;AACT,IAAI,CAAC;AACL,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,oBAAoB,CAAC,EAAE,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE;AAC1G,IAAI,OAAO,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,CAAC,GAAG,SAAS,CAAC,CAAC;AACtE,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,uBAAuB,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,GAAG,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE;AACxG,IAAI,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;AAC9C,IAAI,MAAM,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;AAC9B,IAAI,MAAM,WAAW,GAAG,IAAI,GAAG,EAAE,CAAC;AAClC;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,SAAS,GAAG,CAAC,IAAI,EAAE;AACvB,QAAQ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AACnC,QAAQ,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;AACjD;AACA;AACA,QAAQ,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE;AAC9B,YAAY,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE;AACzC,gBAAgB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,gBAAgB,OAAO,CAAC,CAAC;AACzB,YAAY,CAAC;AACb,YAAY,OAAO,CAAC,CAAC;AACrB,QAAQ,CAAC;AACT;AACA;AACA,QAAQ,IAAI,UAAU,GAAG,IAAI,CAAC;AAC9B,QAAQ,IAAI,WAAW,GAAG,KAAK,CAAC;AAChC;AACA,QAAQ,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK;AACpC,YAAY,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;AAC1C,YAAY,IAAI,UAAU,KAAK,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC;AACrD,YAAY,IAAI,UAAU,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;AACpD,QAAQ,CAAC,CAAC,CAAC;AACX;AACA;AACA,QAAQ,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE;AACrC,YAAY,IAAI,UAAU,EAAE;AAC5B,gBAAgB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,gBAAgB,OAAO,CAAC,CAAC;AACzB,YAAY,CAAC;AACb,YAAY,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,YAAY,OAAO,CAAC,CAAC;AACrB,QAAQ,CAAC;AACT;AACA;AACA,QAAQ,IAAI,UAAU,EAAE;AACxB,YAAY,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAChC,YAAY,OAAO,CAAC,CAAC;AACrB,QAAQ,CAAC;AACT,QAAQ,IAAI,WAAW,EAAE;AACzB,YAAY,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,YAAY,OAAO,CAAC,CAAC;AACrB,QAAQ,CAAC;AACT,QAAQ,OAAO,CAAC,CAAC;AACjB,IAAI,CAAC;AACL;AACA,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAC1B,IAAI,OAAO;AACX,QAAQ,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;AAC7B,QAAQ,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC;AACrC,KAAK,CAAC;AACN,CAAC;AACD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAAS,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,IAAI,EAAE,SAAS,GAAG,KAAK,EAAE,WAAW,GAAG,UAAU,EAAE;AAC9G,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,IAAI,IAAI,EAAE;AAC5E,QAAQ,OAAO,EAAE,CAAC;AAClB,IAAI,CAAC;AACL;AACA;AACA,IAAI,MAAM,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;AAC5B,IAAI,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;AAC7B;AACA,IAAI,OAAO,KAAK,CAAC,MAAM,EAAE;AACzB,QAAQ,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;AACjC,QAAQ,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,SAAS;AACxD;AACA,QAAQ,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;AACnC;AACA,QAAQ,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;AAC3C,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;AACrC,YAAY,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;AACpC,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;AACpB,IAAI,MAAM,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;AAC9B,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AACrC;AACA,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE;AAC1C,QAAQ,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC9B,QAAQ,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvB;AACA,QAAQ,MAAM,WAAW,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;AAC3C,QAAQ,GAAG,GAAG,WAAW,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;AACvE,IAAI,CAAC;AACL;AACA,IAAI,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;AAC1B;;;;;;;;;"}

package/dist/tree.js

@@ -177,7 +177,65 @@ 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();
 }
 
-export { extractFullyCheckedKeys, findObjAttrValueById, findTreeNodeById, flatCompleteTree2NestedTree, nestedTree2IdMap };
+export { extractFullyCheckedKeys, findObjAttrValueById, findTreeNodeById, findTreeNodePath, flatCompleteTree2NestedTree, nestedTree2IdMap };
 //# sourceMappingURL=tree.js.map

package/dist/tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"tree.js","sources":["../src/source/tree.js"],"sourcesContent":["/**\r\n * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} data - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表\r\n */\r\nexport function nestedTree2IdMap(data, idKey = \"id\", childrenKey = \"children\") {\r\n    const retObj = {};\r\n    function fn(nodes) {\r\n        if (Array.isArray(nodes) && nodes.length > 0) {\r\n            nodes.forEach((node) => {\r\n                retObj[node[idKey]] = { ...node };\r\n                retObj[node[idKey]][childrenKey] = null;\r\n\r\n                fn(node[childrenKey]);\r\n            });\r\n        }\r\n    }\r\n    fn(data);\r\n    return retObj;\r\n}\r\n\r\n/**\r\n * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）\r\n * @param {number | string} [parentId=0] - 根节点标识值\r\n * @param {Object} [opts] - 字段映射配置\r\n * @param {string} [opts.idKey='id'] - 节点主键\r\n * @param {string} [opts.parentKey='parentId'] - 父节点外键\r\n * @param {string} [opts.childrenKey='children'] - 存放子节点的字段\r\n * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林\r\n */\r\nexport function flatCompleteTree2NestedTree(nodes, parentId = 0, { idKey = \"id\", parentKey = \"parentId\", childrenKey = \"children\" } = {}) {\r\n    const map = new Map(); // id -> node\r\n    const items = []; // 多根森林\r\n\r\n    // 1. 初始化：保证每个节点都有 children，并存入 map\r\n    for (const item of nodes) {\r\n        const node = { ...item, [childrenKey]: [] };\r\n        map.set(item[idKey], node);\r\n    }\r\n\r\n    // 2. 建立父子关系\r\n    for (const item of nodes) {\r\n        const node = map.get(item[idKey]);\r\n        const parentIdVal = item[parentKey];\r\n\r\n        if (parentIdVal === parentId) {\r\n            // 根层\r\n            items.push(node);\r\n        } else {\r\n            // 非根层：找到父节点，把自己挂上去\r\n            const parent = map.get(parentIdVal);\r\n            if (parent) parent[childrenKey].push(node);\r\n            // 如果 parent 不存在，说明数据不完整，可自定义处理\r\n        }\r\n    }\r\n\r\n    return items;\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {T | undefined} 找到的节点；未找到返回 `undefined`\r\n */\r\nexport function findTreeNodeById(id, arr, idKey = \"id\", childrenKey = \"children\") {\r\n    if (Array.isArray(arr) && arr.length > 0) {\r\n        for (let i = 0; i < arr.length; i++) {\r\n            const item = arr[i];\r\n            if (item[idKey]?.toString() === id?.toString()) {\r\n                return item;\r\n            } else if (Array.isArray(item[childrenKey]) && item[childrenKey].length > 0) {\r\n                const result = findTreeNodeById(id, item[childrenKey], idKey, childrenKey);\r\n                if (result) {\r\n                    return result;\r\n                }\r\n            }\r\n        }\r\n    }\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点，并返回其指定属性值。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [resultKey='name'] - 需要返回的字段\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {any} 找到的值；未找到返回 `undefined`\r\n */\r\nexport function findObjAttrValueById(id, arr, resultKey = \"name\", idKey = \"id\", childrenKey = \"children\") {\r\n    return findTreeNodeById(id, arr, idKey, childrenKey)?.[resultKey];\r\n}\r\n\r\n/**\r\n * 从服务端返回的已选 id 数组里，提取出\r\n * 1. 叶子节点\r\n * 2. 所有子节点都被选中的父节点\r\n * 其余父节点一律丢弃（由前端 Tree 自动算半选）\r\n *\r\n * @param {Array}  treeData     完整树\r\n * @param {Array}  selectedKeys 后端给的选中 id 数组\r\n * @param {String} idKey        节点唯一字段\r\n * @param {String} childrenKey  子节点字段\r\n * @returns {{checked: string[], halfChecked: string[]}}\r\n */\r\nexport function extractFullyCheckedKeys(treeData, selectedKeys, idKey = \"id\", childrenKey = \"children\") {\r\n    const selectedSet = new Set(selectedKeys);\r\n    const checked = new Set();\r\n    const halfChecked = new Set();\r\n\r\n    /* 返回值含义\r\n        0 - 未选中\r\n        1 - 半选\r\n        2 - 全选\r\n        */\r\n    function dfs(node) {\r\n        const nodeId = node[idKey];\r\n        const children = node[childrenKey] || [];\r\n\r\n        // 叶子\r\n        if (!children.length) {\r\n            if (selectedSet.has(nodeId)) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            return 0;\r\n        }\r\n\r\n        // 非叶子\r\n        let allChecked = true;\r\n        let someChecked = false;\r\n\r\n        children.forEach((child) => {\r\n            const childState = dfs(child);\r\n            if (childState !== 2) allChecked = false;\r\n            if (childState >= 1) someChecked = true;\r\n        });\r\n\r\n        // 当前节点本身在 selectedKeys 里，但子节点未全选 → 只能算半选\r\n        if (selectedSet.has(nodeId)) {\r\n            if (allChecked) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n\r\n        // 当前节点不在 selectedKeys 里，看子节点\r\n        if (allChecked) {\r\n            checked.add(nodeId);\r\n            return 2;\r\n        }\r\n        if (someChecked) {\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n        return 0;\r\n    }\r\n\r\n    treeData.forEach(dfs);\r\n    return {\r\n        checked: [...checked],\r\n        halfChecked: [...halfChecked]\r\n    };\r\n}\r\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"tree.js","sources":["../src/source/tree.js"],"sourcesContent":["/**\r\n * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} data - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表\r\n */\r\nexport function nestedTree2IdMap(data, idKey = \"id\", childrenKey = \"children\") {\r\n    const retObj = {};\r\n    function fn(nodes) {\r\n        if (Array.isArray(nodes) && nodes.length > 0) {\r\n            nodes.forEach((node) => {\r\n                retObj[node[idKey]] = { ...node };\r\n                retObj[node[idKey]][childrenKey] = null;\r\n\r\n                fn(node[childrenKey]);\r\n            });\r\n        }\r\n    }\r\n    fn(data);\r\n    return retObj;\r\n}\r\n\r\n/**\r\n * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）\r\n * @param {number | string} [parentId=0] - 根节点标识值\r\n * @param {Object} [opts] - 字段映射配置\r\n * @param {string} [opts.idKey='id'] - 节点主键\r\n * @param {string} [opts.parentKey='parentId'] - 父节点外键\r\n * @param {string} [opts.childrenKey='children'] - 存放子节点的字段\r\n * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林\r\n */\r\nexport function flatCompleteTree2NestedTree(nodes, parentId = 0, { idKey = \"id\", parentKey = \"parentId\", childrenKey = \"children\" } = {}) {\r\n    const map = new Map(); // id -> node\r\n    const items = []; // 多根森林\r\n\r\n    // 1. 初始化：保证每个节点都有 children，并存入 map\r\n    for (const item of nodes) {\r\n        const node = { ...item, [childrenKey]: [] };\r\n        map.set(item[idKey], node);\r\n    }\r\n\r\n    // 2. 建立父子关系\r\n    for (const item of nodes) {\r\n        const node = map.get(item[idKey]);\r\n        const parentIdVal = item[parentKey];\r\n\r\n        if (parentIdVal === parentId) {\r\n            // 根层\r\n            items.push(node);\r\n        } else {\r\n            // 非根层：找到父节点，把自己挂上去\r\n            const parent = map.get(parentIdVal);\r\n            if (parent) parent[childrenKey].push(node);\r\n            // 如果 parent 不存在，说明数据不完整，可自定义处理\r\n        }\r\n    }\r\n\r\n    return items;\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {T | undefined} 找到的节点；未找到返回 `undefined`\r\n */\r\nexport function findTreeNodeById(id, arr, idKey = \"id\", childrenKey = \"children\") {\r\n    if (Array.isArray(arr) && arr.length > 0) {\r\n        for (let i = 0; i < arr.length; i++) {\r\n            const item = arr[i];\r\n            if (item[idKey]?.toString() === id?.toString()) {\r\n                return item;\r\n            } else if (Array.isArray(item[childrenKey]) && item[childrenKey].length > 0) {\r\n                const result = findTreeNodeById(id, item[childrenKey], idKey, childrenKey);\r\n                if (result) {\r\n                    return result;\r\n                }\r\n            }\r\n        }\r\n    }\r\n}\r\n\r\n/**\r\n * 在嵌套树中按 `id` 递归查找节点，并返回其指定属性值。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {string | number} id - 要查找的 id\r\n * @param {T[]} arr - 嵌套树森林\r\n * @param {string} [resultKey='name'] - 需要返回的字段\r\n * @param {string} [idKey='id'] - 主键字段\r\n * @param {string} [childrenKey='children'] - 子节点字段\r\n * @returns {any} 找到的值；未找到返回 `undefined`\r\n */\r\nexport function findObjAttrValueById(id, arr, resultKey = \"name\", idKey = \"id\", childrenKey = \"children\") {\r\n    return findTreeNodeById(id, arr, idKey, childrenKey)?.[resultKey];\r\n}\r\n\r\n/**\r\n * 从服务端返回的已选 id 数组里，提取出\r\n * 1. 叶子节点\r\n * 2. 所有子节点都被选中的父节点\r\n * 其余父节点一律丢弃（由前端 Tree 自动算半选）\r\n *\r\n * @param {Array}  treeData     完整树\r\n * @param {Array}  selectedKeys 后端给的选中 id 数组\r\n * @param {String} idKey        节点唯一字段\r\n * @param {String} childrenKey  子节点字段\r\n * @returns {{checked: string[], halfChecked: string[]}}\r\n */\r\nexport function extractFullyCheckedKeys(treeData, selectedKeys, idKey = \"id\", childrenKey = \"children\") {\r\n    const selectedSet = new Set(selectedKeys);\r\n    const checked = new Set();\r\n    const halfChecked = new Set();\r\n\r\n    /* 返回值含义\r\n        0 - 未选中\r\n        1 - 半选\r\n        2 - 全选\r\n        */\r\n    function dfs(node) {\r\n        const nodeId = node[idKey];\r\n        const children = node[childrenKey] || [];\r\n\r\n        // 叶子\r\n        if (!children.length) {\r\n            if (selectedSet.has(nodeId)) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            return 0;\r\n        }\r\n\r\n        // 非叶子\r\n        let allChecked = true;\r\n        let someChecked = false;\r\n\r\n        children.forEach((child) => {\r\n            const childState = dfs(child);\r\n            if (childState !== 2) allChecked = false;\r\n            if (childState >= 1) someChecked = true;\r\n        });\r\n\r\n        // 当前节点本身在 selectedKeys 里，但子节点未全选 → 只能算半选\r\n        if (selectedSet.has(nodeId)) {\r\n            if (allChecked) {\r\n                checked.add(nodeId);\r\n                return 2;\r\n            }\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n\r\n        // 当前节点不在 selectedKeys 里，看子节点\r\n        if (allChecked) {\r\n            checked.add(nodeId);\r\n            return 2;\r\n        }\r\n        if (someChecked) {\r\n            halfChecked.add(nodeId);\r\n            return 1;\r\n        }\r\n        return 0;\r\n    }\r\n\r\n    treeData.forEach(dfs);\r\n    return {\r\n        checked: [...checked],\r\n        halfChecked: [...halfChecked]\r\n    };\r\n}\r\n\r\n/**\r\n * 在树形结构中查找目标节点的完整路径（从根节点到目标节点，含目标节点自身）。\r\n *\r\n * @template T extends Record<PropertyKey, any>\r\n * @param {T[]} nodes - 树形结构森林（支持多根）\r\n * @param {any} targetValue - 目标节点的 key 值\r\n * @param {string} [key='id'] - 节点唯一标识字段\r\n * @param {string} [parentKey='pid'] - 父节点标识字段（指向父节点的 key 值）\r\n * @param {string} [childrenKey='children'] - 子节点数组字段\r\n * @returns {T[]} 从根到目标节点的路径数组；未找到返回空数组\r\n *\r\n * @example\r\n * const tree = [\r\n *   { id: 1, pid: null, children: [\r\n *     { id: 2, pid: 1, children: [\r\n *       { id: 3, pid: 2 }\r\n *     ]}\r\n *   ]}\r\n * ];\r\n * findTreeNodePath(tree, 3); // [{id:1, ...}, {id:2, ...}, {id:3, ...}]\r\n */\r\nexport function findTreeNodePath(nodes, targetValue, key = \"id\", parentKey = \"pid\", childrenKey = \"children\") {\r\n    if (!Array.isArray(nodes) || nodes.length === 0 || targetValue == null) {\r\n        return [];\r\n    }\r\n\r\n    // 1. 建立节点索引\r\n    const index = new Map();\r\n    const stack = [...nodes];\r\n\r\n    while (stack.length) {\r\n        const node = stack.pop();\r\n        if (!node || typeof node !== \"object\") continue;\r\n\r\n        index.set(node[key], node);\r\n\r\n        const children = node[childrenKey];\r\n        if (Array.isArray(children)) {\r\n            stack.push(...children);\r\n        }\r\n    }\r\n\r\n    // 2. 回溯路径（防循环引用）\r\n    const path = [];\r\n    const visited = new Set();\r\n    let cur = index.get(targetValue);\r\n\r\n    while (cur && !visited.has(cur[key])) {\r\n        visited.add(cur[key]);\r\n        path.push(cur);\r\n\r\n        const parentValue = cur[parentKey];\r\n        cur = parentValue != null ? index.get(parentValue) : undefined;\r\n    }\r\n\r\n    return path.reverse();\r\n}\r\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2bei4-utils",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "🧰 零依赖、ESM 的 JS 业务工具箱：数组乱序/深浅克隆、防抖节流、URL/query 解析、Date/时长格式化、随机汉字/字母、文件下载、事件总线、UUID/分布式短 ID、树结构互转等 40+ 常用函数 & 类，Tree-Shaking 友好。",
   "private": false,
   "type": "module",

package/types/browser.d.ts

@@ -33,6 +33,15 @@ declare function getAllSearchParams(): Record<string, string>;
  * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`
  */
 declare function getSearchParam(key: string): string | undefined;
+declare namespace fullscreenHelper {
+    function requestFullscreen(element: Element): Promise<void> | undefined;
+    function exitFullscreen(): Promise<void> | undefined;
+    function getFullscreenElement(): Element | null;
+    function isFullscreen(): boolean;
+    function isFullscreenEnabled(): boolean;
+    function toggleFullscreen(element: Element): Promise<void> | undefined;
+    function onFullscreenChange(callback: Function): Function;
+}
 /**
  * 视口尺寸对象。
  */
@@ -47,5 +56,5 @@ type ViewportDimensions = {
     h: number;
 };
 
-export { getAllSearchParams, getSearchParam, getViewportSize };
+export { fullscreenHelper, getAllSearchParams, getSearchParam, getViewportSize };
 export type { ViewportDimensions };

package/types/index.d.ts

@@ -321,6 +321,15 @@ declare function getAllSearchParams(): Record<string, string>;
  * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`
  */
 declare function getSearchParam(key: string): string | undefined;
+declare namespace fullscreenHelper {
+    function requestFullscreen(element: Element): Promise<void> | undefined;
+    function exitFullscreen(): Promise<void> | undefined;
+    function getFullscreenElement(): Element | null;
+    function isFullscreen(): boolean;
+    function isFullscreenEnabled(): boolean;
+    function toggleFullscreen(element: Element): Promise<void> | undefined;
+    function onFullscreenChange(callback: Function): Function;
+}
 /**
  * 视口尺寸对象。
  */
@@ -981,5 +990,27 @@ declare function extractFullyCheckedKeys(treeData: any[], selectedKeys: any[], i
     checked: string[];
     halfChecked: string[];
 };
+/**
+ * 在树形结构中查找目标节点的完整路径（从根节点到目标节点，含目标节点自身）。
+ *
+ * @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, ...}]
+ */
+declare function findTreeNodePath<T>(nodes: T[], targetValue: any, key?: string, parentKey?: string, childrenKey?: string): T[];
 
-export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, findTreeNodeById, flatCompleteTree2NestedTree, formatTimeForLocale, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, handleDbMenuItems, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, second2Duration, second2DurationMaxDay, second2DurationMaxHour, shuffle, throttle, toDate };
+export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, findTreeNodeById, findTreeNodePath, flatCompleteTree2NestedTree, formatTimeForLocale, fullscreenHelper, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, handleDbMenuItems, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, second2Duration, second2DurationMaxDay, second2DurationMaxHour, shuffle, throttle, toDate };