vue-stack-tabs 1.4.2 → 2.2.0

package/src/lib/hooks/useTabPanel.tsx

@@ -16,7 +16,7 @@ import { computed, ref } from 'vue'
 import type { DefineComponent, VNode } from 'vue'
 import { isNavigationFailure, useRouter } from 'vue-router'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
-import { encodeTabInfo, createPageId, decodeTabInfo } from '../utils/tabInfoEncoder'
+import { encodeTabInfo, createId, createPageId, decodeTabInfo } from '../utils/tabInfoEncoder'
 import { defu } from 'defu'
 import { Stack } from '../model/TabModel'
 import {
@@ -25,7 +25,9 @@ import {
   omitStackTabsReservedQuery,
   toSafeTabUrl,
   decodeSafeTabUrl,
-  cloneLocationQuery
+  cloneLocationQuery,
+  isSameQueryIgnoringReserved,
+  normalizePathname
 } from '../utils/urlParser'
 import { TabEventType, useTabEmitter } from './useTabEventBus'
 import { runNavigationTransaction } from './tabPanel/navigationTransaction'
@@ -44,6 +46,9 @@ const cloneRouteQuery = (route: RouteLocationNormalizedLoaded, tabInfo: ITabBase
   __tab: route.query.__tab ?? encodeTabInfo(tabInfo)
 })
 
+/** homeTab 未显式指定 id 时使用的固定 id，保证刷新前后 __tab 与标签身份一致。 */
+const DEFAULT_HOME_TAB_ID = '__stack_tabs_home__'
+
 /** 规范化路径（nginx 等可能加尾部斜杠） */
 export const normalizePathForCache = (route: RouteLocationNormalizedLoaded): string => {
   const lastMatch = route.matched[route.matched.length - 1]
@@ -52,9 +57,8 @@ export const normalizePathForCache = (route: RouteLocationNormalizedLoaded): str
   return matchPath === path ? path : route.path
 }
 
-export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
+const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
   const router = useRouter()
-  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
   const emitter = useTabEmitter(runtimeContext)
   const { t } = useI18n()
   const { tabs, defaultTabs, caches, refreshKey, iframeRefreshKeys, isInitialized } = runtimeContext
@@ -68,10 +72,12 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     canAddTab,
     getPages,
     getTopPage,
+    getPageRefreshVersion,
     getPageSnapshot,
     addTab,
     addTabs,
     activateTab,
+    updateTabTitle: updateTabTitleInStore,
     moveTab,
     removeTab: removeTabFromStore,
     removeTabs: removeTabsFromStore,
@@ -80,6 +86,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     replacePages,
     clearPages,
     updatePage,
+    updatePages,
     consumeBackParams,
     markCacheForEviction,
     markTabPagesForEvictionOnly,
@@ -114,29 +121,43 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
   const size = (): number => getTabs().length
 
   /**
-   * 初始化：根据 defaultTabs 创建标签与初始页面，并尝试从 sessionStorage 恢复上次激活的标签
+   * 初始化：先创建固定首页（homeTab），再创建 defaultTabs，并尝试从 sessionStorage 恢复上次激活的标签
    * @param staticTabs - 初始标签配置
+   * @param homeTab - 固定首页；始终位于第一位、不可关闭、不可移动
    */
-  const initialize = (staticTabs: ITabData[]) => {
+  const initialize = (staticTabs: ITabData[], homeTab?: ITabData) => {
+    // 重复调用会累加 defaultTabs 并重复注册标签；初始化后直接忽略。
+    if (isInitialized.value) {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] initialize() called more than once; ignored.')
+      }
+      return
+    }
     const newDefaults: ITabItem[] = []
     const newTabs: ITabItem[] = []
+    let homeTabId = ''
 
-    for (const item of staticTabs) {
+    /** 由 ITabData 构建运行时标签；homeTab 通过 options 强制固定属性 */
+    const buildTab = (
+      item: ITabData,
+      options: { pinned?: boolean; closable?: boolean } = {}
+    ): ITabItem => {
       // 先用默认值填充非空缺字段，避免在循环里提前求值生成用不到的 UUID。
       const fullItem = defu(item, {
         refreshable: true,
         closable: true,
         iframe: false
       })
-      // id 单独兜底，避免每次循环都无意义地调用 crypto.randomUUID。
-      fullItem.id = item.id ?? crypto.randomUUID()
+      // homeTab 未指定 id 时使用固定 id，避免每次初始化生成新 id 后与 session 恢复标签重复。
+      fullItem.id = item.id ?? (options.pinned ? DEFAULT_HOME_TAB_ID : createId())
+      if (options.closable !== undefined) fullItem.closable = options.closable
       const tabId = fullItem.id
       const uri = parseUrl(fullItem.path)
       const cacheName = createPageId()
       const page: ITabPage = {
         id: cacheName,
         tabId,
-        path: uri.path,
+        path: normalizePathname(uri.path),
         query: defu(omitStackTabsReservedQuery(uri.query), { __tab: encodeTabInfo(fullItem) })
       }
       const pages = new Stack<ITabPage>()
@@ -152,10 +173,33 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
             ? 'reload'
             : 'postMessage',
         active: false,
-        pages
+        pages,
+        pinned: options.pinned
       }
 
       addCache(cacheName)
+      return tab
+    }
+
+    if (homeTab) {
+      const home = buildTab(homeTab, { pinned: true, closable: false })
+      homeTabId = home.id
+      newDefaults.push(home)
+      newTabs.push({ ...home })
+    }
+
+    for (const item of staticTabs) {
+      // home 已单独创建；相同 id 的配置跳过，避免出现两个固定首页。
+      if (homeTabId && item.id === homeTabId) {
+        if (!import.meta.env.PROD) {
+          console.warn(
+            '[vue-stack-tabs] defaultTabs contains the same id as homeTab; skipped:',
+            item.id
+          )
+        }
+        continue
+      }
+      const tab = buildTab(item)
       newDefaults.push(tab)
       newTabs.push({ ...tab })
     }
@@ -209,15 +253,95 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     iframeRefreshMode: tab.iframeRefreshMode
   })
 
+  /**
+   * 动态更新标签标题。
+   *
+   * 同步 TabRecord、对外视图与 session；激活标签还会把新的 __tab 写回当前 URL，
+   * 避免刷新或分享链接后标题回退。
+   */
+  const updateTabTitle = (tabId: string, title: string): boolean => {
+    if (!updateTabTitleInStore(tabId, title)) return false
+    const tab = getTab(tabId)
+    if (!tab) return false
+
+    if (tab.active) {
+      saveActiveTabToSession(tab)
+      const top = getTopPage(tabId)
+      if (top) {
+        void Promise.resolve(
+          router.replace({
+            path: top.path,
+            query: { ...cloneLocationQuery(top.query), __tab: encodeTabInfo(toTabBase(tab)) },
+            hash: router.currentRoute.value.hash
+          })
+        ).catch((error: unknown) => {
+          if (!import.meta.env.PROD) {
+            console.warn('[vue-stack-tabs] Failed to sync tab title to URL:', error)
+          }
+        })
+      }
+    }
+    return true
+  }
+
+  /** 当前固定首页（homeTab）；未配置时返回 null。 */
+  const getHomeTab = (): ITabItem | null => getTabs().find((tab) => tab.pinned) ?? null
+
+  /**
+   * 无 __tab 且当前路径没有归属标签时，导航到 homeTab 的栈顶页面。
+   * 使用 replace，避免在浏览器历史里留下中间状态。
+   */
+  const redirectToHome = (): boolean => {
+    const home = getHomeTab()
+    const top = home ? getTopPage(home.id) : null
+    if (!home || !top) return false
+
+    const query = {
+      ...cloneLocationQuery(top.query),
+      __tab: encodeTabInfo(toTabBase(home))
+    }
+    void Promise.resolve(
+      router.replace({
+        path: top.path,
+        query,
+        hash: ''
+      })
+    ).catch((error: unknown) => {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to redirect to home tab:', error)
+      }
+    })
+    return true
+  }
+
+  /**
+   * 是否应回落到 homeTab：仅限 URL 没有 __tab，且当前路径没有被任何标签的栈顶承载。
+   * 带 __tab 的地址即使页面不存在也不回落，交给应用自己的 404 路由处理。
+   */
+  const shouldRedirectToHome = (route: RouteLocationNormalizedLoaded): boolean => {
+    if (typeof route.query.__tab === 'string') return false
+
+    const path = normalizePathForCache(route)
+    const activeTab = getActiveTab()
+    if (activeTab && getTopPage(activeTab.id)?.path === path) return false
+    if (findTabByTopPagePath(path)) return false
+
+    const home = getHomeTab()
+    return Boolean(home && getTopPage(home.id))
+  }
+
   /**
    * 从路由解析 tabInfo，若无则创建默认信息，调用方负责把编码信息写入内部 page.query。
    *
    * 首次进入应用时 URL 上通常还没有 __tab：此时优先接管 path 匹配的默认标签（defaultTabs），
-   * 由调用方把 __tab 写回地址，保证「URL 指向默认标签」；确实找不到归属时才新建兜底标签。
+   * 由调用方把 __tab 写回地址，保证「URL 指向默认标签」；确实找不到归属且配置了 homeTab 时
+   * 返回 null，由调用方重定向到首页；未配置 homeTab 时保持原有兜底标签行为。
    */
-  const parseTabInfoFromRoute = (route: RouteLocationNormalizedLoaded): ITabBase => {
-    if (typeof route.query.__tab === 'string') {
-      const tabInfo = decodeTabInfo(route.query.__tab)
+  const parseTabInfoFromRoute = (route: RouteLocationNormalizedLoaded): ITabBase | null => {
+    const encodedTab = route.query.__tab
+    const hasEncodedTab = typeof encodedTab === 'string'
+    if (hasEncodedTab) {
+      const tabInfo = decodeTabInfo(encodedTab)
       if (tabInfo.id) return tabInfo
     }
 
@@ -234,8 +358,12 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     const pathMatchedTab = findTabByTopPagePath(path)
     if (pathMatchedTab) return toTabBase(pathMatchedTab)
 
+    // 无 __tab 且无任何标签承载当前路径：配置了 homeTab 时交给调用方重定向。
+    // 注意：__tab 存在但无效时仍保持原行为（新建兜底标签），不把错误地址变成首页。
+    if (!hasEncodedTab && getHomeTab()) return null
+
     return {
-      id: crypto.randomUUID(),
+      id: createId(),
       title: t('VueStackTab.undefined'),
       closable: true,
       refreshable: true,
@@ -268,7 +396,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
         url: decodeSafeTabUrl(src),
         active: true,
         pages
-      } as unknown as ITabItem
+      }
       activateTab('')
       addTab(targetTab)
       emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id!, isRoute: false })
@@ -295,10 +423,20 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     | { cacheName: string; tabInfo: ITabBase; targetTab: ITabItem }
     | { empty: true }
     | { recovered: DefineComponent; cacheName: string } => {
-    const tabInfo = parseTabInfoFromRoute(route)
+    const resolvedTabInfo = parseTabInfoFromRoute(route)
+    if (resolvedTabInfo === null) {
+      // 无 __tab 且没有标签承载当前路径：回落到 homeTab。
+      redirectToHome()
+      return { empty: true }
+    }
+    const tabInfo = resolvedTabInfo
     if (isTabMarkedForEviction(tabInfo.id!)) return { empty: true }
 
     const path = normalizePathForCache(route)
+    const routeQuery = cloneRouteQuery(route, tabInfo)
+    /** path 与业务 query 都一致才算同一个页面（忽略 __tab 等保留参数） */
+    const isSameLocation = (candidate: ITabPage): boolean =>
+      candidate.path === path && isSameQueryIgnoringReserved(routeQuery, candidate.query || {})
 
     let targetTab: ITabItem | null = tabInfo.id ? (getTab(tabInfo.id) as ITabItem | null) : null
     let cacheName: string
@@ -308,14 +446,23 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
       const top = getTopPage(targetTab.id)!
       if (!top) throw new Error('[vue-stack-tabs] Stack is not empty but peek() returned undefined')
 
-      if (top.path === path) {
+      if (isSameLocation(top)) {
         cacheName = top.id
+      } else if (top.path === path) {
+        // 同 path、不同 query：按产品语义作为新页面入栈，backward 才能按 query 精确回退。
+        cacheName = createPageId()
+        page = {
+          id: cacheName,
+          tabId: tabInfo.id!,
+          path,
+          query: cloneLocationQuery(routeQuery)
+        }
       } else {
         const pagesList = getPages(targetTab.id)
         let foundIndex = -1
         for (let i = pagesList.length - 2; i >= 0; i--) {
           const pastPage = pagesList[i]
-          if (pastPage && pastPage.path === path) {
+          if (pastPage && isSameLocation(pastPage)) {
             foundIndex = i
             break
           }
@@ -339,8 +486,8 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
             page = {
               id: cacheName,
               tabId: tabInfo.id!,
-              path: route.path,
-              query: cloneRouteQuery(route, tabInfo)
+              path,
+              query: cloneLocationQuery(routeQuery)
             }
           }
         } else {
@@ -348,8 +495,8 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
           page = {
             id: cacheName,
             tabId: tabInfo.id!,
-            path: route.path,
-            query: cloneRouteQuery(route, tabInfo)
+            path,
+            query: cloneLocationQuery(routeQuery)
           }
         }
       }
@@ -358,8 +505,8 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
       page = {
         id: cacheName,
         tabId: tabInfo.id!,
-        path: route.path,
-        query: cloneRouteQuery(route, tabInfo)
+        path,
+        query: cloneLocationQuery(routeQuery)
       }
     }
 
@@ -404,7 +551,12 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     route: RouteLocationNormalizedLoaded,
     component?: VNode | null
   ): DefineComponent => {
-    if (!component) return getEmptyPlaceholderComponent()
+    if (!component) {
+      // 路由没有匹配到组件时不会进入 updatePageState；仍需处理无 __tab 的未知地址回落到首页。
+      // 带 __tab 的未知页面不做重定向，交给应用自己的 404 路由（或空占位）处理。
+      if (shouldRedirectToHome(route)) redirectToHome()
+      return getEmptyPlaceholderComponent()
+    }
 
     const routeKey = route.fullPath + (route.query.__tab || '')
     if (routeKey === lastRouteKey && lastAddPageResult) {
@@ -517,6 +669,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     getTabs,
     getTopPage,
     updatePage,
+    updatePages,
     iframeRefreshKeys,
     createPageId,
     addCache,
@@ -606,6 +759,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     initialize,
     size,
     active,
+    updateTabTitle,
     getCacheName: createCacheName,
     destroy,
     reset,
@@ -615,6 +769,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     getActiveTab,
     getTopPage,
     getPages,
+    getPageRefreshVersion,
     getPageSnapshot,
     moveTab,
     addTab,
@@ -623,6 +778,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     replacePages,
     clearPages,
     updatePage,
+    updatePages,
     removeTab,
     removeAllTabs,
     removeLeftTabs,
@@ -651,3 +807,24 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     }
   }
 }
+
+type TabPanelApi = ReturnType<typeof createTabPanelApi>
+
+const panelApiByContext = new WeakMap<StackTabsRuntimeContext, TabPanelApi>()
+
+/**
+ * 同一个运行时上下文复用同一套 panel API。
+ *
+ * StackTabs、StackKeepAlive、StackCacheRenderer、ContextMenu 与页面内的 useTabRouter
+ * 都会调用本 hook；首次调用在 setup 上下文中完成 useRouter/useI18n 注入，
+ * 后续调用直接返回缓存，避免重复创建 scroll/session/refresh 闭包与局部状态。
+ */
+export default (providedRuntimeContext?: StackTabsRuntimeContext): TabPanelApi => {
+  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
+  const existing = panelApiByContext.get(runtimeContext)
+  if (existing) return existing
+
+  const panelApi = createTabPanelApi(runtimeContext)
+  panelApiByContext.set(runtimeContext, panelApi)
+  return panelApi
+}

package/src/lib/hooks/useTabRouter.ts

@@ -1,4 +1,3 @@
-import { defu } from 'defu'
 import { getCurrentInstance } from 'vue'
 import type { ComponentInternalInstance } from 'vue'
 import type { LocationQueryRaw, RouteLocationPathRaw } from 'vue-router'
@@ -9,7 +8,9 @@ import {
   parseUrl,
   cloneLocationQuery,
   clonePage,
-  isSameQueryIgnoringReserved
+  isSameQueryIgnoringReserved,
+  normalizePathname,
+  omitStackTabsReservedQuery
 } from '../utils/urlParser'
 import { TabEventType, useTabEmitter } from './useTabEventBus'
 
@@ -84,10 +85,11 @@ export default function useTabRouter() {
   const forward = (to: RouteLocationPathRaw) => {
     const tab = getTab(tabId)
     const targetQuery = (to.query || {}) as LocationQueryRaw
+    const targetPath = normalizePathname(to.path)
 
     if (tab) {
       const top = getTopPage(tab.id)
-      if (top && top.path === to.path) {
+      if (top && top.path === targetPath) {
         if (isSameQueryIgnoringReserved(targetQuery, top.query || {})) {
           if (!tab.active) {
             activateTab(tab.id)
@@ -97,9 +99,10 @@ export default function useTabRouter() {
       }
     }
 
-    // __tab 是 StackTabs 解析路由归属标签的关键，优先沿用目标 query 已有的值，
-    // 避免被 to.query 中非字符串的同名 key 或缺失值覆盖。
-    const query = defu(to.query, { __tab: tabInfo })
+    // __tab 是 StackTabs 解析路由归属标签的关键：强制使用当前标签的编码，
+    // 业务 query 传入同名 key 时也不能把导航带到其它标签。
+    const query: LocationQueryRaw = { ...omitStackTabsReservedQuery(targetQuery) }
+    if (typeof tabInfo === 'string' && tabInfo) query.__tab = tabInfo
     const transactionVersion = ++navigationVersion
     emitter.emit(TabEventType.FORWARD)
 
@@ -112,8 +115,8 @@ export default function useTabRouter() {
           appendPage(tab.id, {
             id: optimisticPageId,
             tabId: tab.id,
-            path: to.path,
-            query: cloneLocationQuery(targetQuery)
+            path: targetPath,
+            query: cloneLocationQuery(query)
           })
         }
         return snapshot
@@ -156,13 +159,14 @@ export default function useTabRouter() {
     } else {
       const parsed = parseUrl(to)
       const targetQuery = parsed.query || {}
+      const targetPath = normalizePathname(parsed.path)
       let found = false
 
       for (let i = pages.length - 2; i >= 0; i--) {
         steps++
         const page = pages[i]
         if (
-          page?.path === parsed.path &&
+          page?.path === targetPath &&
           isSameQueryIgnoringReserved(targetQuery, page?.query || {})
         ) {
           found = true
@@ -210,8 +214,11 @@ export default function useTabRouter() {
 
     emitter.emit(TabEventType.BACKWARD)
 
-    // 栈顶 query 已带 __tab 时优先沿用，避免被默认 tabInfo 覆盖导致解析时识别错乱。
-    const targetQueryWithTab = defu(target.query || {}, { __tab: tabInfo })
+    // 与 forward 一致：目标页固定归属当前标签，保留其余业务 query。
+    const targetQueryWithTab: LocationQueryRaw = {
+      ...omitStackTabsReservedQuery(target.query || {})
+    }
+    if (typeof tabInfo === 'string' && tabInfo) targetQueryWithTab.__tab = tabInfo
     const transactionVersion = ++navigationVersion
 
     runNavigationTransaction({

package/src/lib/model/TabModel.ts

@@ -64,6 +64,11 @@ export interface ITabItem extends ITabBase {
   url?: string
   active: boolean
   pages: Stack<ITabPage>
+  /**
+   * 固定在标签栏最前方的内部标记（目前仅 homeTab 使用）。
+   * pinned 标签不可被拖动，其他标签也不能排到它前面；仅存在于运行时，不写入 __tab。
+   */
+  pinned?: boolean
 }
 
 /** 标签内的单个页面（对应 keep-alive 的一个缓存实例） */

package/src/lib/utils/tabInfoEncoder.ts

@@ -1,4 +1,5 @@
 import type { ITabBase } from '../model/TabModel'
+import { isRecord } from './typeGuards'
 
 interface EncodedTabInfoV1 {
   version: 1
@@ -14,20 +15,42 @@ interface EncodedTabInfoV1 {
  * 标签信息编解码器
  *
  * 职责：将标签元数据编码为 URL query 可用的短字符串，用于 __tab 参数。
- * 当前格式为 JSON + Base64，兼容旧版 id|title|iframe|closable|refreshable|mode 编码。
+ * 当前格式为 JSON + Base64URL；解码同时兼容标准 Base64（历史链接）与
+ * 旧版 id|title|iframe|closable|refreshable|mode 编码。
  */
 
 const MAX_DECODED_TAB_INFO_LENGTH = 2048
 const MAX_ENCODED_TAB_INFO_LENGTH = 4096
+/** URL 中 __tab 的 title 上限，避免超长标题把 payload 顶到解码上限导致 id 丢失。 */
+export const MAX_TAB_TITLE_LENGTH = 256
+/** legacy 格式中 id 的合理上限，用于拒绝任意字符串伪装成标签 id。 */
+const MAX_LEGACY_TAB_ID_LENGTH = 128
 
 /**
- * 把任意 UTF-8 字符串安全地编码为 base64（避免中文/特殊字符直接 btoa 抛错）。
- * 使用 encodeURIComponent + unescape 是经典跨浏览器方案，比手动管理 TextEncoder 更简洁。
+ * 把 UTF-8 字符串编码为 Base64URL（无填充、`+`→`-`、`/`→`_`）。
+ * 使用 TextEncoder 取代已废弃的 escape/unescape，同时让结果可直接放进 URL。
  */
-const encodeBase64 = (value: string): string => btoa(unescape(encodeURIComponent(value)))
+const encodeBase64Url = (value: string): string => {
+  const bytes = new TextEncoder().encode(value)
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
 
-/** encodeBase64 的逆操作，非合法 base64 时抛错，由调用方 try/catch。 */
-const decodeBase64 = (encoded: string): string => decodeURIComponent(escape(atob(encoded)))
+/**
+ * 解码 Base64URL / 标准 Base64。
+ * 兼容旧链接：先还原 URL-safe 字符与填充，再按 UTF-8 解码。
+ */
+const decodeBase64 = (encoded: string): string => {
+  const normalized = encoded.replace(/-/g, '+').replace(/_/g, '/')
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.charCodeAt(index)
+  }
+  return new TextDecoder().decode(bytes)
+}
 
 const DEFAULT_TAB_INFO: ITabBase = {
   id: '',
@@ -38,7 +61,14 @@ const DEFAULT_TAB_INFO: ITabBase = {
   iframeRefreshMode: 'postMessage'
 }
 
-import { isRecord } from './typeGuards'
+/** 检测控制字符，避免 legacy id 携带不可见字符。 */
+const hasControlCharacter = (value: string): boolean => {
+  for (const char of value) {
+    const code = char.charCodeAt(0)
+    if (code <= 31 || code === 127) return true
+  }
+  return false
+}
 
 const toTabInfo = (payload: unknown): ITabBase => {
   if (!isRecord(payload)) return { ...DEFAULT_TAB_INFO }
@@ -54,16 +84,36 @@ const toTabInfo = (payload: unknown): ITabBase => {
   }
 }
 
+/**
+ * 旧版分隔符格式：id|title|iframe|closable|refreshable[|mode]。
+ *
+ * 严格校验字段数量与 Y/N 标记：非法字符串（例如 `?__tab=invalid`）不能再被解析成
+ * 任意 id 的标签。格式不合法时返回默认值，由路由层走兜底标签逻辑。
+ */
 const decodeLegacyTabInfo = (tabString: string): ITabBase => {
   const tabValues: string[] = tabString.split('|')
-  const refreshMode = tabValues[5] === 'R' ? ('reload' as const) : ('postMessage' as const)
+  if (tabValues.length < 5 || tabValues.length > 6) return { ...DEFAULT_TAB_INFO }
+
+  const [id = '', title = '', iframe, closable, refreshable, mode] = tabValues
+  const isFlag = (value: string | undefined): value is 'Y' | 'N' => value === 'Y' || value === 'N'
+  const hasValidId =
+    id.length > 0 &&
+    id.length <= MAX_LEGACY_TAB_ID_LENGTH &&
+    id.trim() === id &&
+    !hasControlCharacter(id)
+
+  if (!hasValidId || !isFlag(iframe) || !isFlag(closable) || !isFlag(refreshable)) {
+    return { ...DEFAULT_TAB_INFO }
+  }
+  if (mode !== undefined && mode !== '' && mode !== 'R') return { ...DEFAULT_TAB_INFO }
+
   return {
-    id: tabValues[0] ?? '',
-    title: tabValues[1] ?? '',
-    iframe: tabValues[2] === 'Y',
-    closable: tabValues[3] === 'Y',
-    refreshable: tabValues[4] === 'Y',
-    iframeRefreshMode: refreshMode
+    id,
+    title,
+    iframe: iframe === 'Y',
+    closable: closable === 'Y',
+    refreshable: refreshable === 'Y',
+    iframeRefreshMode: mode === 'R' ? 'reload' : 'postMessage'
   }
 }
 
@@ -71,13 +121,13 @@ export const encodeTabInfo = (tabData: ITabBase): string => {
   const payload: EncodedTabInfoV1 = {
     version: 1,
     id: tabData.id,
-    title: tabData.title,
+    title: tabData.title.slice(0, MAX_TAB_TITLE_LENGTH),
     iframe: tabData.iframe,
     closable: tabData.closable,
     refreshable: tabData.refreshable,
     iframeRefreshMode: tabData.iframeRefreshMode === 'reload' ? 'reload' : 'postMessage'
   }
-  return encodeBase64(JSON.stringify(payload))
+  return encodeBase64Url(JSON.stringify(payload))
 }
 
 export const decodeTabInfo = (encoded: string): ITabBase => {
@@ -102,4 +152,38 @@ export const decodeTabInfo = (encoded: string): ITabBase => {
   }
 }
 
-export const createPageId = (): string => crypto.randomUUID()
+/**
+ * 生成运行时 id。
+ *
+ * `crypto.randomUUID` 仅在安全上下文（https / localhost）可用；内网 http 部署时
+ * 回退到 `crypto.getRandomValues`（非安全上下文同样可用），最后才退回 Math.random，
+ * 避免在受限环境下直接抛 TypeError 导致整个组件不可用。
+ */
+export const createId = (): string => {
+  const cryptoObject = globalThis.crypto
+
+  if (typeof cryptoObject?.randomUUID === 'function') {
+    return cryptoObject.randomUUID()
+  }
+
+  const bytes = new Uint8Array(16)
+  if (typeof cryptoObject?.getRandomValues === 'function') {
+    cryptoObject.getRandomValues(bytes)
+  } else {
+    for (let index = 0; index < bytes.length; index++) {
+      bytes[index] = Math.floor(Math.random() * 256)
+    }
+  }
+
+  // RFC 4122 version 4 + variant bits
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
+
+  const hex: string[] = []
+  for (const byte of bytes) hex.push(byte.toString(16).padStart(2, '0'))
+  return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex
+    .slice(6, 8)
+    .join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10, 16).join('')}`
+}
+
+export const createPageId = (): string => createId()