vue-stack-tabs 1.1.0 → 1.3.0

package/README.md

@@ -1,5 +1,7 @@
 # vue-stack-tabs
 
+**中文** | [English](./README.en.md) | [Русский](./README.ru.md)
+
 > Vue 3 多标签页管理库，基于 Vue Router。用 Vue 作用域实现类似 iframe TabPanel 的效果——**每个 Tab 间组件作用域互不干扰**。
 
 ## ✨ 特性
@@ -36,7 +38,7 @@ pnpm add vue-stack-tabs
 // main.ts
 import { createApp } from 'vue'
 import VueStackTabs from 'vue-stack-tabs'
-import 'vue-stack-tabs/dist/vue-stack-tabs.css'
+import 'vue-stack-tabs/dist/style.css'
 import App from './App.vue'
 import router from './router'
 
@@ -46,6 +48,8 @@ app.use(VueStackTabs)
 app.mount('#app')
 ```
 
+> `vue-stack-tabs` 每个 Vue app 只支持一个 `<VueStackTabs>` 实例。默认导入 `VueStackTabs` 是 Vue plugin，用于 `app.use(VueStackTabs)`；如果需要本地组件导入，请使用 named export。
+
 ### 2. 配置路由
 
 标签页依赖 Vue Router，需要一个承载 `<VueStackTabs>` 的父路由：
@@ -98,6 +102,12 @@ const defaultTabs: ITabData[] = [
 </script>
 ```
 
+如果需要本地组件导入，推荐使用 `VueStackTabs` named export；`StackTab` named export 会继续保留作为兼容别名：
+
+```ts
+import { VueStackTabs as VueStackTabsComponent } from 'vue-stack-tabs'
+```
+
 ### 4. 打开标签
 
 ```ts
@@ -133,7 +143,7 @@ export default defineNuxtConfig({
   vueStackTabs: {
     locale: 'zh-CN'
   },
-  css: ['vue-stack-tabs/dist/vue-stack-tabs.css']
+  css: ['vue-stack-tabs/dist/style.css']
 })
 ```
 
@@ -173,6 +183,54 @@ const { openTab } = useTabActions()
 
 ---
 
+## ESM-only 与 iframe bridge 子入口
+
+`vue-stack-tabs` 从当前版本开始只承诺 ESM import，不再支持 `require('vue-stack-tabs')`。
+
+主应用中继续使用 root 入口：
+
+```ts
+import VueStackTabs from 'vue-stack-tabs'
+import 'vue-stack-tabs/dist/style.css'
+```
+
+iframe 内部页面建议使用无样式副作用的子入口：
+
+```ts
+import { postOpenTab, onRefreshRequest } from 'vue-stack-tabs/iframe-bridge'
+
+postOpenTab(
+  { title: '订单详情', path: '/orders/1' },
+  { targetOrigin: 'https://parent.example.com' }
+)
+
+const off = onRefreshRequest(() => window.location.reload(), {
+  allowedOrigins: ['https://parent.example.com']
+})
+```
+
+默认未传 `targetOrigin` 时使用 iframe 页面自身的 `window.location.origin`，适合同源父页面；跨域父页面必须显式传 `targetOrigin`。生产环境建议同时显式传入 `targetOrigin` 和 `allowedOrigins`。
+
+---
+
+## iframe 安全策略
+
+`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，但这会降低隔离强度。
+
+---
+
 ## 📖 API 参考
 
 ### useTabActions
@@ -199,7 +257,7 @@ const {
 | `openTab(tab, renew?)` | 打开新标签。`renew=true` 时若已存在则清空页面栈后重新打开 |
 | `closeTab(id)`         | 关闭指定标签，返回新激活的标签 ID                         |
 | `closeAllTabs()`       | 关闭所有可关闭标签                                        |
-| `refreshTab(id)`       | 刷新指定标签（替换 ULID，重建组件实例）                   |
+| `refreshTab(id)`       | 刷新指定标签（替换缓存 ID，重建组件实例）                   |
 | `refreshAllTabs()`     | 刷新所有标签                                              |
 | `activeTab(id)`        | 激活指定标签（切换 Tab）                                  |
 | `reset()`              | 关闭所有标签并重置状态                                    |
@@ -283,22 +341,26 @@ fetchData().finally(() => closeTabLoading())
 
 `<VueStackTabs>` 组件属性：
 
-| Prop                   | 类型                        | 默认值                  | 说明                                              |
-| ---------------------- | --------------------------- | ----------------------- | ------------------------------------------------- |
-| `iframePath`           | `string`                    | **必填**                | iframe 占位路由的路径                             |
-| `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 的来源列表                |
+| 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 的来源列表                      |
 
 ---
 
@@ -323,38 +385,76 @@ openTab({
 })
 ```
 
-### iframe 内页面打开标签
+### iframe 页面内操作
+
+在 iframe 标签页内，可以通过 `postMessage` 与宿主容器进行通信，实现打开新标签或响应刷新操作。
 
-在 iframe 内的页面中，可以通过 `postMessage` 打开宿主的标签：
+#### 1. 使用 Bridge 工具（推荐）
+
+如果 iframe 内页能引用库代码，推荐使用无样式副作用的 `vue-stack-tabs/iframe-bridge` 子入口：
 
 ```ts
-import { postOpenTab } from 'vue-stack-tabs'
+import { postOpenTab, onRefreshRequest } from 'vue-stack-tabs/iframe-bridge'
 
-// 在 iframe 内调用
-postOpenTab({
-  title: '新页面',
-  path: '/detail',
-  query: { id: '1' }
-})
-```
+const parentOrigin = 'https://parent.example.com'
 
-### iframe 刷新
+// 打开标签
+postOpenTab(
+  {
+    title: '新页面',
+    path: '/detail',
+    query: { id: '1' }
+  },
+  { targetOrigin: parentOrigin }
+)
+
+// 监听刷新请求
+const off = onRefreshRequest(
+  () => {
+    // 自定义刷新逻辑
+    location.reload()
+  },
+  { allowedOrigins: [parentOrigin] }
+)
+```
 
-iframe 刷新有两种模式：
+#### 2. 原生对接方式
 
-- `postMessage`（默认）：向 iframe 发送消息，由内页自行刷新
-- `reload`：重建 iframe DOM（适用于跨域页面）
+如果无法引入库工具，或希望保持零依赖，可以使用原生 API。生产环境必须使用明确的父页面 origin，并校验刷新消息来源。`postOpenTab` 的默认 `targetOrigin` 是 iframe 页面的 `window.location.origin`，跨域父页面必须显式传入父页面 origin：
 
 ```ts
-// iframe 内页面监听刷新请求
-import { onRefreshRequest } from 'vue-stack-tabs'
+const parentOrigin = 'https://parent.example.com'
 
-onRefreshRequest(() => {
-  // 执行刷新逻辑
-  location.reload()
+// 打开标签
+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 刷新模式
+
+在 `openTab` 时可通过 `iframeRefreshMode` 指定刷新行为：
+
+- `postMessage`（默认）：宿主向 iframe 发送 `vue-stack-tabs:refresh` 消息，由内页自行决定如何刷新（动画更丝滑）。
+- `reload`：宿主直接重置 iframe 的 `src` 或 `key` 触发浏览器强制重载（适用于跨域或无法修改代码的页面）。
+
 ---
 
 ## 🌍 国际化
@@ -388,7 +488,7 @@ app.use(VueStackTabs, [
 ```ts
 /** 打开标签时传入的数据 */
 interface ITabData {
-  id?: string // 标签 ID（不传则自动生成 ULID）
+  id?: string // 标签 ID（不传则自动生成 UUID）
   title: string // 标签标题
   path: string // 路由路径或 iframe URL
   query?: Record<string, string> // 路由参数