vue3-tabor

v0.2.2

Published

7 months ago

Vue 3 routing tabs with keepAlive support, browser-like tab navigation for Vue applications

Downloads

✨ 特点

🔥 简单易上手：零学习成本，引入即用
🎨 高度定制化：提供丰富API和配置，满足从基础到复杂的各类需求
📦 轻量高效：基于Vue 3和Vue Router 4优化设计，性能出色，体积小巧
💪 类型支持：使用TypeScript开发，提供完整类型定义，开发体验卓越

🛠️ 功能特性

基础功能
- ✅ 路由响应：自动响应路由变化，打开、切换页签
- ✅ 标签管理：
  - ✅ 打开/替换页签
  - ✅ 关闭页签
  - ✅ 关闭其他页签
  - ✅ 刷新页签
  - ✅ 右键菜单操作
- ✅ 缓存控制：支持页签内容缓存，提升用户体验
- ⏳ 全局配置：支持全局及个性化配置（开发中）
- ⏳ 生命周期钩子：提供丰富的生命周期事件（开发中）
高级特性
- ✅ iframe支持：内置iframe路由支持，轻松集成外部页面
- ⏳ 动画效果：页签切换动画（开发中）
- ⏳ 国际化：多语言支持（开发中）
- ⏳ 埋点统计：页签访问数据统计（开发中）

📦 安装

npm install vue3-tabor

🚀 快速开始

1. 在入口文件中引入并注册插件

import { createApp } from "vue";
import Tabor from "vue3-tabor";
// 必须引入样式文件
import "vue3-tabor/dist/assets/index.css";
import router from "./router";
import App from "./App.vue";

const app = createApp(App);
app.use(router);
app.use(Tabor, { 
  router,  // 传入router实例
  maxCache: 10  // 可选：最大缓存数量
});

app.mount("#app");

2. 在布局组件中使用标签页组件

<!-- App.vue 或 Layout.vue -->
<template>
  <div class="app-container">
    <header><!-- 你的应用头部 --></header>
    <main>
      <vue-tabor />
    </main>
  </div>
</template>

📖 API 文档

全局配置

在安装插件时，可以传入以下配置选项：

app.use(Tabor, {
  router: router,       // 必需：Vue Router 实例
  maxCache: 10,         // 可选：最大缓存数量，默认为10
});

组件属性 (Props)

<vue-tabor> 组件支持以下属性：

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | maxAlive | Number | 10 | 最大缓存数量 | | hideClose | Boolean | false | 是否隐藏关闭按钮 | | beforeClose | Function | - | 关闭标签前的钩子函数，返回Promise | | tabClass | String | - | 标签的自定义CSS类名 | | pageClass | String | - | 页面的自定义CSS类名 | | dropdownClass | String | - | 下拉菜单的自定义CSS类名 | | tabType | String | 'line' | 标签类型，可选值：'line'、'card' | | style | Object | - | 自定义样式变量 | | tabPrefix | Component | - | 标签前缀组件 | | language | String | 'zh' | 界面语言，可选值：'zh'、'en' |

国际化支持

vue3-tabor 支持中文和英文两种语言，可以通过以下方式进行配置：

<!-- 设置为英文 -->
<vue-tabor language="en" />

<!-- 设置为中文 -->
<vue-tabor language="zh" />

样式变量

vue3-tabor 提供了以下 CSS 变量，可以通过 style 属性或全局 CSS 自定义主题样式：

基础配置

<vue-tabor :style="{
  /* 基础颜色与尺寸 */
  --primary-color: #5a67d8,                 /* 主题色，用于激活状态和高亮效果 */
  --font-size-base: 14px,                   /* 基础字体大小 */
}" />

标签外观

<vue-tabor :style="{
  /* 标签尺寸与间距 */
  --tab-height: 40px,                       /* 标签高度 */
  --tab-min-width: 83px,                    /* 标签最小宽度 */
  --tab-padding: 0 12px,                    /* 标签内边距 */
  --tabs-gap: 6px,                          /* 标签之间的间距 */
  --tab-label-min-width: 30px,              /* 标签文本最小宽度 */
  --tab-label-max-width: 100px,             /* 标签文本最大宽度，超出将显示省略号 */
  
  /* 标签颜色与边框 */
  --tab-background-color: rgba(248, 249, 250, 0.5), /* 标签背景色 */
  --tab-active-background-color: #fff,      /* 激活标签的背景色 */
  --tab-active-color: var(--primary-color), /* 激活标签的文本颜色 */
  --tab-text-color: #64748b,                /* 普通标签的文本颜色 */
  --tab-border-color: #e2e8f0,              /* 标签边框颜色 */
  --tab-border-radius: 4px,                 /* 标签边框圆角 */
  
  /* 标签阴影 */
  --tab-box-shadow: 0 1px 2px rgba(0, 0, 0, 0.03),  /* 标签阴影 */
  --tab-active-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05), /* 激活标签阴影 */
}" />

内容区域

<vue-tabor :style="{
  /* 内容区域样式 */
  --page-padding: 10px,                     /* 页面内容区域内边距 */
}" />

预设主题示例

默认主题 (浅色)

<vue-tabor :style="{
  --primary-color: #5a67d8,
  --tab-background-color: rgba(248, 249, 250, 0.5),
  --tab-active-background-color: #fff,
  --tab-text-color: #64748b,
  --tab-border-color: #e2e8f0
}" />

暗色主题

<vue-tabor :style="{
  --primary-color: #818cf8,
  --tab-background-color: rgba(30, 41, 59, 0.5),
  --tab-active-background-color: #1e293b,
  --tab-active-color: #818cf8,
  --tab-text-color: #cbd5e1,
  --tab-border-color: #334155
}" />

亮蓝主题

<vue-tabor :style="{
  --primary-color: #0ea5e9,
  --tab-border-radius: 8px 8px 0 0,
  --tab-background-color: rgba(224, 242, 254, 0.5),
  --tab-active-background-color: #fff
}" />

通过全局 CSS 自定义样式

除了使用组件的 style 属性外，您还可以通过全局 CSS 变量设置来自定义样式：

/* 在您的全局样式文件中 */
:root {
  --primary-color: #5a67d8;
  --tab-height: 40px;
  --tab-background-color: rgba(248, 249, 250, 0.5);
  /* 其他变量... */
}

高级样式定制

对于需要更深层次自定义的场景，您可以使用以下方法：

使用提供的类名添加自定义样式：

/* 自定义标签样式 */
.tabor-tab {
  /* 自定义样式 */
}
   
/* 自定义激活标签样式 */
.tabor-tab-active {
  /* 自定义样式 */
}

使用 tabPrefix 属性添加前缀内容：

<vue-tabor :tabPrefix="YourPrefixComponent" />

实例方法

可以通过注入的 tabStore 访问以下方法：

// 在组件中使用
import { useTabor } from 'vue3-tabor'

export default {
  setup() {
    const tabor = useTabor();
    
    // 使用tabor方法
    return { tabor };
  }
}

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | open | (to: RouteLocationRaw, options?: OpenProps) | Promise<void> | 打开新标签 | | close | (item?: TabGetter, toOptions?: ToOptions) | Promise<void> | 关闭标签 | | closeOthers | (tabId?: TabId) | void | 关闭其他标签 | | refresh | (tabId?: TabId) | void | 刷新标签 | | find | (tabId: TabId) | Tab | undefined | 查找标签 | | has | (tabId?: TabId) | boolean | 检查标签是否存在 | | setActive | (tab: Tab) | void | 设置活动标签 | | remove | (item: { id?: TabId; fullPath?: string }) | void | 移除标签 |

Tab相关类型

// 标签配置
interface TabConfig {
  key?: "path" | "fullPath" | ((route) => string);
  name?: string | (route:RouteLocationNormalized) => string;
  keepAlive?: boolean;
  icon?: string;
  iframeAttributes?: IframeAttributes;
  hideClose?: boolean | ((tab: Tab) => boolean);
}

// 标签信息
interface Tab {
  id: string;
  name: string | symbol | (route:RouteLocationNormalized) => string;
  icon?: string;
  keepAlive?: boolean;
  fullPath: string;
  allowClose?: boolean;
  iframeAttributes?: IframeAttributes;
  routeName?: string;
}

// 打开标签的选项
interface OpenProps {
  replace?: boolean;  // 是否替换当前标签
  refresh?: boolean;  // 是否刷新
  tabConfig?: TabConfig;  // 标签配置
}

iframe 支持

vue3-tabor 支持在标签中打开外部页面：

// 打开iframe标签
tabStore.open({
  path: '/iframe',
  query: { 
    src: 'https://example.com', 
    title: '外部页面' 
  }
}, {
  tabConfig: {
    iframeAttributes: {
      src: 'https://example.com',
      width: '100%',
      height: '100%'
    }
  }
});

路由配置

在路由配置中，可以通过 meta.tabConfig 来设置标签页的配置。使用 satisfies TabConfig 可以确保类型安全：

const routes = [
  {
    path: '/home',
    component: Home,
    meta: {
      tabConfig: {
        hideClose: true,  // 隐藏关闭按钮
        keepAlive: true,  // 启用缓存
        name: '首页'
      } satisfies TabConfig
    }
  }
]

🔧 技术栈

💻 Vue 3：基于最新的Vue 3.x版本开发
🔄 Vue Router 4：与Vue Router深度集成
💪 TypeScript：类型安全的代码开发体验
👬 Vitest：可靠的单元测试保障

📚 更多资源

问题反馈