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

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

@@ -3,7 +3,7 @@ import { message } from 'antd';
 import { DEFAULT_TABS_CONFIG } from "../propTypes";
 import { useTabsCache } from "./useTabsCache";
 import locale, { formatMessage } from "../../../../locale";
-import { createTabFromMenu, generateTabId, shouldOpenExternal, handleExternalOpen, checkTabLimit, getRightTabs, flattenMenuData, canOpenAsTab, getMenuRoute, findExistingTab, resolveTabMenuItem, derivePinned, getPinnedBoundary, pinTab as pinTabInList, unpinTab as unpinTabInList, reorderWithPinConstraint } from "../utils";
+import { createTabFromMenu, generateTabId, shouldOpenExternal, handleExternalOpen, checkTabLimit, getRightTabs, flattenMenuData, canOpenAsTab, getMenuRoute, findExistingTab, normalizeTabUrl, isSafeExternalUrl, isSafeHttpUrl, resolveTabMenuItem, derivePinned, getPinnedBoundary, pinTab as pinTabInList, unpinTab as unpinTabInList, reorderWithPinConstraint } from "../utils";
 
 /**
  * 标签页状态管理Hook
@@ -21,6 +21,7 @@ export const useTabsState = options => {
     ...DEFAULT_TABS_CONFIG,
     ...config
   };
+  const urlSyncEnabled = finalConfig.urlSync === true || typeof finalConfig.urlSync === 'object' && finalConfig.urlSync !== null;
 
   // 初始化状态
   const [state, setState] = useState(() => ({
@@ -47,7 +48,10 @@ export const useTabsState = options => {
   const [isInitialized, setIsInitialized] = useState(false);
 
   // 从缓存恢复状态
+  const hasRestoredCacheRef = useRef(false);
   useEffect(() => {
+    if (hasRestoredCacheRef.current) return;
+    hasRestoredCacheRef.current = true;
     const cachedState = restoreFromCache();
     if (cachedState && cachedState.tabsList && cachedState.tabsList.length > 0) {
       // 兼容旧缓存：如果缓存中有 activeTab 但没有 activeTabInfo，进行迁移
@@ -67,11 +71,33 @@ export const useTabsState = options => {
         pinned: tab.pinned === undefined ? derivePinned(tab) : tab.pinned
       }));
       restoredState.activeKey = restoredState.activeKey === undefined || restoredState.activeKey === null ? '' : String(restoredState.activeKey);
+      if (urlSyncEnabled) {
+        const retainedTabByUrl = new Map();
+        const retainedIdByOriginalId = new Map();
+        restoredState.tabsList.forEach(tab => {
+          const normalizedUrl = normalizeTabUrl(tab.url);
+          if (!normalizedUrl) return;
+          const retainedTab = retainedTabByUrl.get(normalizedUrl);
+          if (retainedTab) {
+            retainedIdByOriginalId.set(tab.id, retainedTab.id);
+            return;
+          }
+          const normalizedTab = {
+            ...tab,
+            url: normalizedUrl
+          };
+          retainedTabByUrl.set(normalizedUrl, normalizedTab);
+          retainedIdByOriginalId.set(tab.id, normalizedTab.id);
+        });
+        restoredState.tabsList = Array.from(retainedTabByUrl.values());
+        restoredState.activeKey = retainedIdByOriginalId.get(restoredState.activeKey) || restoredState.tabsList[0]?.id || '';
+      }
       restoredState.activeTabInfo = restoredState.tabsList.find(tab => tab.id === restoredState.activeKey);
+      restoredState.activeComponent = restoredState.activeTabInfo ? restoredState.activeTabInfo.menuItem?.code || restoredState.activeTabInfo.id : '';
       setState(restoredState);
     }
     setIsInitialized(true);
-  }, [restoreFromCache]);
+  }, [restoreFromCache, urlSyncEnabled]);
   const lastActiveKeyRef = useRef('');
   const shouldSkipSaveRef = useRef(false);
   const initialTabsAppliedRef = useRef(false);
@@ -128,9 +154,11 @@ export const useTabsState = options => {
       return false;
     }
 
-    // 如果 forceNew = false（默认），检查是否已存在相同的标签页
-    if (!forceNew) {
-      const existingTab = findExistingTab(state.tabsList, menuItem);
+    // URL 同步模式下完整 URL 始终唯一，forceNew 不能绕过身份匹配。
+    if (urlSyncEnabled || !forceNew) {
+      const existingTab = findExistingTab(state.tabsList, menuItem, {
+        urlSync: urlSyncEnabled
+      });
       if (existingTab) {
         // 如果已存在，可以添加（会切换到已存在的标签页）
         return true;
@@ -143,7 +171,7 @@ export const useTabsState = options => {
       return false;
     }
     return true;
-  }, [state.tabsList, finalConfig]);
+  }, [state.tabsList, finalConfig, urlSyncEnabled]);
 
   /**
    * 添加标签页
@@ -156,15 +184,33 @@ export const useTabsState = options => {
     setState(prevState => {
       if (!canOpenAsTab(menuItem)) return prevState;
       if (shouldOpenExternal(menuItem)) {
-        handleExternalOpen(menuItem);
+        const externalUrl = getMenuRoute(menuItem);
+        if (!urlSyncEnabled || isSafeHttpUrl(externalUrl)) {
+          handleExternalOpen(menuItem, urlSyncEnabled);
+        }
+        return prevState;
+      }
+      const rawUrl = getMenuRoute(menuItem);
+      const normalizedUrl = urlSyncEnabled ? normalizeTabUrl(rawUrl) : undefined;
+      if (urlSyncEnabled && rawUrl && !normalizedUrl) {
+        if (isSafeExternalUrl(rawUrl)) {
+          handleExternalOpen(menuItem, true);
+        }
         return prevState;
       }
+      const resolvedMenuItem = normalizedUrl ? {
+        ...menuItem,
+        url: normalizedUrl,
+        redirectUrl: undefined
+      } : menuItem;
 
       // 非强制新建时，查找已存在的标签页并切换
-      const existingTab = !forceNew ? findExistingTab(prevState.tabsList, menuItem) : undefined;
+      const existingTab = urlSyncEnabled || !forceNew ? findExistingTab(prevState.tabsList, resolvedMenuItem, {
+        urlSync: urlSyncEnabled
+      }) : undefined;
       if (existingTab) {
         // 若来源菜单明确标记 closable: false 而已有 tab 未继承，则修正
-        const correctedTab = menuItem.closable === false && existingTab.closable !== false ? {
+        const correctedTab = resolvedMenuItem.closable === false && existingTab.closable !== false ? {
           ...existingTab,
           closable: false
         } : existingTab;
@@ -184,8 +230,8 @@ export const useTabsState = options => {
         return prevState;
       }
       const existingIds = prevState.tabsList.map(tab => tab.id);
-      const tabId = generateTabId(menuItem, existingIds);
-      const newTab = createTabFromMenu(menuItem, prevState.newTabIndex);
+      const tabId = generateTabId(resolvedMenuItem, existingIds);
+      const newTab = createTabFromMenu(resolvedMenuItem, prevState.newTabIndex);
       newTab.id = tabId;
       const pinnedBoundary = getPinnedBoundary(prevState.tabsList);
       const nextTabsList = derivePinned(newTab) ? [...prevState.tabsList.slice(0, pinnedBoundary), newTab, ...prevState.tabsList.slice(pinnedBoundary)] : [...prevState.tabsList, newTab];
@@ -198,10 +244,10 @@ export const useTabsState = options => {
         activeKey: shouldActivate ? tabId : prevState.activeKey,
         activeTabInfo: shouldActivate ? newTab : prevState.activeTabInfo,
         newTabIndex: prevState.newTabIndex + 1,
-        activeComponent: shouldActivate ? menuItem.code || tabId : prevState.activeComponent
+        activeComponent: shouldActivate ? resolvedMenuItem.code || tabId : prevState.activeComponent
       };
     });
-  }, [finalConfig]);
+  }, [finalConfig, urlSyncEnabled]);
 
   // 普通初始标签只在当前 TabsManager 挂载周期应用一次。
   // 缓存恢复已有标签时只消费默认值；closeAll 后 ref 保持 true，避免再次补签。
@@ -344,6 +390,46 @@ export const useTabsState = options => {
     });
   }, []);
 
+  /**
+   * Router blocker 拒绝 URL 导航时，将激活状态还原到上一个已提交页签。
+   * 首次打开页签就被拦截时，同时移除未提交的新页签。
+   */
+  const rollbackTabActivation = useCallback((previousTabId, attemptedTabId, removeAttemptedTab) => {
+    setState(prevState => {
+      if (prevState.activeKey !== attemptedTabId) return prevState;
+      const nextTabsList = removeAttemptedTab ? prevState.tabsList.filter(tab => tab.id !== attemptedTabId) : prevState.tabsList;
+      const previousTab = nextTabsList.find(tab => tab.id === previousTabId);
+      return {
+        ...prevState,
+        tabsList: nextTabsList,
+        activeKey: previousTab?.id || '',
+        activeTabInfo: previousTab,
+        activeComponent: previousTab ? previousTab.menuItem?.code || previousTab.id : ''
+      };
+    });
+  }, []);
+
+  /**
+   * 更新页签当前 URL，保持 tab.id 和 menuItem 的菜单基础路由不变。
+   */
+  const updateTabUrl = useCallback((tabId, url) => {
+    setState(prevState => {
+      const targetIndex = prevState.tabsList.findIndex(tab => tab.id === tabId);
+      if (targetIndex === -1 || prevState.tabsList[targetIndex].url === url) return prevState;
+      const nextTab = {
+        ...prevState.tabsList[targetIndex],
+        url
+      };
+      const nextTabsList = [...prevState.tabsList];
+      nextTabsList[targetIndex] = nextTab;
+      return {
+        ...prevState,
+        tabsList: nextTabsList,
+        activeTabInfo: prevState.activeKey === tabId ? nextTab : prevState.activeTabInfo
+      };
+    });
+  }, []);
+
   /**
    * 关闭其他标签页
    */
@@ -474,9 +560,9 @@ export const useTabsState = options => {
     });
   }, []);
 
-  // 监听 URL 变化并同步 Tabs (仅在初始化和 location 变化时)
-  // 放在最后以确保可以使用 addTab 和 switchTab
+  // URL 不同步模式保留旧有的 pathname -> Tabs 初始匹配，但不写回 URL。
   useEffect(() => {
+    if (urlSyncEnabled) return;
     if (!dataSource || !('menus' in dataSource)) return;
     const currentPath = window.location.pathname;
     const activeTab = state.tabsList.find(tab => tab.id === state.activeKey);
@@ -490,7 +576,7 @@ export const useTabsState = options => {
       return;
     }
     addTab(targetMenu);
-  }, [dataSource, state.tabsList, state.activeKey, addTab, switchTab]);
+  }, [urlSyncEnabled, dataSource, state.tabsList, state.activeKey, addTab, switchTab]);
   return {
     state,
     isInitialized,
@@ -498,7 +584,9 @@ export const useTabsState = options => {
     canAddTab,
     removeTab,
     updateTab,
+    updateTabUrl,
     switchTab,
+    rollbackTabActivation,
     closeOtherTabs,
     closeRightTabs,
     closeAllTabs,

package/es/ProLayout/components/TabsManager/hooks/useTabsUrlSync.d.ts

@@ -0,0 +1,19 @@
+import type { TabsConfig, TabsState } from '../../../propTypes';
+import type { TabsManagerProps, UseTabsStateReturn } from '../propTypes';
+interface UseTabsUrlSyncOptions {
+    config: TabsConfig;
+    dataSource: TabsManagerProps['dataSource'];
+    state: TabsState;
+    isInitialized: boolean;
+    addTab: UseTabsStateReturn['addTab'];
+    switchTab: UseTabsStateReturn['switchTab'];
+    updateTabUrl: UseTabsStateReturn['updateTabUrl'];
+    rollbackTabActivation: UseTabsStateReturn['rollbackTabActivation'];
+    interactionSequence: number;
+}
+/**
+ * 维护浏览器 location 与活动页签 URL 的双向同步。
+ * 未开启 config.urlSync 时不安装任何 History 监听或写入逻辑。
+ */
+export declare const useTabsUrlSync: ({ config, dataSource, state, isInitialized, addTab, switchTab, updateTabUrl, rollbackTabActivation, interactionSequence, }: UseTabsUrlSyncOptions) => void;
+export {};

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;