vue-stack-tabs 1.0.1 → 1.3.0

package/README.md

@@ -1,56 +1,38 @@
-# Vue Stack Tabs
+# vue-stack-tabs
 
-[![npm version](https://img.shields.io/npm/v/vue-stack-tabs.svg)](https://www.npmjs.com/package/vue-stack-tabs)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+**中文** | [English](./README.en.md) | [Русский](./README.ru.md)
 
-A multi-tab management library for Vue 3 and Vue Router. Each tab has its own component stack with isolated scope, suitable for admin dashboards, multi-tab workspaces, and similar scenarios.
+> Vue 3 多标签页管理库，基于 Vue Router。用 Vue 作用域实现类似 iframe TabPanel 的效果——**每个 Tab 间组件作用域互不干扰**。
 
-基于 Vue 3 和 Vue Router 的多标签页管理库。每个标签拥有独立的组件栈，作用域互不干扰，适合后台管理、多页签工作台等场景。
+## ✨ 特性
 
----
-
-## Table of Contents / 目录
-
-- [Features / 特性](#features--特性)
-- [Installation / 安装](#installation--安装)
-- [Quick Start / 快速开始](#quick-start--快速开始)
-- [Props / 属性](#props--属性)
-- [API](#api)
-- [Nuxt](#nuxt)
-- [iframe & PostMessage](#iframe--postmessage)
-- [i18n / 国际化](#i18n--国际化)
-- [Sub-routes / 子路由](#sub-routes-experimental--子路由试验性)
-- [完整中文说明](#完整中文说明)
-- [License / 许可证](#license--许可证)
-
----
-
-## Features / 特性
-
-- **Route-based & iframe tabs** — Tab pages from Vue Router routes or embedded iframes
-- **Tab operations** — Add, close, refresh, batch close (all / left / right / others)
-- **Stack navigation** — Forward / backward within a tab
-- **Scroll position** — Remember and restore scroll per page
-- **Session recovery** — Restore last active tab on refresh
-- **Nuxt 3/4 module** — Official Nuxt integration
+- 🗂️ **路由级标签页** — 每个标签拥有独立的组件和缓存
+- 📚 **栈式页内导航** — 标签内支持 forward / backward，类似浏览器历史栈
+- 🔄 **标签刷新** — 单个刷新或全部刷新，完全重建组件实例
+- 🌐 **iframe 标签** — 支持嵌入 iframe 页面，postMessage 通信
+- 💾 **Session 持久化** — 浏览器刷新后恢复上次激活的标签
+- 📜 **滚动位置记忆** — 切换标签后自动恢复上次滚动位置
+- 🎨 **右键菜单** — 内置关闭/刷新操作
+- 🌍 **国际化** — 内置中英文，可扩展
+- 📦 **Nuxt 3/4 模块** — 开箱即用
 
 ---
 
-## Installation / 安装
+## 📦 安装
 
 ```bash
-pnpm add vue-stack-tabs
-# or
+# npm
 npm install vue-stack-tabs
-```
 
-**Peer dependencies:** Vue 3, Vue Router 5.x
+# pnpm
+pnpm add vue-stack-tabs
+```
 
 ---
 
-## Quick Start / 快速开始
+## 🚀 快速接入（Vue 3）
 
-### Vue
+### 1. 注册插件
 
 ```ts
 // main.ts
@@ -66,155 +48,93 @@ app.use(VueStackTabs)
 app.mount('#app')
 ```
 
-```vue
-<!-- App.vue or layout -->
-<template>
-  <vue-stack-tabs iframe-path="/iframe" />
-</template>
-```
-
-Configure the iframe route to match `iframe-path` (see [Route config](#route-config--路由配置)).
+> `vue-stack-tabs` 每个 Vue app 只支持一个 `<VueStackTabs>` 实例。默认导入 `VueStackTabs` 是 Vue plugin，用于 `app.use(VueStackTabs)`；如果需要本地组件导入，请使用 named export。
 
-### Route Config / 路由配置
+### 2. 配置路由
 
-The parent route must wrap `<vue-stack-tabs>`, and the iframe path route must be registered.
+标签页依赖 Vue Router，需要一个承载 `<VueStackTabs>` 的父路由：
 
 ```ts
 // router.ts
 import { createRouter, createWebHistory } from 'vue-router'
-import Frame from '@/components/layout/Frame.vue'
-import { IFrame } from 'vue-stack-tabs'
 
 const router = createRouter({
   history: createWebHistory(),
   routes: [
     {
       path: '/',
-      component: Frame,  // contains <vue-stack-tabs>
+      component: () => import('./Layout.vue'),
       children: [
-        { path: '', component: () => import('@/views/home.vue') },
-        { path: 'iframe', component: IFrame },  // must match iframe-path
-        { path: ':pathMatch(.*)', redirect: '/404' }
+        { path: '', component: () => import('./pages/Home.vue') },
+        { path: 'about', component: () => import('./pages/About.vue') },
+        { path: 'settings', component: () => import('./pages/Settings.vue') },
+        // iframe 占位路由（必须）
+        { path: 'iframe', component: () => import('vue-stack-tabs').then((m) => m.IFrame) }
       ]
     }
   ]
 })
-```
-
----
-
-## Props / 属性
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `defaultTabs` | `ITabData[]` | `[]` | Initial tabs |
-| `max` | `number` | `20` | Max open tabs |
-| `iframePath` | `string` | — | iframe route path **(required)** |
-| `iframeAllowedOrigins` | `string[]` | `[]` | Origins allowed for postMessage `openTab` |
-| `pageTransition` | `string` | `stack-tab-swap` | Page transition name |
-| `tabTransition` | `string` | `stack-tab-zoom` | Tab transition name |
-| `tabScrollMode` | `'wheel' \| 'button' \| 'both'` | `both` | Tab bar scroll mode |
-| `width` / `height` | `string` | `100%` | Component size |
-| `i18n` | `string` | `zh-CN` | Locale (`zh-CN` \| `en`) |
-| `space` | `number` | `300` | Tab scroll step (px) |
-| `globalScroll` | `boolean` | `false` | Use page-level scroll |
-| `contextmenu` | `boolean \| object` | `true` | Right-click menu |
-| `sessionPrefix` | `string` | `''` | Prefix for sessionStorage key |
 
----
+export default router
+```
 
-## API
+### 3. 使用组件
 
-### useTabActions
+```vue
+<!-- Layout.vue -->
+<template>
+  <div style="width: 100%; height: 100vh">
+    <VueStackTabs iframe-path="/iframe" :default-tabs="defaultTabs" :max="20" :contextmenu="true" />
+  </div>
+</template>
 
-```ts
-import { useTabActions } from 'vue-stack-tabs'
+<script setup lang="ts">
+import type { ITabData } from 'vue-stack-tabs'
 
-const {
-  openTab,
-  closeTab,
-  closeAllTabs,
-  refreshTab,
-  refreshAllTabs,
-  activeTab,
-  reset,
-  tabs,
-  openInNewWindow
-} = useTabActions()
+const defaultTabs: ITabData[] = [
+  {
+    title: '首页',
+    path: '/',
+    closable: false,
+    refreshable: true
+  }
+]
+</script>
 ```
 
-| Method | Description |
-|--------|-------------|
-| `openTab(tab, renew?)` | Open tab. `renew=true` clears stack and reopens |
-| `closeTab(id)` | Close tab |
-| `closeAllTabs()` | Close all tabs |
-| `refreshTab(id)` | Refresh current page of tab |
-| `refreshAllTabs()` | Refresh all tabs |
-| `activeTab(id, isRoute?)` | Activate tab |
-| `reset()` | Reset all tabs |
-| `openInNewWindow(id)` | Open iframe tab in new window (fallback) |
-
-**openTab(tab: ITabData)**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | `string` | No | Tab id (auto-generated if omitted) |
-| `title` | `string` | Yes | Tab title |
-| `path` | `string` | Yes | Route path or iframe URL |
-| `query` | `Record<string, string>` | No | Query params |
-| `iframe` | `boolean` | No | Open as iframe |
-| `iframeRefreshMode` | `'postMessage' \| 'reload'` | No | iframe refresh mode |
-| `closable` | `boolean` | No | Default `true` |
-| `refreshable` | `boolean` | No | Default `true` |
-
-### useTabRouter
-
-Used **inside tab pages** for in-tab navigation.
+如果需要本地组件导入，推荐使用 `VueStackTabs` named export；`StackTab` named export 会继续保留作为兼容别名：
 
 ```ts
-import { useTabRouter } from 'vue-stack-tabs'
-
-const { forward, backward, addScrollTarget } = useTabRouter()
-
-// Forward: push new page
-forward({ path: '/detail', query: { id: '1' } })
-
-// Backward: pop stack
-backward('/list')           // back to first matching path
-backward(1)                 // back 1 step
-backward(2, { foo: 'bar' }) // back 2 steps, pass query to target
-
-// Register scroll containers for position restore
-addScrollTarget('.scroll-area', '#panel')
+import { VueStackTabs as VueStackTabsComponent } from 'vue-stack-tabs'
 ```
 
-### useTabLoading
+### 4. 打开标签
 
 ```ts
-import { useTabLoading } from 'vue-stack-tabs'
+import { useTabActions } from 'vue-stack-tabs'
 
-const { openTabLoading, closeTabLoading } = useTabLoading()
-```
+const { openTab, closeTab, refreshTab } = useTabActions()
 
-### Initial Tabs / 初始化页签
+// 打开新标签
+openTab({
+  id: 'about', // 可选，不传则自动生成
+  title: '关于',
+  path: '/about',
+  query: { id: '1' } // 可选
+})
 
-```vue
-<vue-stack-tabs
-  iframe-path="/iframe"
-  :default-tabs="[
-    { id: 'home', title: 'Home', path: '/', closable: false },
-    { title: 'About', path: '/about' }
-  ]"
-/>
-```
+// 关闭标签
+closeTab('about')
 
-> The first tab should be non-closable (`closable: false`).
+// 刷新标签
+refreshTab('about')
+```
 
 ---
 
-## Nuxt
+## 🚀 快速接入（Nuxt 3/4）
 
-### Module (recommended)
+### 1. 注册模块
 
 ```ts
 // nuxt.config.ts
@@ -222,496 +142,393 @@ export default defineNuxtConfig({
   modules: ['vue-stack-tabs/nuxt'],
   vueStackTabs: {
     locale: 'zh-CN'
-  }
+  },
+  css: ['vue-stack-tabs/dist/style.css']
 })
 ```
 
-The module auto-imports `useTabActions`, `useTabRouter`, `useTabLoading`.
-
-### iframe route in Nuxt
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  hooks: {
-    'pages:extend'(pages) {
-      pages.push({
-        name: 'iframe',
-        path: '/iframe',
-        file: '~/components/IFrame.vue'  // minimal component with useTabRouter()
-      })
-    }
-  }
-})
-```
-
----
-
-## iframe & PostMessage
-
-### Open tab from iframe
-
-```ts
-import { postOpenTab } from 'vue-stack-tabs'
-
-postOpenTab({
-  title: 'New Page',
-  path: '/detail',
-  query: { id: '123' },
-  closable: true,
-  refreshable: true
-})
-```
-
-Parent must allow the iframe origin if cross-origin:
+### 2. 在 Layout 中使用
 
 ```vue
-<vue-stack-tabs
-  iframe-path="/iframe"
-  :iframe-allowed-origins="['https://iframe-origin.com']"
-/>
-```
-
-### Receive refresh in iframe
+<!-- layouts/default.vue -->
+<template>
+  <div style="width: 100%; height: 100vh">
+    <VueStackTabs iframe-path="/iframe" :default-tabs="defaultTabs" />
+  </div>
+</template>
 
-```ts
-import { onRefreshRequest } from 'vue-stack-tabs'
-import { onUnmounted } from 'vue'
+<script setup lang="ts">
+import type { ITabData } from 'vue-stack-tabs'
 
-const unlisten = onRefreshRequest()  // defaults to location.reload()
-onUnmounted(unlisten)
+const defaultTabs: ITabData[] = [{ title: '首页', path: '/', closable: false, refreshable: true }]
+</script>
 ```
 
-### Cross-origin iframe (reload mode)
+### 3. 页面中使用
 
-When the iframe is cross-origin and you cannot modify its code:
+```vue
+<!-- pages/index.vue -->
+<template>
+  <div>
+    <h1>首页</h1>
+    <button @click="openTab({ title: '关于', path: '/about' })">打开关于页</button>
+  </div>
+</template>
 
-```ts
-openTab({
-  title: 'External',
-  path: 'https://example.com',
-  iframe: true,
-  iframeRefreshMode: 'reload'
-})
+<script setup>
+import { useTabActions } from 'vue-stack-tabs'
+const { openTab } = useTabActions()
+</script>
 ```
 
 ---
 
-## i18n / 国际化
+## ESM-only 与 iframe bridge 子入口
 
-Built-in: `zh-CN`, `en`.
+`vue-stack-tabs` 从当前版本开始只承诺 ESM import，不再支持 `require('vue-stack-tabs')`。
 
-```vue
-<vue-stack-tabs iframe-path="/iframe" i18n="zh-CN" />
-```
-
-### Custom messages
+主应用中继续使用 root 入口：
 
 ```ts
-app.use(VueStackTabs, [{
-  locale: 'zh-CN',
-  messages: {
-    VueStackTab: {
-      close: 'Close',
-      closeLefts: 'Close left',
-      closeRights: 'Close right',
-      closeOthers: 'Close others',
-      closeAll: 'Close all',
-      reload: 'Reload',
-      reloadAll: 'Reload all',
-      maximum: 'Maximize',
-      restore: 'Restore',
-      undefined: 'Undefined',
-      loading: 'Loading',
-      openInNewWindow: 'Open in new window'
-    }
-  }
-}])
+import VueStackTabs from 'vue-stack-tabs'
+import 'vue-stack-tabs/dist/style.css'
 ```
 
----
-
-## Slots
+iframe 内部页面建议使用无样式副作用的子入口：
 
-| Slot | Description |
-|------|-------------|
-| `leftButton` | Left side of tab bar |
-| `rightButton` | Right side of tab bar |
+```ts
+import { postOpenTab, onRefreshRequest } from 'vue-stack-tabs/iframe-bridge'
 
----
+postOpenTab(
+  { title: '订单详情', path: '/orders/1' },
+  { targetOrigin: 'https://parent.example.com' }
+)
 
-## Events
+const off = onRefreshRequest(() => window.location.reload(), {
+  allowedOrigins: ['https://parent.example.com']
+})
+```
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `onActive` | `id: string` | Fired when a tab is activated |
-| `onPageLoaded` | — | Fired when page component is loaded |
+默认未传 `targetOrigin` 时使用 iframe 页面自身的 `window.location.origin`，适合同源父页面；跨域父页面必须显式传 `targetOrigin`。生产环境建议同时显式传入 `targetOrigin` 和 `allowedOrigins`。
 
 ---
 
-## Exports
+## iframe 安全策略
 
-```ts
-import VueStackTabs, {
-  useTabActions,
-  useTabRouter,
-  useTabLoading,
-  TabHeaderButton,
-  IFrame,
-  postOpenTab,
-  onRefreshRequest,
-  MSG_REFRESH,
-  MSG_OPEN_TAB
-} from 'vue-stack-tabs'
-import type { ITabData, ITabBase, IframeOpenTabPayload } from 'vue-stack-tabs'
+`VueStackTabs` 支持配置 iframe 安全属性：
+
+```vue
+<VueStackTabs
+  iframe-path="/__iframe"
+  iframe-sandbox="allow-scripts allow-forms allow-popups allow-downloads allow-same-origin"
+  iframe-referrer-policy="strict-origin-when-cross-origin"
+  iframe-allow="fullscreen"
+  :iframe-load-timeout="15000"
+/>
 ```
 
+默认 sandbox 保留常见业务页面能力，属于兼容优先，不是强隔离；强隔离请移除 `allow-same-origin`，并按业务能力继续减少 sandbox token。如果你的同源业务页面确实不能在 sandbox 下工作，可以传入空字符串关闭 sandbox，但这会降低隔离强度。
+
 ---
 
-## Sub-routes (Experimental / 子路由试验性)
+## 📖 API 参考
 
-Nested routes with `children` and `forward`/`backward` are supported. See [SUBROUTE_EXPERIMENTAL.md](./docs/SUBROUTE_EXPERIMENTAL.md) for details. This feature is experimental.
+### useTabActions
 
----
+标签级操作封装。
 
-## Development / 开发
+```ts
+import { useTabActions } from 'vue-stack-tabs'
 
-```bash
-pnpm install
-pnpm run dev        # Demo app
-pnpm run test       # Unit tests
-pnpm run test:prepack   # Pre-pack: unit + Vue + Nuxt (source)
-pnpm run test:packaged # Post-pack: Vue + Nuxt (dist)
-pnpm run docs:dev   # Docs preview
+const {
+  openTab, // (tab: ITabData, renew?: boolean) => Promise<string>
+  closeTab, // (id: string) => string
+  closeAllTabs, // () => void
+  refreshTab, // (id: string) => void
+  refreshAllTabs, // () => void
+  activeTab, // (id: string, isRoute?: boolean) => void
+  reset, // () => void
+  tabs // Ref<ITabItem[]>
+} = useTabActions()
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). [AGENTS.md](./AGENTS.md) for AI assistants.
+| 方法                   | 说明                                                      |
+| ---------------------- | --------------------------------------------------------- |
+| `openTab(tab, renew?)` | 打开新标签。`renew=true` 时若已存在则清空页面栈后重新打开 |
+| `closeTab(id)`         | 关闭指定标签，返回新激活的标签 ID                         |
+| `closeAllTabs()`       | 关闭所有可关闭标签                                        |
+| `refreshTab(id)`       | 刷新指定标签（替换缓存 ID，重建组件实例）                   |
+| `refreshAllTabs()`     | 刷新所有标签                                              |
+| `activeTab(id)`        | 激活指定标签（切换 Tab）                                  |
+| `reset()`              | 关闭所有标签并重置状态                                    |
 
 ---
 
-## 完整中文说明
+### useTabRouter
 
-### 安装与引入
+标签内栈式导航，**只能在标签内的页面组件中使用**。
 
 ```ts
-// main.ts
-import { createApp } from 'vue'
-import VueStackTabs from 'vue-stack-tabs'
-import 'vue-stack-tabs/dist/style.css'
-import App from './App.vue'
-import router from './router'
-
-const app = createApp(App)
-app.use(router)
-app.use(VueStackTabs)
-app.mount('#app')
-```
-
-**依赖：** Vue 3、Vue Router 5.x
-
-### 快速开始
+import { useTabRouter } from 'vue-stack-tabs'
 
-```vue
-<!-- App.vue 或布局组件 -->
-<template>
-  <vue-stack-tabs iframe-path="/iframe" />
-</template>
+const { forward, backward, addScrollTarget } = useTabRouter()
 ```
 
-父路由需包裹 `<vue-stack-tabs>`，并注册与 `iframe-path` 一致的 iframe 路由。
+| 方法                        | 说明                              |
+| --------------------------- | --------------------------------- |
+| `forward(to)`               | 在当前标签内前进到新页面          |
+| `backward(to, backQuery?)`  | 在当前标签内后退                  |
+| `addScrollTarget(selector)` | 注册需要记忆滚动位置的 DOM 选择器 |
 
-### 路由配置
+#### forward
 
 ```ts
-// router.ts
-import { createRouter, createWebHistory } from 'vue-router'
-import Frame from '@/components/layout/Frame.vue'
-import { IFrame } from 'vue-stack-tabs'
+// 前进到 /detail 页面
+forward({ path: '/detail', query: { id: '123' } })
 
-const router = createRouter({
-  history: createWebHistory(),
-  routes: [
-    {
-      path: '/',
-      component: Frame,  // 内部包含 <vue-stack-tabs>
-      children: [
-        { path: '', component: () => import('@/views/home.vue') },
-        { path: 'iframe', component: IFrame },  // 需与 iframe-path 一致
-        { path: ':pathMatch(.*)', redirect: '/404' }
-      ]
-    }
-  ]
-})
+// 循环压栈自身（同路由可多次入栈，每次创建独立缓存）
+forward({ path: '/list', query: { page: '2' } })
 ```
 
-### 属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `defaultTabs` | `ITabData[]` | `[]` | 初始页签 |
-| `max` | `number` | `20` | 最大打开数量 |
-| `iframePath` | `string` | — | iframe 路由路径 **（必填）** |
-| `iframeAllowedOrigins` | `string[]` | `[]` | 允许 postMessage 调用 openTab 的 iframe 来源 |
-| `pageTransition` | `string` | `stack-tab-swap` | 页面转场效果 |
-| `tabTransition` | `string` | `stack-tab-zoom` | 标签转场效果 |
-| `tabScrollMode` | `'wheel' \| 'button' \| 'both'` | `both` | 标签栏滚动方式 |
-| `width` / `height` | `string` | `100%` | 组件尺寸 |
-| `i18n` | `string` | `zh-CN` | 语言（`zh-CN` \| `en`） |
-| `space` | `number` | `300` | 标签滚动步长（px） |
-| `globalScroll` | `boolean` | `false` | 是否使用页面级滚动 |
-| `contextmenu` | `boolean \| object` | `true` | 右键菜单 |
-| `sessionPrefix` | `string` | `''` | sessionStorage key 前缀 |
-
-### API
-
-#### useTabActions
+#### backward
 
 ```ts
-import { useTabActions } from 'vue-stack-tabs'
+// 后退 1 步（默认）
+backward(1)
 
-const {
-  openTab,
-  closeTab,
-  closeAllTabs,
-  refreshTab,
-  refreshAllTabs,
-  activeTab,
-  reset,
-  tabs,
-  openInNewWindow
-} = useTabActions()
-```
+// 后退 N 步
+backward(3)
 
-| 方法 | 说明 |
-|------|------|
-| `openTab(tab, renew?)` | 打开标签；`renew=true` 时清空栈并重新打开 |
-| `closeTab(id)` | 关闭指定标签 |
-| `closeAllTabs()` | 关闭所有标签 |
-| `refreshTab(id)` | 刷新指定标签当前页 |
-| `refreshAllTabs()` | 刷新所有标签 |
-| `activeTab(id, isRoute?)` | 激活指定标签 |
-| `reset()` | 重置所有标签 |
-| `openInNewWindow(id)` | iframe 标签在新窗口打开（无法嵌入时降级） |
-
-**openTab(tab: ITabData)**
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `id` | `string` | 否 | 标签 id，不填则自动生成 |
-| `title` | `string` | 是 | 标签名称 |
-| `path` | `string` | 是 | 路由路径或 iframe URL |
-| `query` | `Record<string, string>` | 否 | 查询参数 |
-| `iframe` | `boolean` | 否 | 是否以 iframe 打开 |
-| `iframeRefreshMode` | `'postMessage' \| 'reload'` | 否 | iframe 刷新方式 |
-| `closable` | `boolean` | 否 | 默认 `true` |
-| `refreshable` | `boolean` | 否 | 默认 `true` |
-
-#### useTabRouter
-
-在**标签内的页面**中使用，用于标签内前进/后退。
+// 回退到指定路径（自动从栈中查找）
+backward('/list')
 
-```ts
-import { useTabRouter } from 'vue-stack-tabs'
+// 带参回退（目标页通过 props._back 接收）
+backward('/list', { result: 'success', data: { id: 1 } })
+```
 
-const { forward, backward, addScrollTarget } = useTabRouter()
+**目标页接收参数：**
 
-// 前进：入栈新页面
-forward({ path: '/detail', query: { id: '1' } })
+```vue
+<script setup>
+// 声明 props 接收后退参数
+defineProps<{ _back?: { result: string; data: any } }>()
+</script>
+```
 
-// 后退：出栈
-backward('/list')           // 回退到首个匹配路径
-backward(1)                 // 回退 1 步
-backward(2, { foo: 'bar' }) // 回退 2 步，并向目标页传递 query
+---
 
-// 注册滚动容器（用于位置记忆与恢复）
-addScrollTarget('.scroll-area', '#panel')
-```
+### useTabLoading
 
-#### useTabLoading
+页面加载状态控制，**只能在标签内的页面组件中使用**。
 
 ```ts
 import { useTabLoading } from 'vue-stack-tabs'
 
 const { openTabLoading, closeTabLoading } = useTabLoading()
-```
 
-#### 初始化页签
+// 显示加载遮罩
+openTabLoading()
 
-```vue
-<vue-stack-tabs
-  iframe-path="/iframe"
-  :default-tabs="[
-    { id: 'home', title: '首页', path: '/', closable: false },
-    { title: '关于', path: '/about' }
-  ]"
-/>
+// 异步操作完成后关闭
+fetchData().finally(() => closeTabLoading())
 ```
 
-> 第一个页签建议设为不可关闭（`closable: false`）。
+> 组件卸载时自动关闭 Loading，无需手动清理。
 
-### Nuxt
+---
 
-#### 模块方式（推荐）
+## ⚙️ Props
+
+`<VueStackTabs>` 组件属性：
+
+| Prop                   | 类型                        | 默认值                                                                     | 说明                                                    |
+| ---------------------- | --------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `iframePath`           | `string`                    | **必填**                                                                   | iframe 占位路由的路径                                   |
+| `iframeSandbox`        | `string`                    | `allow-scripts allow-forms allow-popups allow-downloads allow-same-origin` | iframe sandbox 策略；默认兼容优先不是强隔离，强隔离请移除 `allow-same-origin`；传空字符串可关闭 sandbox（不推荐） |
+| `iframeReferrerPolicy` | `ReferrerPolicy`            | `strict-origin-when-cross-origin`                                          | iframe referrerpolicy 属性                              |
+| `iframeAllow`          | `string`                    | `''`                                                                       | iframe allow 属性，例如 `fullscreen`                    |
+| `iframeLoadTimeout`    | `number`                    | `15000`                                                                    | iframe 加载超时时间，单位 ms                            |
+| `defaultTabs`          | `ITabData[]`                | `[]`                                                                       | 初始标签列表                                            |
+| `max`                  | `number`                    | `20`                                                                       | 最大标签数量                                            |
+| `contextmenu`          | `boolean \| object`         | `true`                                                                     | 是否启用右键菜单                                        |
+| `pageTransition`       | `string`                    | `'stack-tab-swap'`                                                         | 前进时的页面转场动画名                                  |
+| `pageTransitionBack`   | `string`                    | `'stack-tab-swap-back'`                                                    | 后退时的页面转场动画名                                  |
+| `tabTransition`        | `string \| TransitionProps` | `'stack-tab-zoom'`                                                         | 标签增删时的过渡效果                                    |
+| `tabScrollMode`        | `TabScrollMode`             | `'both'`                                                                   | 标签栏滚动方式：`'wheel'` / `'button'` / `'both'`       |
+| `width`                | `string`                    | `'100%'`                                                                   | 容器宽度                                                |
+| `height`               | `string`                    | `'100%'`                                                                   | 容器高度                                                |
+| `i18n`                 | `string`                    | `'zh-CN'`                                                                  | 国际化语言                                              |
+| `globalScroll`         | `boolean`                   | `false`                                                                    | 是否使用页面级滚动记忆                                  |
+| `sessionPrefix`        | `string`                    | `''`                                                                       | sessionStorage 键前缀                                   |
+| `iframeAllowedOrigins` | `string[]`                  | 同源                                                                       | 允许 iframe postMessage 的来源列表                      |
 
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['vue-stack-tabs/nuxt'],
-  vueStackTabs: {
-    locale: 'zh-CN'
-  }
-})
-```
+---
 
-模块会自动导入 `useTabActions`、`useTabRouter`、`useTabLoading`。
+## 🎯 Events
 
-#### Nuxt 中配置 iframe 路由
+| 事件           | 参数           | 说明                   |
+| -------------- | -------------- | ---------------------- |
+| `onActive`     | `(id: string)` | 标签被激活时触发       |
+| `onPageLoaded` | —              | 页面组件加载完成时触发 |
 
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  hooks: {
-    'pages:extend'(pages) {
-      pages.push({
-        name: 'iframe',
-        path: '/iframe',
-        file: '~/components/IFrame.vue'  // 最小组件，含 useTabRouter() 即可
-      })
-    }
-  }
-})
-```
+---
 
-### iframe 与父窗口通信
+## 🖼️ iframe 标签页
 
-#### iframe 内打开新标签
+### 打开 iframe 标签
 
 ```ts
-import { postOpenTab } from 'vue-stack-tabs'
-
-postOpenTab({
-  title: '新页面',
-  path: '/detail',
-  query: { id: '123' },
-  closable: true,
-  refreshable: true
+openTab({
+  title: '外部页面',
+  path: 'https://example.com',
+  iframe: true
 })
 ```
 
-跨域时父应用需配置 `iframeAllowedOrigins`：
+### iframe 页面内操作
 
-```vue
-<vue-stack-tabs
-  iframe-path="/iframe"
-  :iframe-allowed-origins="['https://iframe来源域名']"
-/>
-```
+在 iframe 标签页内，可以通过 `postMessage` 与宿主容器进行通信，实现打开新标签或响应刷新操作。
+
+#### 1. 使用 Bridge 工具（推荐）
 
-#### iframe 内接收刷新指令
+如果 iframe 内页能引用库代码，推荐使用无样式副作用的 `vue-stack-tabs/iframe-bridge` 子入口：
 
 ```ts
-import { onRefreshRequest } from 'vue-stack-tabs'
-import { onUnmounted } from 'vue'
+import { postOpenTab, onRefreshRequest } from 'vue-stack-tabs/iframe-bridge'
 
-const unlisten = onRefreshRequest()  // 默认执行 location.reload()
-onUnmounted(unlisten)
+const parentOrigin = 'https://parent.example.com'
+
+// 打开标签
+postOpenTab(
+  {
+    title: '新页面',
+    path: '/detail',
+    query: { id: '1' }
+  },
+  { targetOrigin: parentOrigin }
+)
+
+// 监听刷新请求
+const off = onRefreshRequest(
+  () => {
+    // 自定义刷新逻辑
+    location.reload()
+  },
+  { allowedOrigins: [parentOrigin] }
+)
 ```
 
-#### 跨域 iframe（reload 模式）
+#### 2. 原生对接方式
 
-若 iframe 为跨域且无法修改其代码，可指定 `iframeRefreshMode: 'reload'`，刷新时直接重载 iframe：
+如果无法引入库工具，或希望保持零依赖，可以使用原生 API。生产环境必须使用明确的父页面 origin，并校验刷新消息来源。`postOpenTab` 的默认 `targetOrigin` 是 iframe 页面的 `window.location.origin`，跨域父页面必须显式传入父页面 origin：
 
 ```ts
-openTab({
-  title: '外部页面',
-  path: 'https://example.com',
-  iframe: true,
-  iframeRefreshMode: 'reload'
+const parentOrigin = 'https://parent.example.com'
+
+// 打开标签
+window.parent.postMessage(
+  {
+    type: 'vue-stack-tabs:openTab',
+    payload: {
+      title: '原生新页面',
+      path: '/detail'
+    }
+  },
+  parentOrigin
+)
+
+// 监听刷新请求
+window.addEventListener('message', (ev) => {
+  if (ev.origin !== parentOrigin) return
+  if (ev.source !== window.parent) return
+  if (ev.data?.type === 'vue-stack-tabs:refresh') {
+    // 执行刷新
+    location.reload()
+  }
 })
 ```
 
-### 国际化
+### iframe 刷新模式
 
-内置 `zh-CN`、`en`。
+在 `openTab` 时可通过 `iframeRefreshMode` 指定刷新行为：
 
-```vue
-<vue-stack-tabs iframe-path="/iframe" i18n="zh-CN" />
+- `postMessage`（默认）：宿主向 iframe 发送 `vue-stack-tabs:refresh` 消息，由内页自行决定如何刷新（动画更丝滑）。
+- `reload`：宿主直接重置 iframe 的 `src` 或 `key` 触发浏览器强制重载（适用于跨域或无法修改代码的页面）。
+
+---
+
+## 🌍 国际化
+
+内置语言：`zh-CN`（中文）、`en-US`（英文）。
+
+```ts
+// 切换语言
+app.use(VueStackTabs, [{ locale: 'en-US' }])
 ```
 
-#### 自定义文案
+自定义语言包：
 
 ```ts
-app.use(VueStackTabs, [{
-  locale: 'zh-CN',
-  messages: {
-    VueStackTab: {
-      close: '关闭',
-      closeLefts: '关闭左侧',
-      closeRights: '关闭右侧',
-      closeOthers: '关闭其他',
-      closeAll: '关闭全部',
-      reload: '刷新',
-      reloadAll: '刷新全部',
-      maximum: '最大化',
-      restore: '还原',
-      undefined: '未定义',
-      loading: '加载中',
-      openInNewWindow: '新窗口打开'
+app.use(VueStackTabs, [
+  {
+    locale: 'ja-JP',
+    messages: {
+      'VueStackTab.close': '閉じる',
+      'VueStackTab.refresh': '更新'
+      // ...
     }
   }
-}])
+])
 ```
 
-### 插槽
-
-| 插槽 | 说明 |
-|------|------|
-| `leftButton` | 标签栏左侧 |
-| `rightButton` | 标签栏右侧 |
-
-### 事件
-
-| 事件 | 参数 | 说明 |
-|------|------|------|
-| `onActive` | `id: string` | 标签被激活时触发 |
-| `onPageLoaded` | — | 页面组件加载完成时触发 |
+---
 
-### 导出
+## 📄 类型定义
 
 ```ts
-import VueStackTabs, {
-  useTabActions,
-  useTabRouter,
-  useTabLoading,
-  TabHeaderButton,
-  IFrame,
-  postOpenTab,
-  onRefreshRequest,
-  MSG_REFRESH,
-  MSG_OPEN_TAB
-} from 'vue-stack-tabs'
-import type { ITabData, ITabBase, IframeOpenTabPayload } from 'vue-stack-tabs'
+/** 打开标签时传入的数据 */
+interface ITabData {
+  id?: string // 标签 ID（不传则自动生成 UUID）
+  title: string // 标签标题
+  path: string // 路由路径或 iframe URL
+  query?: Record<string, string> // 路由参数
+  closable?: boolean // 是否可关闭（默认 true）
+  refreshable?: boolean // 是否可刷新（默认 true）
+  iframe?: boolean // 是否为 iframe 标签（默认 false）
+  iframeRefreshMode?: 'postMessage' | 'reload' // iframe 刷新方式
+}
+
+/** 标签栏滚动模式 */
+enum TabScrollMode {
+  WHEEL = 'wheel',
+  BUTTON = 'button',
+  BOTH = 'both'
+}
 ```
 
-### 子路由（试验性）
-
-支持路由 `children` 与 `forward`/`backward` 多级导航。详见 [SUBROUTE_EXPERIMENTAL.md](./docs/SUBROUTE_EXPERIMENTAL.md)。该功能为试验性。
+---
 
-### 开发
+## 📁 项目结构
 
-```bash
-pnpm install
-pnpm run dev           # 演示应用
-pnpm run test          # 单元测试
-pnpm run test:prepack  # 打包前：单元 + Vue + Nuxt（源码）
-pnpm run test:packaged # 打包后：Vue + Nuxt（dist）
-pnpm run docs:dev      # 文档预览
+```
+src/lib/
+├── StackTabs.vue           # 主组件
+├── index.ts                # 入口与导出
+├── hooks/                  # 核心逻辑
+│   ├── useTabActions.ts    # 对外 API
+│   ├── useTabRouter.ts     # 栈内导航
+│   ├── useTabLoading.ts    # Loading 状态
+│   └── useTabPanel.tsx     # 核心引擎
+├── model/TabModel.ts       # 类型定义
+├── components/             # UI 组件
+├── nuxt/                   # Nuxt 模块
+└── assets/style/           # 样式
 ```
 
-参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。[AGENTS.md](./AGENTS.md) 供 AI 助手参考。
+详细架构设计请参阅 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。
 
 ---
 
-## License / 许可证
+## 📝 License
 
-Apache License 2.0
+[LGPL-2.1](./LICENSE)