modules-switch-v3

Vue 3 快捷九宫格业务系统切换组件库（原 mg-module-quickswitch Vue 3 现代化重构升级版）

特性

• ⚡ 全量支持 Vue 3：基于 Vue 3 + TypeScript + Composition API 重构，类型完备、性能优异。
• 🎨 100% 视觉与功能还原：完美复现折叠 (56px) / 展开 (147px)、深浅主题、300ms 防抖悬浮弹层及三级业务板块分类。
• 🧩 高容错与外部 UI 解耦：自适应探测宿主 Element Plus、View UI Plus 消息提示，无任何 UI 库时自动启用原生轻量 Toast 兜底，绝无运行时崩溃风险。
• 🚀 智能路由容灾：支持 vue-router 单页导航；当宿主未安装路由库时，自动无损降级为原生 Hash/History 导航，并支持事件回调。
• 📦 开箱即用零心智负担：样式已随 JS 自动打包内联注入，宿主项目无需手动引入 CSS 文件。

安装

npm install modules-switch-v3
# 或者使用 pnpm / yarn
pnpm add modules-switch-v3

快速上手

1. 全局注册

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import ModulesSwitchPlugin from "modules-switch-v3";

const app = createApp(App);
app.use(ModulesSwitchPlugin);
app.mount("#app");

2. 局部引入

<template>
  <ModulesSwitch
    :collapsed="collapsed"
    theme="dark"
    :themeConfig="themeConfig"
    @back="handleBack"
    @item-click="handleItemClick"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ModulesSwitch } from "modules-switch-v3";

const collapsed = ref(false);
const themeConfig = {
  module_is_show_shortcut: 1,
  color: {
    module_sidebar_background_color: "#4a5b71",
  },
  logo: {
    module_small_logo_url: "https://...",
    module_big_logo_url: "https://...",
  },
};

const handleBack = () => {
  console.log("返回首页");
};
</script>

组件 Props

| 属性名 | 类型 | 默认值 | 说明 | | :--------------- | :------------------ | :---------------------------------------------------- | :------------------------ | | collapsed | boolean | false | 侧边栏是否折叠 | | theme | 'dark' \| 'light' | 'dark' | 主题风格 | | requestUrl | string | 'https://shandianyun.iqilu.com' | 服务接口 BaseURL | | themeConfig | ThemeConfig | { module_is_show_shortcut: 0, color: {}, logo: {} } | 远端控制配置 | | customRequest | Function | undefined | 自定义请求实例函数 (可选) | | messageHandler | Function | undefined | 自定义消息提示函数 (可选) |

组件 Emits

| 事件名 | 参数 | 说明 | | :----------- | :------------------------- | :----------------------- | | back | - | 点击 Logo 区域时触发 | | on-back | - | 兼容 Vue 2 传统事件名称 | | item-click | (item: ModuleItem) | 点击模块卡片项时触发 | | navigate | ({ path, id, opentype }) | 触发路由跳转时派发 | | error | (err: any) | 网络请求或接口报错时派发 |

维护与发包

# 启动本地沙盒调试
npm run dev

# 编译打包 (输出 ESM / CJS / UMD 与类型定义)
npm run build

# 发布至 npm
npm publish

之后发布包步骤

1. 编译最新代码

git add . git commit -m "feat: 完善九宫格跳转逻辑"

2. 升级补丁版本号 (例如 1.0.0 -> 1.0.1，并自动提交 git tag)

npm version patch

3. 编译最新代码并发布

npm publish

4. 同步推送至您的 GitLab 仓库

git push origin master --tags