shared-layout-components

shared-layout-components

基于 Vue3 和 Ant Design Vue 的公共布局组件库，提供完整的后台管理系统布局解决方案。

特性

• 🎯 开箱即用 - 提供完整的后台布局组件
• 🔗 联动交互 - 菜单、标签页、面包屑自动联动
• 💾 状态持久化 - 基于 Pinia 的标签页状态管理，支持刷新保持
• 🎨 高度可定制 - 支持插槽自定义各区域内容
• 📦 按需引入 - 支持 UMD 和 ES Module 两种格式
• 🔄 对等依赖 - 通过函数参数接收宿主应用的依赖实例，避免重复打包
• 🔌 微前端支持 - 内置 qiankun 微应用生命周期支持

组件列表

安装

npm install shared-layout-components

前置依赖（对等依赖）

本库使用**对等依赖（peer dependencies）**方式管理依赖，需要在宿主应用中安装以下依赖：

npm install vue@^3.3.4 vue-router@^4.0.0 pinia@^3.0.0 ant-design-vue@^4.2.6 @ant-design/icons-vue@^7.0.0

{
  "vue": "^3.3.4",
  "vue-router": "^4.0.0",
  "pinia": "^3.0.0",
  "ant-design-vue": "^4.2.6",
  "@ant-design/icons-vue": "^7.0.0"
}

可选依赖

说明：本库不会将依赖打包到构建产物中，而是通过函数参数从宿主应用接收实例，避免版本冲突和重复打包。

快速开始

1. 定义路由配置

// router.js
export const routes = [
  {
    path: '/',
    redirect: '/dashboard'
  },
  {
    path: '/dashboard',
    name: 'Dashboard',
    component: () => import('./pages/Dashboard.vue'),
    meta: { title: '仪表盘' }
  },
  {
    path: '/user/list',
    name: 'UserList',
    component: () => import('./pages/UserList.vue'),
    meta: { title: '用户列表' }
  }
];

2. 初始化应用

// main.js
import { createApp } from 'vue';
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/reset.css';
import App from './App.vue';
import { routes } from './router';

// 导入对等依赖模块
import * as VueRouter from 'vue-router';
import * as pinia from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';

// 导入组件库
import { createSharedLayout } from 'shared-layout-components';

const app = createApp(App);

// 创建并安装 Pinia（宿主应用自行管理）
const piniaInstance = pinia.createPinia();
piniaInstance.use(piniaPluginPersistedstate);
app.use(piniaInstance);

// 创建并安装 Vue Router（宿主应用自行管理）
const router = VueRouter.createRouter({
  history: VueRouter.createWebHistory(),
  routes
});
app.use(router);

// 使用组件库，传入宿主应用的依赖实例
const sharedLayout = createSharedLayout({
  pinia,                      // 传入 pinia 模块
  piniaPluginPersistedstate,  // 传入持久化插件
  router,                     // 传入已创建的路由实例
  vueRouter: VueRouter        // 传入 vue-router 模块
});
app.use(sharedLayout);

app.use(Antd);
app.mount('#app');

说明：

• 宿主应用需要自行创建并安装 router 和 pinia 实例
• 将依赖模块通过参数传递给组件库
• 组件库通过注入机制将依赖提供给内部组件使用
• 这种方式避免了依赖重复打包和版本冲突

3. 使用 PageLayout 组件

<template>
  <PageLayout
    ref="pageLayoutRef"
    :menuData="menuData"
    :systemTitle="systemTitle"
  >
    <template #default="{ activeTab }">
      <router-view></router-view>
    </template>
  </PageLayout>
</template>

<script setup>
import { ref, provide } from 'vue';
import { PageLayout } from 'shared-layout-components';

const pageLayoutRef = ref(null);
const systemTitle = ref('管理系统');

const menuData = ref([
  {
    key: 'dashboard',
    label: '仪表盘',
    title: '仪表盘',
    path: '/dashboard'
  },
  {
    key: 'user',
    label: '用户管理',
    title: '用户管理',
    children: [
      { key: 'user-list', label: '用户列表', title: '用户列表', path: '/user/list' },
      { key: 'user-role', label: '角色管理', title: '角色管理', path: '/user/role' }
    ]
  }
]);

// 提供打开新 tab 的方法给子页面使用
provide('openTab', (tab) => {
  const layout = pageLayoutRef.value;
  if (layout) {
    layout.addTab(tab);
  }
});
</script>

组件会自动处理：

• 路由变化时自动添加对应标签页
• 点击菜单时自动跳转路由
• 切换标签页时自动跳转路由
• 关闭标签页时自动切换到相邻标签页并跳转

4. 子页面打开新 Tab 示例

<!-- UserList.vue -->
<template>
  <div class="page-user-list">
    <h2>用户列表</h2>
    <a-card>
      <div class="table-toolbar">
        <a-button type="primary" @click="handleAdd">
          <plus-outlined />
          新增用户
        </a-button>
      </div>
      <!-- 表格内容 -->
    </a-card>
  </div>
</template>

<script setup>
import { inject } from 'vue';
import { PlusOutlined } from '@ant-design/icons-vue';

const openTab = inject('openTab', null);

const handleAdd = () => {
  if (openTab) {
    openTab({
      key: 'user-list-add',      // 唯一标识
      title: '新增用户',          // 标签页标题
      closable: true,            // 是否可关闭
      path: '/user/list/add'     // 路由路径
    });
  }
};
</script>

⚠️ 路由定义注意事项

子页面路由路径必须包含父级列表路径，以便组件库正确匹配左侧菜单和面包屑。

✅ 正确示例

// 菜单配置
const menuData = [
  {
    key: 'audiobook',
    label: '有声书管理',
    title: '有声书管理',
    children: [
      { 
        key: 'audiobook-list', 
        label: '有声书列表', 
        title: '有声书列表', 
        path: '/audiobook/index'  // 列表页路径
      }
    ]
  }
];

// 路由配置
const routes = [
  {
    path: '/audiobook/index',           // 列表页
    name: 'AudiobookList',
    component: () => import('./pages/AudiobookList.vue'),
    meta: { title: '有声书列表' }
  },
  {
    path: '/audiobook/index/add',       // 新增页 ✅ 包含列表路径
    name: 'AudiobookAdd',
    component: () => import('./pages/AudiobookAdd.vue'),
    meta: { title: '新增有声书' }
  },
  {
    path: '/audiobook/index/edit/:id',  // 编辑页 ✅ 包含列表路径
    name: 'AudiobookEdit',
    component: () => import('./pages/AudiobookEdit.vue'),
    meta: { title: '编辑有声书' }
  }
];

❌ 错误示例

// 错误：新增页路径没有包含列表路径
{
  path: '/audiobook/add',     // ❌ 错误：应该是 /audiobook/index/add
  name: 'AudiobookAdd',
  component: () => import('./pages/AudiobookAdd.vue')
}

路径匹配规则

组件库使用最长前缀匹配算法自动匹配菜单：

1. 当前路由 /audiobook/index/add 会匹配到菜单 /audiobook/index
2. 面包屑会显示：有声书管理 > 有声书列表 > 新增有声书
3. 左侧菜单"有声书列表"会被自动选中并展开

建议路径命名规范：

API

createSharedLayout(options)

创建组件库插件，需要在宿主应用中调用。

PageLayout Props

PageLayout Events

PageLayout Methods

通过 ref 调用：

暴露的响应式数据：

PageLayout Slots

菜单数据格式

const menuData = [
  {
    key: 'dashboard',      // 唯一标识
    label: '仪表盘',        // 菜单名称
    title: '仪表盘',        // 标签页标题
    icon: 'dashboard',     // 图标（可选）
    path: '/dashboard'     // 路由路径
  },
  {
    key: 'user',
    label: '用户管理',
    title: '用户管理',
    children: [            // 子菜单
      {
        key: 'user-list',
        label: '用户列表',
        title: '用户列表',
        path: '/user/list'
      }
    ]
  }
];

标签页数据格式

const tab = {
  key: 'dashboard',        // 唯一标识
  title: '仪表盘',          // 标签页标题
  path: '/dashboard',      // 路由路径
  closable: true           // 是否可关闭（默认 true）
};

Tabs 组件

独立的标签页组件，也可单独使用。

Tabs Props

Tabs Events

Tabs Methods

通过 ref 调用：

使用示例

<template>
  <Tabs
    ref="tabsRef"
    :tabs="tabsList"
    :activeTab="activeTab"
    @update:activeTab="onTabChange"
    @tab-close="onTabClose"
  />
</template>

<script setup>
import { ref } from 'vue';
import { Tabs } from 'shared-layout-components';

const tabsRef = ref();
const tabsList = ref([...]);
const activeTab = ref('');

// 通过 ref 删除指定 tab
const removeTabByKey = (key) => {
  tabsRef.value.removeTab(key);
};
</script>

状态管理

组件内部使用 Pinia 管理标签页状态，通过 getStores 可访问：

import { getStores } from 'shared-layout-components';

const { useTabsStore } = getStores();
const tabsStore = useTabsStore();

// 获取当前标签页列表
console.log(tabsStore.tabs);

// 获取当前激活标签页
console.log(tabsStore.currentTab);

// 获取当前标签页数据
console.log(tabsStore.currentTabData);

本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

发布

# 构建并发布
npm run prepublishOnly
npm publish

License

MIT