@zat-design/sisyphus-react 4.5.9 → 4.5.10-beta.1

package/es/ProLayout/components/TabsManager/hooks/useTabsUrlSync.js

@@ -0,0 +1,295 @@
+import { createContext, useContext, useEffect, useRef, useState } from 'react';
+import * as ReactRouterDom from 'react-router-dom';
+import { canOpenAsTab, flattenMenuData, getCurrentTabUrl, getMenuRoute, getTabUrlPathname, normalizeTabUrl } from "../utils";
+import { subscribeHistoryLocation } from "../utils/historyObserver";
+const getOptionalRouterContext = exportName => {
+  const descriptor = Object.getOwnPropertyDescriptor(ReactRouterDom, exportName);
+  return descriptor ? Reflect.get(ReactRouterDom, exportName) : undefined;
+};
+const OptionalNavigationContext = getOptionalRouterContext('UNSAFE_NavigationContext') || /*#__PURE__*/createContext(null);
+
+// Data Router 从 react-router-dom 6.4 起提供；保留 6.0-6.3 peer 兼容。
+const OptionalDataRouterContext = getOptionalRouterContext('UNSAFE_DataRouterContext') || /*#__PURE__*/createContext(null);
+const getDataRouterUrl = (url, basename) => {
+  if (!basename || basename === '/') return url;
+  const pathname = getTabUrlPathname(url);
+  if (!pathname) return url;
+  const normalizedBasename = `/${basename.replace(/^\/+|\/+$/g, '')}`;
+  const lowerPathname = pathname.toLowerCase();
+  const lowerBasename = normalizedBasename.toLowerCase();
+  const suffix = url.slice(pathname.length);
+  if (lowerPathname === lowerBasename) return `/${suffix}`;
+  if (lowerPathname.startsWith(`${lowerBasename}/`)) {
+    return `${pathname.slice(normalizedBasename.length)}${suffix}`;
+  }
+  return url;
+};
+const isCurrentDataRouterNavigation = (currentUrl, dataRouterContext) => {
+  const navigationLocation = dataRouterContext?.router.state?.navigation?.location;
+  if (!navigationLocation) return false;
+  const navigationUrl = `${navigationLocation.pathname}${navigationLocation.search ?? ''}${navigationLocation.hash ?? ''}`;
+  return navigationUrl === currentUrl || navigationUrl === getDataRouterUrl(currentUrl, dataRouterContext?.basename);
+};
+const isSameOrNestedPath = (basePathname, currentPathname) => {
+  if (!basePathname || !currentPathname) return false;
+  const normalizedBase = basePathname === '/' ? '/' : basePathname.replace(/\/$/, '');
+  return currentPathname === normalizedBase || normalizedBase !== '/' && currentPathname.startsWith(`${normalizedBase}/`);
+};
+const getSourceMenus = dataSource => {
+  if (!dataSource || !('menus' in dataSource) || !Array.isArray(dataSource.menus)) return [];
+  return flattenMenuData(dataSource.menus);
+};
+const createPushHistoryState = currentState => {
+  if (!currentState || typeof currentState !== 'object' || Array.isArray(currentState)) {
+    return currentState;
+  }
+  const nextState = {
+    ...currentState
+  };
+  const currentIndex = nextState.idx;
+  const currentKey = nextState.key;
+  const isReactRouterState = 'usr' in nextState && typeof currentIndex === 'number' && typeof currentKey === 'string';
+  if (isReactRouterState) {
+    nextState.idx = currentIndex + 1;
+    nextState.key = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+  }
+  return nextState;
+};
+const getRouterLocationState = currentState => {
+  if (!currentState || typeof currentState !== 'object' || Array.isArray(currentState)) {
+    return currentState;
+  }
+  const state = currentState;
+  if (typeof state.idx !== 'number') return currentState;
+  return 'usr' in state ? state.usr : null;
+};
+/**
+ * 维护浏览器 location 与活动页签 URL 的双向同步。
+ * 未开启 config.urlSync 时不安装任何 History 监听或写入逻辑。
+ */
+export const useTabsUrlSync = ({
+  config,
+  dataSource,
+  state,
+  isInitialized,
+  addTab,
+  switchTab,
+  updateTabUrl,
+  rollbackTabActivation,
+  interactionSequence
+}) => {
+  const navigationContext = useContext(OptionalNavigationContext);
+  const dataRouterContext = useContext(OptionalDataRouterContext);
+  const navigator = navigationContext?.navigator;
+  const enabled = config.urlSync === true || typeof config.urlSync === 'object' && config.urlSync !== null;
+  const historyMode = typeof config.urlSync === 'object' ? config.urlSync.history || 'replace' : 'replace';
+  const bootstrappedRef = useRef(false);
+  const writingUrlRef = useRef(false);
+  const preserveUrlInteractionRef = useRef(null);
+  const locationSequenceRef = useRef(0);
+  const handledLocationSequenceRef = useRef(undefined);
+  const committedActiveKeyRef = useRef(state.activeKey);
+  const committedTabIdsRef = useRef(new Set(state.tabsList.map(tab => tab.id)));
+  const navigationAttemptRef = useRef(0);
+  const pendingDataNavigationRef = useRef(false);
+  const pendingDataNavigationUrlRef = useRef(null);
+  const ignoredHistoryUrlRef = useRef(null);
+  const [locationChange, setLocationChange] = useState(() => ({
+    url: typeof window === 'undefined' ? '' : getCurrentTabUrl(),
+    source: 'initial',
+    sequence: 0
+  }));
+
+  // History API 不会为 pushState/replaceState 触发 popstate，在挂载期间补齐通知。
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return undefined;
+    return subscribeHistoryLocation(source => {
+      if (writingUrlRef.current) return;
+      const currentUrl = getCurrentTabUrl();
+      if (ignoredHistoryUrlRef.current === currentUrl) {
+        ignoredHistoryUrlRef.current = null;
+        return;
+      }
+      const pendingDataNavigation = pendingDataNavigationRef.current;
+      const pendingDataNavigationUrl = pendingDataNavigationUrlRef.current;
+      const isPendingDataNavigationCommit = pendingDataNavigation && (pendingDataNavigationUrl === currentUrl || isCurrentDataRouterNavigation(currentUrl, dataRouterContext));
+      if (!isPendingDataNavigationCommit) {
+        navigationAttemptRef.current += 1;
+      }
+      pendingDataNavigationRef.current = false;
+      pendingDataNavigationUrlRef.current = isPendingDataNavigationCommit ? currentUrl : null;
+      if (pendingDataNavigation && !isPendingDataNavigationCommit && dataRouterContext) {
+        ignoredHistoryUrlRef.current = currentUrl;
+        const cancellation = dataRouterContext.router.navigate(getDataRouterUrl(currentUrl, dataRouterContext.basename), {
+          replace: true,
+          state: getRouterLocationState(window.history.state)
+        });
+        void cancellation.finally(() => {
+          if (ignoredHistoryUrlRef.current === currentUrl) {
+            ignoredHistoryUrlRef.current = null;
+          }
+        });
+      }
+      preserveUrlInteractionRef.current = null;
+      locationSequenceRef.current += 1;
+      setLocationChange({
+        url: currentUrl,
+        source,
+        sequence: locationSequenceRef.current
+      });
+    });
+  }, [enabled, dataRouterContext]);
+
+  // URL -> Tabs：精确 URL 优先；同 pathname 视为当前页签内导航；
+  // 其次才按菜单 pathname 创建新页签。
+  useEffect(() => {
+    if (!enabled || !isInitialized || typeof window === 'undefined') return;
+    const currentUrl = normalizeTabUrl(locationChange.url);
+    if (!currentUrl) return;
+    if (handledLocationSequenceRef.current === locationChange.sequence) return;
+    const exactTab = state.tabsList.find(tab => normalizeTabUrl(tab.url) === currentUrl);
+    if (exactTab) {
+      handledLocationSequenceRef.current = locationChange.sequence;
+      bootstrappedRef.current = true;
+      preserveUrlInteractionRef.current = null;
+      if (state.activeKey !== exactTab.id) {
+        switchTab(exactTab.id);
+      }
+      return;
+    }
+    const currentPathname = getTabUrlPathname(currentUrl);
+    const sourceMenus = getSourceMenus(dataSource);
+    const activeTab = state.tabsList.find(tab => tab.id === state.activeKey);
+    const activeCode = activeTab?.menuItem?.code || activeTab?.code;
+    const activeSourceMenu = activeCode ? sourceMenus.find(item => item.code === activeCode) : undefined;
+    const activeMenuItem = activeSourceMenu || activeTab?.menuItem;
+    const activeBasePathname = activeMenuItem ? getTabUrlPathname(getMenuRoute(activeMenuItem)) : getTabUrlPathname(activeTab?.url);
+    const targetMenu = sourceMenus.map(item => ({
+      item,
+      pathname: getTabUrlPathname(getMenuRoute(item))
+    })).filter(entry => !!entry.pathname && isSameOrNestedPath(entry.pathname, currentPathname)).sort((left, right) => right.pathname.length - left.pathname.length)[0]?.item;
+    const targetBelongsToActiveMenu = !targetMenu || !!activeCode && targetMenu.code === activeCode;
+    if (activeTab && locationChange.source !== 'initial' && targetBelongsToActiveMenu && isSameOrNestedPath(activeBasePathname, currentPathname)) {
+      handledLocationSequenceRef.current = locationChange.sequence;
+      bootstrappedRef.current = true;
+      preserveUrlInteractionRef.current = null;
+      updateTabUrl(activeTab.id, currentUrl);
+      return;
+    }
+    if (targetMenu && canOpenAsTab(targetMenu)) {
+      handledLocationSequenceRef.current = locationChange.sequence;
+      bootstrappedRef.current = true;
+      preserveUrlInteractionRef.current = interactionSequence;
+      addTab({
+        ...targetMenu,
+        url: currentUrl,
+        redirectUrl: undefined
+      });
+      return;
+    }
+    if (!bootstrappedRef.current) {
+      bootstrappedRef.current = true;
+      preserveUrlInteractionRef.current = interactionSequence;
+      return;
+    }
+    if (activeTab && locationChange.source !== 'initial') {
+      handledLocationSequenceRef.current = locationChange.sequence;
+      preserveUrlInteractionRef.current = null;
+      navigationAttemptRef.current += 1;
+      updateTabUrl(activeTab.id, currentUrl);
+      return;
+    }
+    if (locationChange.source !== 'initial') {
+      handledLocationSequenceRef.current = locationChange.sequence;
+    }
+  }, [enabled, isInitialized, locationChange, state.tabsList, state.activeKey, dataSource, addTab, switchTab, updateTabUrl, interactionSequence]);
+
+  // Tabs -> URL：默认用 replace 避免切签堆积浏览器历史。
+  useEffect(() => {
+    if (!enabled || !isInitialized || !bootstrappedRef.current || typeof window === 'undefined') {
+      return;
+    }
+    const activeTab = state.tabsList.find(tab => tab.id === state.activeKey);
+    const targetUrl = normalizeTabUrl(activeTab?.url);
+    const commitActiveTab = () => {
+      committedActiveKeyRef.current = state.activeKey;
+      committedTabIdsRef.current = new Set(state.tabsList.map(tab => tab.id));
+    };
+    if (preserveUrlInteractionRef.current !== null) {
+      if (preserveUrlInteractionRef.current === interactionSequence) {
+        if (targetUrl === getCurrentTabUrl()) {
+          preserveUrlInteractionRef.current = null;
+        }
+        commitActiveTab();
+        return;
+      }
+      preserveUrlInteractionRef.current = null;
+    }
+    if (!targetUrl || targetUrl === getCurrentTabUrl()) {
+      const pendingNavigation = pendingDataNavigationRef.current;
+      navigationAttemptRef.current += 1;
+      pendingDataNavigationRef.current = false;
+      pendingDataNavigationUrlRef.current = null;
+      if (pendingNavigation && dataRouterContext) {
+        const cancellationUrl = getCurrentTabUrl();
+        ignoredHistoryUrlRef.current = cancellationUrl;
+        const cancellation = dataRouterContext.router.navigate(getDataRouterUrl(cancellationUrl, dataRouterContext.basename), {
+          replace: true,
+          state: getRouterLocationState(window.history.state)
+        });
+        void cancellation.finally(() => {
+          if (ignoredHistoryUrlRef.current === cancellationUrl) {
+            ignoredHistoryUrlRef.current = null;
+          }
+        });
+      }
+      commitActiveTab();
+      return;
+    }
+    handledLocationSequenceRef.current = locationChange.sequence;
+    const previousActiveKey = committedActiveKeyRef.current;
+    const attemptedActiveKey = state.activeKey;
+    const removeAttemptedTab = !committedTabIdsRef.current.has(attemptedActiveKey);
+    const navigationAttempt = navigationAttemptRef.current + 1;
+    navigationAttemptRef.current = navigationAttempt;
+    writingUrlRef.current = true;
+    try {
+      const routerState = getRouterLocationState(window.history.state);
+      if (dataRouterContext) {
+        const settleNavigation = () => {
+          if (navigationAttemptRef.current !== navigationAttempt) return;
+          const committedDataNavigationUrl = pendingDataNavigationUrlRef.current;
+          pendingDataNavigationRef.current = false;
+          pendingDataNavigationUrlRef.current = null;
+          const currentUrl = getCurrentTabUrl();
+          if (targetUrl === currentUrl || committedDataNavigationUrl === currentUrl) {
+            commitActiveTab();
+            return;
+          }
+          rollbackTabActivation(previousActiveKey, attemptedActiveKey, removeAttemptedTab);
+        };
+        pendingDataNavigationRef.current = true;
+        pendingDataNavigationUrlRef.current = targetUrl;
+        void dataRouterContext.router.navigate(getDataRouterUrl(targetUrl, dataRouterContext.basename), {
+          replace: historyMode === 'replace',
+          state: routerState
+        }).then(settleNavigation);
+      } else if (navigator) {
+        if (historyMode === 'push') {
+          navigator.push(targetUrl, routerState);
+        } else {
+          navigator.replace(targetUrl, routerState);
+        }
+        commitActiveTab();
+      } else if (historyMode === 'push') {
+        window.history.pushState(createPushHistoryState(window.history.state), '', targetUrl);
+        commitActiveTab();
+      } else {
+        window.history.replaceState(window.history.state, '', targetUrl);
+        commitActiveTab();
+      }
+    } finally {
+      writingUrlRef.current = false;
+    }
+  }, [enabled, historyMode, isInitialized, state.tabsList, state.activeKey, interactionSequence, navigator, dataRouterContext, rollbackTabActivation]);
+};

package/es/ProLayout/components/TabsManager/index.js

@@ -1,6 +1,7 @@
 import { useCallback, useMemo, forwardRef, useImperativeHandle, useState, useEffect, useLayoutEffect, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { useTabsState } from "./hooks/useTabsState";
+import { useTabsUrlSync } from "./hooks/useTabsUrlSync";
 import { useIframeRoute } from "./hooks/useIframeRoute";
 import { flattenMenuData, resolveTabMenuItem, derivePinned } from "./utils";
 import { TabItemComponent } from "./components/TabItem";
@@ -22,12 +23,12 @@ const TabsManager = /*#__PURE__*/forwardRef(({
 }, ref) => {
   // iframe 模式检测(在 useTabsState 之前,因为 cacheEnabled 依赖 pure)
   // addTab 由后续 useTabsState 提供,此处先用占位,后面用 ref 透传
-  const iframeAddTabRef = useRef(() => {});
+  const iframeAddTabRef = useRef(undefined);
   const {
     pure: isIframePure
   } = useIframeRoute({
     config: config?.iframe,
-    addTab: params => iframeAddTabRef.current(params)
+    addTab: params => iframeAddTabRef.current?.(params)
   });
 
   // 通知父级(ProLayout)pure 状态变化
@@ -46,7 +47,9 @@ const TabsManager = /*#__PURE__*/forwardRef(({
     canAddTab,
     removeTab,
     updateTab,
+    updateTabUrl,
     switchTab,
+    rollbackTabActivation,
     closeOtherTabs,
     closeRightTabs,
     closeAllTabs,
@@ -58,6 +61,21 @@ const TabsManager = /*#__PURE__*/forwardRef(({
     dataSource,
     cacheEnabled: !isIframePure
   });
+  const tabInteractionSequenceRef = useRef(0);
+  const markTabInteraction = useCallback(() => {
+    tabInteractionSequenceRef.current += 1;
+  }, []);
+  useTabsUrlSync({
+    config,
+    dataSource,
+    state,
+    isInitialized,
+    addTab,
+    switchTab,
+    updateTabUrl,
+    rollbackTabActivation,
+    interactionSequence: tabInteractionSequenceRef.current
+  });
 
   // 桥接 useIframeRoute 的 { code, name, extra } → addTab(menuItem)
   iframeAddTabRef.current = params => {
@@ -212,10 +230,11 @@ const TabsManager = /*#__PURE__*/forwardRef(({
   // 处理菜单点击 - 拦截原有的菜单点击逻辑
   const handleMenuClick = useCallback(params => {
     if (params.item) {
+      markTabInteraction();
       addTab(params.item);
     }
     originalOnMenuClick?.(params);
-  }, [addTab, originalOnMenuClick]);
+  }, [addTab, markTabInteraction, originalOnMenuClick]);
 
   // 切换固定状态：已固定→取消固定，未固定→固定
   const handleTogglePin = useCallback(tabId => {
@@ -231,11 +250,15 @@ const TabsManager = /*#__PURE__*/forwardRef(({
   // 创建标签页实例 API
   const tabsInstance = useMemo(() => ({
     addTab: (params, options) => {
+      markTabInteraction();
       const sourceMenus = Array.isArray(dataSource?.menus) ? dataSource.menus : [];
       const menuItem = resolveTabMenuItem(params, sourceMenus);
       addTab(menuItem, options);
     },
-    removeTab,
+    removeTab: tabId => {
+      markTabInteraction();
+      removeTab(tabId);
+    },
     updateTab,
     getTabInfo: () => ({
       tabsList: state.tabsList,
@@ -245,15 +268,32 @@ const TabsManager = /*#__PURE__*/forwardRef(({
     pushView,
     back,
     getViewStack
-  }), [addTab, removeTab, updateTab, state.tabsList, state.activeKey, state.activeComponent, dataSource, pushView, back, getViewStack]);
+  }), [addTab, markTabInteraction, removeTab, updateTab, state.tabsList, state.activeKey, state.activeComponent, dataSource, pushView, back, getViewStack]);
   const handleTabChange = useCallback(activeKey => {
+    markTabInteraction();
     switchTab(activeKey);
-  }, [switchTab]);
+  }, [markTabInteraction, switchTab]);
+  const handleRemoveTab = useCallback(tabId => {
+    markTabInteraction();
+    removeTab(tabId);
+  }, [markTabInteraction, removeTab]);
+  const handleCloseOtherTabs = useCallback(tabId => {
+    markTabInteraction();
+    closeOtherTabs(tabId);
+  }, [closeOtherTabs, markTabInteraction]);
+  const handleCloseRightTabs = useCallback(tabId => {
+    markTabInteraction();
+    closeRightTabs(tabId);
+  }, [closeRightTabs, markTabInteraction]);
+  const handleCloseAllTabs = useCallback(() => {
+    markTabInteraction();
+    closeAllTabs();
+  }, [closeAllTabs, markTabInteraction]);
   const handleTabEdit = useCallback((targetKey, action) => {
     if (action === 'remove') {
-      removeTab(targetKey);
+      handleRemoveTab(targetKey);
     }
-  }, [removeTab]);
+  }, [handleRemoveTab]);
 
   // 构建 Tabs items
   const tabsItems = useMemo(() => {
@@ -269,11 +309,11 @@ const TabsManager = /*#__PURE__*/forwardRef(({
         label: /*#__PURE__*/_jsx(TabItemComponent, {
           tab: tab,
           active: tab.id === state.activeKey,
-          onClick: () => switchTab(tab.id),
-          onClose: () => removeTab(tab.id),
-          onCloseOthers: () => closeOtherTabs(tab.id),
-          onCloseRight: () => closeRightTabs(tab.id),
-          onCloseAll: closeAllTabs,
+          onClick: () => handleTabChange(tab.id),
+          onClose: () => handleRemoveTab(tab.id),
+          onCloseOthers: () => handleCloseOtherTabs(tab.id),
+          onCloseRight: () => handleCloseRightTabs(tab.id),
+          onCloseAll: handleCloseAllTabs,
           pinned: pinned,
           pinDisabled: pinDisabled,
           onTogglePin: () => handleTogglePin(tab.id),
@@ -286,7 +326,7 @@ const TabsManager = /*#__PURE__*/forwardRef(({
         children: null
       };
     });
-  }, [state.tabsList, state.activeKey, config?.menuItems, config?.tabMenuClick, config?.fixed, switchTab, removeTab, closeOtherTabs, closeRightTabs, closeAllTabs, handleTogglePin]);
+  }, [state.tabsList, state.activeKey, config?.menuItems, config?.tabMenuClick, config?.fixed, handleTabChange, handleRemoveTab, handleCloseOtherTabs, handleCloseRightTabs, handleCloseAllTabs, handleTogglePin]);
   const activeComponent = config?.activeComponent;
   const emptyComponent = config?.empty;
 

package/es/ProLayout/components/TabsManager/propTypes.d.ts

@@ -71,8 +71,12 @@ export interface UseTabsStateReturn {
     removeTab: (tabId: string) => void;
     /** 更新指定 id 的标签页字段（替换语义；找不到时 no-op） */
     updateTab: (tabId: string, updates: UpdateTabParams) => void;
+    /** 更新页签当前 URL，保持 tab.id 不变 */
+    updateTabUrl: (tabId: string, url: string) => void;
     /** 切换标签页 */
     switchTab: (tabId: string) => void;
+    /** URL 导航未提交时回滚本次激活 */
+    rollbackTabActivation: (previousTabId: string, attemptedTabId: string, removeAttemptedTab: boolean) => void;
     /** 关闭其他标签页 */
     closeOtherTabs: (currentTabId: string) => void;
     /** 关闭右侧标签页 */

package/es/ProLayout/components/TabsManager/style/index.less

@@ -171,7 +171,7 @@
       padding: 4px 0 5px !important;
       margin-right: 8px !important;
       margin-left: 0;
-      background: #F5F5F5;
+      background: #f5f5f5;
       transition: none;
       border-color: #e7e8ee;
       &.@{ant-prefix}-tabs-tab-active {

package/es/ProLayout/components/TabsManager/utils/historyObserver.d.ts

@@ -0,0 +1,7 @@
+export type HistoryLocationChangeSource = 'push' | 'replace' | 'pop' | 'hash';
+type HistoryLocationListener = (source: HistoryLocationChangeSource) => void;
+/**
+ * 共享对原生 History 的唯一包装，避免多个 ProLayout 实例互相覆盖和泄漏。
+ */
+export declare const subscribeHistoryLocation: (listener: HistoryLocationListener) => (() => void);
+export {};

package/es/ProLayout/components/TabsManager/utils/historyObserver.js

@@ -0,0 +1,62 @@
+const listeners = new Set();
+let originalPushState;
+let originalReplaceState;
+let wrappedPushState;
+let wrappedReplaceState;
+let installationSequence = 0;
+let activeInstallation = 0;
+const notify = source => {
+  listeners.forEach(listener => listener(source));
+};
+const handlePopState = () => notify('pop');
+const handleHashChange = () => notify('hash');
+const install = () => {
+  const browserHistory = window.history;
+  const installation = installationSequence + 1;
+  installationSequence = installation;
+  activeInstallation = installation;
+  originalPushState = browserHistory.pushState;
+  originalReplaceState = browserHistory.replaceState;
+  const installedPushState = originalPushState;
+  const installedReplaceState = originalReplaceState;
+  wrappedPushState = function pushState(...args) {
+    installedPushState.apply(browserHistory, args);
+    if (activeInstallation === installation) notify('push');
+  };
+  wrappedReplaceState = function replaceState(...args) {
+    installedReplaceState.apply(browserHistory, args);
+    if (activeInstallation === installation) notify('replace');
+  };
+  browserHistory.pushState = wrappedPushState;
+  browserHistory.replaceState = wrappedReplaceState;
+  window.addEventListener('popstate', handlePopState);
+  window.addEventListener('hashchange', handleHashChange);
+};
+const uninstall = () => {
+  const browserHistory = window.history;
+  activeInstallation = 0;
+  if (wrappedPushState && originalPushState && browserHistory.pushState === wrappedPushState) {
+    browserHistory.pushState = originalPushState;
+  }
+  if (wrappedReplaceState && originalReplaceState && browserHistory.replaceState === wrappedReplaceState) {
+    browserHistory.replaceState = originalReplaceState;
+  }
+  window.removeEventListener('popstate', handlePopState);
+  window.removeEventListener('hashchange', handleHashChange);
+  originalPushState = undefined;
+  originalReplaceState = undefined;
+  wrappedPushState = undefined;
+  wrappedReplaceState = undefined;
+};
+
+/**
+ * 共享对原生 History 的唯一包装，避免多个 ProLayout 实例互相覆盖和泄漏。
+ */
+export const subscribeHistoryLocation = listener => {
+  if (listeners.size === 0) install();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) uninstall();
+  };
+};

package/es/ProLayout/components/TabsManager/utils/index.d.ts

@@ -5,7 +5,20 @@ import { AddTabParams, TabItem, MenusType } from '../../../propTypes';
  */
 export declare const getMenuRoute: (menuItem: MenusType) => string;
 export declare const hasRelationKey: (relationKey: MenusType['relationKey']) => relationKey is string | number;
-export declare const findExistingTab: (tabsList: TabItem[], menuItem: MenusType) => TabItem | undefined;
+/**
+ * 将同源 URL 规范化为应用内地址，保留 search 和 hash。
+ * 返回 undefined 表示 URL 无效或跨域。
+ */
+export declare const normalizeTabUrl: (value?: string) => string | undefined;
+/** 仅允许将跨域 HTTP(S) URL 交给浏览器外部打开。 */
+export declare const isSafeExternalUrl: (value?: string) => boolean;
+export declare const isSafeHttpUrl: (value?: string) => boolean;
+export declare const getCurrentTabUrl: () => string;
+export declare const getTabUrlPathname: (value?: string) => string | undefined;
+export interface FindExistingTabOptions {
+    urlSync?: boolean;
+}
+export declare const findExistingTab: (tabsList: TabItem[], menuItem: MenusType, options?: FindExistingTabOptions) => TabItem | undefined;
 /**
  * 根据菜单项生成TabItem
  */
@@ -21,7 +34,7 @@ export declare const shouldOpenExternal: (menuItem: MenusType, target?: string)
 /**
  * 处理外部跳转
  */
-export declare const handleExternalOpen: (menuItem: MenusType) => void;
+export declare const handleExternalOpen: (menuItem: MenusType, secure?: boolean) => void;
 /**
  * 检查是否超出最大标签页限制
  * @param currentTabs 当前标签页列表