vue-stack-tabs 1.4.2 → 2.3.0

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

@@ -17,22 +17,31 @@ export enum TabScrollMode {
   BOTH = 'both'
 }
 
-/** 标签栏滚动条拖拽时的临时状态 */
+/**
+ * @deprecated 标签栏拖拽内部已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
 export interface DragData {
   thumbLeft: number
   startScrollLeft: number
   startThumbLeft: number
   startPageX: number
 }
-/** 滚动条滑块计算所需的数据 */
+
+/**
+ * @deprecated 内部滚轮/滚动事件常量已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
+export type ScrollEvents = {
+  ScrollUpdate: void
+}
+
+/** 滚动条滑块计算所需的数据（滚动过程中保持非响应式） */
 export interface ScrollData {
   clientWidth: number
   scrollWidth: number
   scrollLeft: number
 }
-export type ScrollEvents = {
-  ScrollUpdate: void
-}
 
 /** 打开标签时传入的完整数据（含 path、query） */
 export interface ITabData extends ITabBase {
@@ -64,6 +73,11 @@ export interface ITabItem extends ITabBase {
   url?: string
   active: boolean
   pages: Stack<ITabPage>
+  /**
+   * 固定在标签栏最前方的内部标记（目前仅 homeTab 使用）。
+   * pinned 标签不可被拖动，其他标签也不能排到它前面；仅存在于运行时，不写入 __tab。
+   */
+  pinned?: boolean
 }
 
 /** 标签内的单个页面（对应 keep-alive 的一个缓存实例） */

package/src/lib/nuxt/module.ts

@@ -34,7 +34,9 @@ export default defineNuxtModule<ModuleOptions>({
     addComponent({
       name: 'VueStackTabs',
       export: 'VueStackTabs',
-      filePath: resolve('../index.ts')
+      // 指向发布产物（dist/vue-stack-tabs.es.js）中的命名导出；
+      // 源码入口 ../index.ts 不会被发布，Nuxt 构建时会解析失败。
+      filePath: resolve('../vue-stack-tabs.es.js')
     })
 
     addImports([

package/src/lib/nuxt/runtime/plugin.ts

@@ -4,7 +4,7 @@
 import { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'
 import VueStackTabs from 'vue-stack-tabs'
 import { applyStackTabsLocale } from '../../i18n/stackTabsLocale'
-import { useI18n } from 'vue-i18n-lite'
+import { useI18n, type I18n } from 'vue-i18n-lite'
 
 export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig().public.vueStackTabs as {
@@ -17,6 +17,10 @@ export default defineNuxtPlugin((nuxtApp) => {
 
   // 兜底：应用 vue-stack-tabs 内部 i18n 实例的 locale 切换逻辑，
   // 避免某些场景下 plugin options 未能正确初始化时 locale 仍是默认 zh-CN。
-  const { changeLocale } = useI18n()
-  applyStackTabsLocale(changeLocale, locale)
+  //
+  // 必须在 app 的注入上下文中取实例：插件顶层直接 inject() 拿不到 app.provide 的值。
+  nuxtApp.vueApp.runWithContext(() => {
+    const i18n = useI18n() as I18n | undefined
+    if (i18n?.changeLocale) applyStackTabsLocale(i18n.changeLocale, locale)
+  })
 })

package/src/lib/utils/scrollUtils.ts

@@ -71,24 +71,6 @@ export function scrollIntoView({
   }
 }
 
-/** 获取系统滚动条宽度（用于布局计算） */
-export const getScrollbarWidth = (function () {
-  let width: number | null = null
-
-  return function () {
-    if (width !== null) return width
-
-    const div = document.createElement('div')
-
-    div.style.cssText = 'width: 100px; height: 100px;overflow-y: scroll'
-    document.body.appendChild(div)
-    width = div.offsetWidth - div.clientWidth
-    div.parentElement?.removeChild(div)
-
-    return width
-  }
-})()
-
 const Z_INDEX_CEILING = 89999
 
 /**

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 丢失。 */
+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,16 +121,16 @@ 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 => {
+const decodeTabInfoUncached = (encoded: string): ITabBase => {
   if (typeof encoded !== 'string' || encoded.length > MAX_ENCODED_TAB_INFO_LENGTH) {
     return { ...DEFAULT_TAB_INFO }
   }
@@ -102,4 +152,57 @@ export const decodeTabInfo = (encoded: string): ITabBase => {
   }
 }
 
-export const createPageId = (): string => crypto.randomUUID()
+/**
+ * 单条解码缓存：同一 __tab 在一次会话/连续导航中会反复出现，
+ * 缓存最近一次结果可省掉 Base64 + TextDecoder + JSON.parse。
+ * 返回值始终是副本，避免调用方修改缓存对象。
+ */
+let cachedEncodedTabInfo = ''
+let cachedTabInfo: ITabBase | null = null
+
+export const decodeTabInfo = (encoded: string): ITabBase => {
+  if (encoded === cachedEncodedTabInfo && cachedTabInfo) {
+    return { ...cachedTabInfo }
+  }
+
+  const decoded = decodeTabInfoUncached(encoded)
+  cachedEncodedTabInfo = encoded
+  cachedTabInfo = decoded
+  return { ...decoded }
+}
+
+/**
+ * 生成运行时 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()

package/src/lib/utils/urlParser.ts

@@ -44,15 +44,6 @@ export function isAllowedTabUrl(url: string): boolean {
   }
 }
 
-/**
- * 判断是否为不允许嵌入 iframe 的 URL
- * @param url - 待检查的 URL 字符串
- * @returns 非 allowlist URL 返回 true
- */
-export function isInvalidIframeUrl(url: string): boolean {
-  return !isAllowedTabUrl(url)
-}
-
 /** 非法 URL 降级为 about:blank，避免进入 iframe/window.open 等 URL sink */
 export function toSafeTabUrl(url: string): string {
   return isAllowedTabUrl(url) ? url : 'about:blank'
@@ -68,28 +59,42 @@ export function decodeSafeTabUrl(encodedUrl: unknown): string {
 }
 
 /**
- * 判断 URL 是否为跨域（相对路径或同源视为同域）
+ * 判断 URL 是否为跨域（相对路径或同源视为同域）。
+ *
+ * 统一用 `new URL(url, origin)` 解析，协议相对 URL（`//host/path`）也会按实际
+ * origin 判定，避免被误判为同源。`about:blank` 与相对路径视为同源。
  * @param url - 待检查的 URL
  */
 export function isCrossOriginUrl(url: string): boolean {
-  if (!url || !/^https?:\/\//i.test(url)) return false
+  if (!url) return false
+  const base = getUrlBase()
   try {
-    const cur = typeof window !== 'undefined' ? window.location : { origin: 'http://localhost' }
-    const u = new URL(url, cur.origin)
-    return u.origin !== cur.origin
+    const parsed = new URL(url, base)
+    // 非 http(s) 不是「跨域」，而是非法 URL；由 isAllowedTabUrl 负责拒绝。
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
+    return parsed.origin !== new URL(base).origin
   } catch {
     return true
   }
 }
 
 /**
- * 解析 URL 字符串为 path 和 query
- * @param uri 完整 URL 或 path?query 字符串
+ * 解析 URL 字符串为 path、query 和 hash。
+ *
+ * hash 会先从 query 中剥离，避免 `/page?x=1#section` 被解析成 `query.x = '1#section'`。
+ * @param uri 完整 URL 或 path?query#hash 字符串
  */
-export function parseUrl(uri: string): { path: string; query: LocationQueryRaw } {
-  const [pathPart = '', queryPart] = uri.split('?')
+export function parseUrl(uri: string): {
+  path: string
+  query: LocationQueryRaw
+  hash: string
+} {
+  const hashIndex = uri.indexOf('#')
+  const hash = hashIndex >= 0 ? uri.slice(hashIndex) : ''
+  const withoutHash = hashIndex >= 0 ? uri.slice(0, hashIndex) : uri
+  const [pathPart = '', queryPart] = withoutHash.split('?')
   if (queryPart === undefined) {
-    return { path: pathPart, query: {} }
+    return { path: pathPart, query: {}, hash }
   }
 
   const params = new URLSearchParams(queryPart)
@@ -102,7 +107,17 @@ export function parseUrl(uri: string): { path: string; query: LocationQueryRaw }
     }
     query[key] = Array.isArray(existing) ? [...existing, value] : [existing, value]
   }
-  return { path: pathPart, query }
+  return { path: pathPart, query, hash }
+}
+
+/**
+ * 规范化 pathname：去掉末尾多余斜杠（根路径 `/` 保留）。
+ * 页面栈比较与写入统一使用，避免 `/list` 与 `/list/` 被当成两个页面。
+ */
+export function normalizePathname(path: string): string {
+  if (!path || path === '/') return path
+  const normalized = path.replace(/\/+$/, '')
+  return normalized || '/'
 }
 
 /** 浅克隆 LocationQueryRaw，避免引用共享导致的副作用 */
@@ -128,39 +143,51 @@ export function clonePage<T extends CloneablePage>(page: T): T {
   }
 }
 
-/** 忽略 __tab/__src/_back 等内部保留 key 后比较两个 query 是否等价 */
+/** 判断 key 是否为 vue-stack-tabs 内部保留参数（含后退参数 _back） */
+const isIgnoredQueryKey = (key: string): boolean =>
+  STACK_TABS_RESERVED_QUERY_KEYS.has(key) || key === '_back'
+
+/** 比较两个 query 值：数组按元素逐个比较，标量按字符串比较，并区分数组与标量 */
+const isSameQueryValue = (a: LocationQueryRaw[string], b: LocationQueryRaw[string]): boolean => {
+  const isArrayA = Array.isArray(a)
+  const isArrayB = Array.isArray(b)
+  if (isArrayA || isArrayB) {
+    if (!isArrayA || !isArrayB || a.length !== b.length) return false
+    for (let index = 0; index < a.length; index++) {
+      const itemA = a[index]
+      const itemB = b[index]
+      if (itemA !== itemB && String(itemA ?? '') !== String(itemB ?? '')) return false
+    }
+    return true
+  }
+  // 绝大多数 query 值是字符串：先做值直比，避免每次都 String() 分配。
+  return a === b || String(a ?? '') === String(b ?? '')
+}
+
+/**
+ * 忽略 __tab/__src/_back 等内部保留 key 后比较两个 query 是否等价。
+ *
+ * 直接按键逐一比较，不构造中间对象；同时要求 key 集合完全一致
+ * （旧实现只比较 key 数量，`{ a: '' }` 与 `{ b: '' }` 会被误判为相等）。
+ */
 export function isSameQueryIgnoringReserved(
   a: LocationQueryRaw = {},
   b: LocationQueryRaw = {}
 ): boolean {
-  const clean = (q: LocationQueryRaw): Record<string, string | string[]> => {
-    const result: Record<string, string | string[]> = {}
-    for (const [key, value] of Object.entries(q)) {
-      if (STACK_TABS_RESERVED_QUERY_KEYS.has(key) || key === '_back') continue
-      result[key] = Array.isArray(value)
-        ? value.map((item) => String(item ?? ''))
-        : String(value ?? '')
-    }
-    return result
+  let countA = 0
+  for (const key of Object.keys(a)) {
+    if (isIgnoredQueryKey(key)) continue
+    countA++
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false
+    if (!isSameQueryValue(a[key], b[key])) return false
   }
-  const ca = clean(a)
-  const cb = clean(b)
-  const keysA = Object.keys(ca)
-  const keysB = Object.keys(cb)
-  if (keysA.length !== keysB.length) return false
-  return keysA.every((key) => {
-    const aValue = ca[key]
-    const bValue = cb[key]
-    if (Array.isArray(aValue) || Array.isArray(bValue)) {
-      return (
-        Array.isArray(aValue) &&
-        Array.isArray(bValue) &&
-        aValue.length === bValue.length &&
-        aValue.every((value, index) => value === bValue[index])
-      )
-    }
-    return aValue === bValue
-  })
+
+  let countB = 0
+  for (const key of Object.keys(b)) {
+    if (isIgnoredQueryKey(key)) continue
+    countB++
+  }
+  return countA === countB
 }
 
 /** 移除 query 中的 vue-stack-tabs 保留参数（__tab、__src），返回干净的 query */