vue-stack-tabs 1.0.1 → 1.3.0

package/README.ru.md

@@ -0,0 +1,526 @@
+# vue-stack-tabs
+
+[中文](./README.md) | [English](./README.en.md) | **Русский**
+
+> Библиотека управления вкладками для Vue 3 на основе Vue Router. Реализует поведение TabPanel, аналогичное iframe, с использованием областей видимости Vue — **каждая вкладка имеет изолированную область компонентов**.
+
+## Возможности
+
+- **Вкладки на уровне маршрутов** — каждая вкладка владеет независимыми компонентами и кэшем
+- **Стековая навигация внутри вкладки** — forward / backward внутри вкладки, аналогично стеку истории браузера
+- **Обновление вкладок** — обновление одной или всех вкладок с полной пересборкой экземпляров компонентов
+- **Вкладки iframe** — встраивание iframe-страниц с коммуникацией через postMessage
+- **Сохранение сессии** — восстановление последних активных вкладок после обновления браузера
+- **Запоминание позиции прокрутки** — автоматическое восстановление позиции прокрутки при переключении вкладок
+- **Контекстное меню** — встроенные действия закрытия/обновления
+- **Интернационализация** — встроенные китайский и английский языки, расширяемо
+- **Модуль Nuxt 3/4** — работает из коробки
+
+---
+
+## Установка
+
+```bash
+# npm
+npm install vue-stack-tabs
+
+# pnpm
+pnpm add vue-stack-tabs
+```
+
+---
+
+## Быстрый старт (Vue 3)
+
+### 1. Регистрация плагина
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import VueStackTabs from 'vue-stack-tabs'
+import 'vue-stack-tabs/dist/vue-stack-tabs.css'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+app.use(router)
+app.use(VueStackTabs)
+app.mount('#app')
+```
+
+### 2. Настройка маршрутов
+
+Вкладки зависят от Vue Router. Необходим родительский маршрут для размещения `<VueStackTabs>`:
+
+```ts
+// router.ts
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      component: () => import('./Layout.vue'),
+      children: [
+        { 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) }
+      ]
+    }
+  ]
+})
+
+export default router
+```
+
+### 3. Использование компонента
+
+```vue
+<!-- Layout.vue -->
+<template>
+  <div style="width: 100%; height: 100vh">
+    <VueStackTabs iframe-path="/iframe" :default-tabs="defaultTabs" :max="20" :contextmenu="true" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { ITabData } from 'vue-stack-tabs'
+
+const defaultTabs: ITabData[] = [
+  {
+    title: 'Главная',
+    path: '/',
+    closable: false,
+    refreshable: true
+  }
+]
+</script>
+```
+
+### 4. Открытие вкладок
+
+```ts
+import { useTabActions } from 'vue-stack-tabs'
+
+const { openTab, closeTab, refreshTab } = useTabActions()
+
+// Открыть новую вкладку
+openTab({
+  id: 'about', // необязательно, генерируется автоматически
+  title: 'О приложении',
+  path: '/about',
+  query: { id: '1' } // необязательно
+})
+
+// Закрыть вкладку
+closeTab('about')
+
+// Обновить вкладку
+refreshTab('about')
+```
+
+---
+
+## Быстрый старт (Nuxt 3/4)
+
+### 1. Регистрация модуля
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['vue-stack-tabs/nuxt'],
+  vueStackTabs: {
+    locale: 'en-US'
+  },
+  css: ['vue-stack-tabs/dist/vue-stack-tabs.css']
+})
+```
+
+### 2. Использование в Layout
+
+```vue
+<!-- layouts/default.vue -->
+<template>
+  <div style="width: 100%; height: 100vh">
+    <VueStackTabs iframe-path="/iframe" :default-tabs="defaultTabs" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { ITabData } from 'vue-stack-tabs'
+
+const defaultTabs: ITabData[] = [{ title: 'Главная', path: '/', closable: false, refreshable: true }]
+</script>
+```
+
+### 3. Использование на страницах
+
+```vue
+<!-- pages/index.vue -->
+<template>
+  <div>
+    <h1>Главная</h1>
+    <button @click="openTab({ title: 'О приложении', path: '/about' })">Открыть страницу «О приложении»</button>
+  </div>
+</template>
+
+<script setup>
+import { useTabActions } from 'vue-stack-tabs'
+const { openTab } = useTabActions()
+</script>
+```
+
+---
+
+## ESM-only и суб-вход iframe bridge
+
+`vue-stack-tabs` начиная с текущей версии поддерживает только ESM import; `require('vue-stack-tabs')` больше не поддерживается.
+
+Основное приложение продолжает использовать корневой вход:
+
+```ts
+import VueStackTabs from 'vue-stack-tabs'
+import 'vue-stack-tabs/dist/vue-stack-tabs.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` не указан, по умолчанию используется `window.location.origin` страницы iframe, подходит для родительских страниц с тем же источником; для кросс-доменных родительских страниц необходимо явно передать `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 по потребностям бизнеса.
+
+---
+
+## Справочник API
+
+### useTabActions
+
+Композабл для операций на уровне вкладок.
+
+```ts
+import { useTabActions } from 'vue-stack-tabs'
+
+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()
+```
+
+| Метод                  | Описание                                                                          |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `openTab(tab, renew?)` | Открыть новую вкладку. При `renew=true` очищает стек страниц и открывает заново   |
+| `closeTab(id)`         | Закрыть указанную вкладку, возвращает ID новой активной вкладки                    |
+| `closeAllTabs()`       | Закрыть все закрываемые вкладки                                                   |
+| `refreshTab(id)`       | Обновить указанную вкладку (заменяет ID кэша, пересоздаёт экземпляр компонента)      |
+| `refreshAllTabs()`     | Обновить все вкладки                                                              |
+| `activeTab(id)`        | Активировать указанную вкладку (переключить вкладку)                               |
+| `reset()`              | Закрыть все вкладки и сбросить состояние                                          |
+
+---
+
+### useTabRouter
+
+Стековая навигация внутри вкладки. **Можно использовать только внутри компонентов страниц во вкладке**.
+
+```ts
+import { useTabRouter } from 'vue-stack-tabs'
+
+const { forward, backward, addScrollTarget } = useTabRouter()
+```
+
+| Метод                       | Описание                                                    |
+| --------------------------- | ----------------------------------------------------------- |
+| `forward(to)`               | Перейти вперёд к новой странице внутри текущей вкладки       |
+| `backward(to, backQuery?)`  | Вернуться назад внутри текущей вкладки                      |
+| `addScrollTarget(selector)` | Зарегистрировать CSS-селектор DOM для запоминания прокрутки  |
+
+#### forward
+
+```ts
+// Перейти на страницу /detail
+forward({ path: '/detail', query: { id: '123' } })
+
+// Добавить тот же маршрут в стек (один маршрут может быть добавлен многократно, каждый с независимым кэшем)
+forward({ path: '/list', query: { page: '2' } })
+```
+
+#### backward
+
+```ts
+// Вернуться на 1 шаг назад (по умолчанию)
+backward(1)
+
+// Вернуться на N шагов
+backward(3)
+
+// Вернуться к определённому пути (автоматический поиск в стеке)
+backward('/list')
+
+// Вернуться с параметрами (целевая страница получает через props._back)
+backward('/list', { result: 'success', data: { id: 1 } })
+```
+
+**Получение параметров на целевой странице:**
+
+```vue
+<script setup>
+// Объявить props для получения параметров обратной навигации
+defineProps<{ _back?: { result: string; data: any } }>()
+</script>
+```
+
+---
+
+### useTabLoading
+
+Управление состоянием загрузки страницы. **Можно использовать только внутри компонентов страниц во вкладке**.
+
+```ts
+import { useTabLoading } from 'vue-stack-tabs'
+
+const { openTabLoading, closeTabLoading } = useTabLoading()
+
+// Показать оверлей загрузки
+openTabLoading()
+
+// Закрыть после завершения асинхронной операции
+fetchData().finally(() => closeTabLoading())
+```
+
+> Загрузка автоматически закрывается при размонтировании компонента — ручная очистка не требуется.
+
+---
+
+## Свойства (Props)
+
+Свойства компонента `<VueStackTabs>`:
+
+| Свойство               | Тип                         | По умолчанию            | Описание                                                      |
+| ----------------------- | --------------------------- | ----------------------- | ------------------------------------------------------------- |
+| `iframePath`            | `string`                    | **Обязательно**         | Путь маршрута-заглушки для iframe                              |
+| `iframeSandbox`         | `string`                    | `allow-scripts allow-forms allow-popups allow-downloads allow-same-origin` | Политика sandbox для iframe; по умолчанию совместимость, не строгая изоляция — удалите `allow-same-origin` для строгой изоляции; пустая строка отключает sandbox (не рекомендуется) |
+| `iframeReferrerPolicy`  | `ReferrerPolicy`            | `strict-origin-when-cross-origin`                                          | Атрибут referrerpolicy для iframe                             |
+| `iframeAllow`           | `string`                    | `''`                                                                       | Атрибут allow для iframe, например `fullscreen`               |
+| `iframeLoadTimeout`     | `number`                    | `15000`                                                                    | Тайм-аут загрузки 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                   |
+
+---
+
+## События (Events)
+
+| Событие        | Параметры      | Описание                                      |
+| -------------- | -------------- | --------------------------------------------- |
+| `onActive`     | `(id: string)` | Срабатывает при активации вкладки              |
+| `onPageLoaded` | —              | Срабатывает при загрузке компонента страницы   |
+
+---
+
+## Вкладки iframe
+
+### Открытие вкладки iframe
+
+```ts
+openTab({
+  title: 'Внешняя страница',
+  path: 'https://example.com',
+  iframe: true
+})
+```
+
+### Операции внутри iframe-страниц
+
+Внутри вкладки iframe можно взаимодействовать с хост-контейнером через `postMessage` для открытия новых вкладок или обработки действий обновления.
+
+#### 1. Использование утилит Bridge (рекомендуется)
+
+Если iframe-страница может ссылаться на код библиотеки (или импортировать инструменты из `iframeBridge.ts`), рекомендуется этот подход:
+
+```ts
+import { postOpenTab, onRefreshRequest } from 'vue-stack-tabs/iframe-bridge'
+
+const parentOrigin = 'https://parent.example.com'
+
+// Открыть вкладку
+postOpenTab(
+  {
+    title: 'Новая страница',
+    path: '/detail',
+    query: { id: '1' }
+  },
+  { targetOrigin: parentOrigin }
+)
+
+// Слушать запросы на обновление
+const off = onRefreshRequest(
+  () => {
+    // Пользовательская логика обновления
+    location.reload()
+  },
+  { allowedOrigins: [parentOrigin] }
+)
+```
+
+#### 2. Нативная интеграция
+
+Если невозможно импортировать утилиты библиотеки или требуется нулевая зависимость, используйте нативный API:
+
+```ts
+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
+
+При вызове `openTab` можно указать поведение обновления через `iframeRefreshMode`:
+
+- `postMessage` (по умолчанию): хост отправляет сообщение `vue-stack-tabs:refresh` в iframe; внутренняя страница сама решает, как обновляться (более плавная анимация).
+- `reload`: хост напрямую сбрасывает `src` или `key` iframe для принудительной перезагрузки браузером (подходит для кросс-доменных или немодифицируемых страниц).
+
+---
+
+## Интернационализация
+
+Встроенные языки: `zh-CN` (китайский), `en-US` (английский).
+
+```ts
+// Переключить язык
+app.use(VueStackTabs, [{ locale: 'en-US' }])
+```
+
+Пользовательский языковой пакет:
+
+```ts
+app.use(VueStackTabs, [
+  {
+    locale: 'ru-RU',
+    messages: {
+      'VueStackTab.close': 'Закрыть',
+      'VueStackTab.refresh': 'Обновить'
+      // ...
+    }
+  }
+])
+```
+
+---
+
+## Определения типов
+
+```ts
+/** Данные, передаваемые при открытии вкладки */
+interface ITabData {
+  id?: string // ID вкладки (автоматически генерируемый UUID, если не указан)
+  title: string // Заголовок вкладки
+  path: string // Путь маршрута или URL iframe
+  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'
+}
+```
+
+---
+
+## Структура проекта
+
+```
+src/lib/
+├── StackTabs.vue           # Главный компонент
+├── index.ts                # Точка входа и экспорты
+├── hooks/                  # Основная логика
+│   ├── useTabActions.ts    # Публичный API
+│   ├── useTabRouter.ts     # Навигация внутри вкладки
+│   ├── useTabLoading.ts    # Состояние загрузки
+│   └── useTabPanel.tsx     # Ядро движка
+├── model/TabModel.ts       # Определения типов
+├── components/             # UI-компоненты
+├── nuxt/                   # Модуль Nuxt
+└── assets/style/           # Стили
+```
+
+Подробное описание архитектуры см. в [`ARCHITECTURE.md`](./ARCHITECTURE.md).
+
+---
+
+## Лицензия
+
+[LGPL-2.1](./LICENSE)

package/dist/iframe-bridge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * iframe-bridge 子入口（vue-stack-tabs/iframe-bridge）。
+ *
+ * 供 iframe 内部页面引用，不包含 Vue 组件和样式等副作用，
+ * 仅导出 postMessage 通信工具。
+ */
+export { MSG_OPEN_TAB, MSG_REFRESH, onRefreshRequest, postOpenTab } from './utils/iframeBridge';
+export type { IframeBridgeOptions, IframeOpenTabPayload, RefreshRequestOptions } from './utils/iframeBridge';

package/dist/iframe-bridge.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Iframe Bridge 测试页面</title>
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        padding: 20px;
+        background: #f0f2f5;
+      }
+      .card {
+        background: white;
+        padding: 20px;
+        border-radius: 8px;
+        box-shadow: 0 2px 12px 0 rgba(0, 0, 0, 0.1);
+      }
+      button {
+        padding: 10px 20px;
+        background: #67c23a;
+        color: white;
+        border: none;
+        border-radius: 4px;
+        cursor: pointer;
+      }
+      .status {
+        margin-top: 10px;
+        color: #606266;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h2>此页面演示使用封装好的 Bridge 对接方式</h2>
+      <p>页面加载时间: <span id="time"></span></p>
+      <p>
+        使用 <code>iframeBridge.ts</code> 中提供的 <code>postOpenTab</code> 和
+        <code>onRefreshRequest</code>。
+      </p>
+
+      <div style="margin: 20px 0">
+        <button id="btnOpen">使用 Bridge 方法请求打开新 Tab</button>
+      </div>
+      <div class="status" id="status"></div>
+    </div>
+
+    <!-- 注意：在实际项目中，如果是原生 HTML 需要引入编译后的 Bridge 脚本，或者直接使用 type="module" -->
+    <script type="module">
+      // 这里的导入路径仅为本地调试示意，实际推荐将 Bridge 打包为公共库或 CDN 引用
+      import { postOpenTab, onRefreshRequest } from './src/lib/utils/iframeBridge.ts'
+
+      const timeEl = document.getElementById('time')
+      timeEl.innerText = new Date().toLocaleTimeString()
+
+      // 1. 使用 Bridge 封装的方法打开 Tab
+      document.getElementById('btnOpen').onclick = () => {
+        postOpenTab({
+          id: 'bridge_triggered_tab',
+          title: 'Bridge 弹出的新页签',
+          path: '/demo/page1',
+          closable: true
+        })
+      }
+
+      // 2. 使用 Bridge 封装的方法监听刷新请求
+      onRefreshRequest(() => {
+        console.log('[Bridge Child] Received refresh request from parent')
+        const statusEl = document.getElementById('status')
+        statusEl.innerText = '正在执行刷新 logic...'
+        setTimeout(() => {
+          location.reload()
+        }, 500)
+      })
+    </script>
+  </body>
+</html>

package/dist/iframe-bridge.mjs

@@ -0,0 +1,20 @@
+//#region src/lib/utils/iframeBridge.ts
+var e = "vue-stack-tabs:refresh", t = "vue-stack-tabs:openTab";
+function n() {
+	return window.location.origin;
+}
+function r(e, r = {}) {
+	typeof window > "u" || !window.parent || window.parent.postMessage({
+		type: t,
+		payload: e
+	}, r.targetOrigin ?? n());
+}
+function i(e = () => window.location.reload(), t = {}) {
+	if (typeof window > "u") return () => void 0;
+	let n = t.allowedOrigins ?? [], r = (t) => {
+		t.source === window.parent && (n.length > 0 && !n.includes(t.origin) || t.data?.type === "vue-stack-tabs:refresh" && e());
+	};
+	return window.addEventListener("message", r), () => window.removeEventListener("message", r);
+}
+//#endregion
+export { t as MSG_OPEN_TAB, e as MSG_REFRESH, i as onRefreshRequest, r as postOpenTab };