v-micro-app-plugin
是一款基于京东MicroApp框架的微前端插件,旨在帮助开发者快速地将微应用集成到不同的系统中,实现高效、灵活的前端模块化开发。以下是详细的使用指南,帮助你快速上手。
微前端插件 v-micro-app-plugin 源码地址:GitHub - yoguoer/v-micro-app-plugin: v-micro-app-plugin是一款基于MicroApp的微前端插件,实现快速安装使用。v-micro-app-plugin是一款基于MicroApp的微前端插件,实现快速安装使用。. Contribute to yoguoer/v-micro-app-plugin development by creating an account on GitHub.
https://github.com/yoguoer/v-micro-app-plugin.git
用该插件搭建的的示例项目 vMicroVerseHub 源码地址:GitHub - yoguoer/vMicroVerseHub: vMicroversehub 是一个使用 v-micro-app-plugin搭建的 monorepo 微前端项目框架,主要用于给出案例,更好地展示插件的功能和用法。vMicroversehub 是一个使用 v-micro-app-plugin搭建的 monorepo 微前端项目框架,主要用于给出案例,更好地展示插件的功能和用法。 - yoguoer/vMicroVerseHub
https://github.com/yoguoer/vMicroVerseHub.git
特性
快速集成:通过简单的配置,即可将MicroApp微应用作为插件快速集成到现有系统中。
灵活部署:支持动态加载和卸载微应用,便于按需加载,提升页面加载速度和用户体验。
无缝通信:内置跨应用通信机制,支持不同微应用间的数据交换和事件传递。
易于扩展:插件架构清晰,易于根据业务需求进行定制和扩展。
安装
你可以通过 npm、pnpm 或 yarn 来安装 v-micro-app-plugin
。
-
通过 npm 安装
npm i v-micro-app-plugin --save
-
通过 pnpm 安装
pnpm i v-micro-app-plugin --save
-
通过 yarn 安装
yarn add v-micro-app-plugin
参数
initMyMicroApp 调用参数
参数名 | 介绍 | 类型 |
---|---|---|
app | 应用实例 | object |
options | 配置参数 | microAppConfig |
router | Router 实例 | any |
store | 状态管理实例 | any |
注意:microAppConfig
的类型声明如下:
export interface microAppConfig {
projectName?: string; // 项目名称
subAppConfigs?: Object; // 子应用配置
isBaseApp?: boolean; // 是否为 micro-app 主应用
basePath?: string; // 打包路径
disableSandbox?: boolean; // 是否禁用沙箱
iframe?: boolean; // 是否使用 iframe
}
options 参数介绍
在配置 v-micro-app-plugin
时,你需要准备一个符合条件的 options
对象,该对象包含以下参数:
参数名 | 介绍 | 类型 |
---|---|---|
projectName | 项目名称 | string |
subAppConfigs | 子应用配置对象,包含多个子应用的配置 | Object |
isBaseApp | 标记当前应用是否为主应用(默认为 true) | boolean |
basePath | 打包路径或其他基础路径 | string |
disableSandbox | 是否禁用沙箱(默认为 false) | boolean |
iframe | 是否使用 iframe(默认为 true) | boolean |
注意:subAppConfigs
对象中每个子应用的配置包括:
-
name
:子应用名称 -
url
:子应用的运行地址
使用
引入插件
在你的主应用或目标系统的入口文件中,引入 v-micro-app-plugin
。
import initMyMicroApp from 'v-micro-app-plugin'
配置和启动
你需要准备一个配置对象 options
,包含项目名称、子应用配置、是否为MicroApp主应用以及打包路径等信息。然后,使用 initMyMicroApp
函数进行初始化。这里假设你已经有了一个 Vue 应用实例 app
, Vue Router 实例 router
,以及状态管理实例 store。
const options = {
projectName: 'v-micro-app-plugin',
subAppConfigs: {
'appFirst': {
name: 'appFirst',
url: 'http://localhost:4000/#/' // 微应用的运行地址
},
'appSecond': {
name: 'appSecond',
url: 'http://localhost:3000/#/' // 另一个微应用的运行地址
}
},
isBaseApp: true, // 当前应用是否为主应用
basePath: '/', // 打包路径或其他基础路径
disableSandbox: false, // 是否禁用沙箱
iframe: true, // 是否使用 iframe
};
// 初始化微前端插件
await initMyMicroApp(app, options, router, store);
环境变量配置
为了在不同环境下(如开发、测试、生产)使用不同的微应用地址,你可以使用环境变量来动态设置 url
。这里提供一个示例:
// 假设你已经在项目中配置了环境变量,例如使用 Vite 的 .env 文件 import.meta.env.MODE
const env = import.meta.env.MODE; // 这里使用的是 Vite 默认的 MODE 变量
const microAppUrl = {
appFirst: {
development: 'http://localhost:3000/#/',
test: 'https://test.example.com/vivien/appFirst/',
production: 'https://www.example.com/vivien/appFirst/'
},
appSecond: {
development: 'http://localhost:4000/#/',
test: 'https://test.example.com/vivien/appSecond/',
production: 'https://www.example.com/vivien/appSecond/'
},
};
const options = {
projectName: 'micro-app-Name',
subAppConfigs: {
'appFirst': {
name: 'appFirst',
url: microAppUrl['appFirst'][env]
},
'appSecond': {
name: 'appSecond',
url: microAppUrl['appSecond'][env]
}
},
isBaseApp: true, // 是否为主应用
basePath: '/', // 打包路径或其他基础路径
disableSandbox: false, // 是否禁用沙箱
iframe: true, // 是否使用 iframe
};
await initMyMicroApp(app, options, router, store);
⚠注意:不管是主应用还是子应用,都必须安装插件,根据需要进行不同的配置。
对象和方法
v-micro-app-plugin
提供了一系列可供使用的方法和对象:
microAppUtils 对象
该对象用于获取当前应用的一些基本信息,提供多个方法。具体如下:
方法名 | 介绍 | 参数 |
---|---|---|
isMicroApp | 判断应用是否在微前端环境中 | - |
isBaseApp | 判断应用是否是主应用 | - |
getMicroAppBaseRoute | 获取子应用的基础路由 | - |
getMicroAppPublicPath | 获取子应用的publicPath目录 | - |
getMicroAppName | 获取当前应用名称 | name?: string |
getMicroApp | 返回当前应用实例 | - |
使用示例:
import { microAppUtils } from "v-micro-app-plugin"; const { isMicroApp, isBaseApp } = microAppUtils; import { onBeforeMount } from "vue"; onBeforeMount(() => { console.log('是否在微前端环境中:',isMicroApp(), '是否为主应用:'isBaseApp()) })
getMicroAppMessage 方法
此方法直接返回一个通信实例对象,该对象用于实现应用之间的通信,提供一系列 API 方便使用。具体如下:
方法名 | 介绍 | 参数 |
---|---|---|
sendMessage | 发送数据 | { data, appName, callback }: MessageParamsType |
sendGlobal | 全局发送数据 | { data, appName, callback }: MessageParamsType |
forceSend | 强制发送数据,无论数据是否变化 | { data, appName, callback }: MessageParamsType |
forceSendGlobal | 强制全局发送数据,无论数据是否变化 | { data, appName, callback }: MessageParamsType |
getMessage | 获取数据 | appName?: string |
getGlobalMessage | 获取全局数据 | - |
clearMessage | 清除数据 | appName: string |
clearGlobalMessage | 清除全局数据 | - |
注意:MessageParamsType
的类型声明如下:
interface MessageParamsType {
data: object // 发送的数据内容
appName?: string // 接收数据应用名称,当且仅当主应用发送数据时需要传入
callback?: Function // 回调函数
}
使用示例:
在子应用 appFirst 中,使用 sendMessage 给子应用发出数据,使用发出 sendGlobal 全局数据:
import { getMicroAppMessage } from "v-micro-app-plugin"; function testSendMessage(){ const microAppMessage = getMicroAppMessage() microAppMessage.sendMessage({ data: { type: 'sendMessage', value: 'appFirst给主应用发送数据~' }, callback: () => { console.log('使用sendMessage发送数据成功,执行回调!') } }) microAppMessage.sendGlobal({ data: { fun: 'sendGlobal', text: 'appFirst给全局发送数据~' }, callback: () => { console.log('使用sendGlobal发送数据成功,执行回调!') } }) setTimeout(() => { console.log("getGlobalMessage:", microAppMessage.getGlobalMessage(),"getMessage:", microAppMessage.getMessage()) },3000) } // 结果发现:子应用 => 可以接收到全局信息,但接收不到自己发给主应用的信息。
在主应用中,使用 getMessage 接收子应用发来的数据,使用 getGlobalMessage 接收全局数据:
import { getMicroAppMessage } from "v-micro-app-plugin"; function testGetMessage() { const microAppMessage = getMicroAppMessage() setTimeout(() => { console.log('getGlobalMessage:',microAppMessage.getGlobalMessage(),'getMessage:',microAppMessage.getMessage('appFirst')) }, 3000) } // 结果发现:主应用 => 可以接收到全局信息,也可以收到 appFirst 发来的信息。
Tip:其它通信 API 方法的使用方式同上。
⚠注意:子应用发送数据给主应用时,无需传递
appName
参数;而主应用发送数据给子应用时,则需通过appName
参数来指定某个具体子应用名称。同理,清空当前子应用发送给主应用的数据时,无需传递appName
参数;而清空主应用发送给子应用的数据时,则需通过appName
参数来指定某个具体子应用名称。
可直接引入的方法
方法名 | 介绍 | 参数 |
---|---|---|
getMainAppConfigs | 获取主应用配置项 | - |
getSubAppConfigs | 获取子应用配置项 | - |
getRounterInstance | 获取 Microapp 路由实例 | - |
renderAllSubApp | 渲染所有子应用 | - |
使用示例:
import { getMainAppConfigs, getSubAppConfigs } from "v-micro-app-plugin"; import { onBeforeMount } from "vue"; onBeforeMount(() => { console.log('使用示例:',getMainAppConfigs(), getSubAppConfigs()) }) // 将会输出当前主应用配置信息,以及其包含的子应用配置信息
其它
为了照顾到一些微前端小白,在这里,我附上一些必要的、可能会有所帮助的信息。
配置路由信息
有了主子应用之后,我们就需要在主应用中给子应用配置路由信息,这里一共有 2 个子应用,我们为它们分别进行配置。
- appFirst:
import microAppSetting from '@/settings/microAppSetting'
export default {
path: '/appFirst',
name: 'appFirst',
component: Layout,
order: 1,
hidden: false,
meta: {
title: 'appFirst',
hideBreadcrumb: false,
icon: Document,
microAppOptions: microAppSetting.subAppConfigs!['appFirst']
}
}
-
appSecond:
import microAppSetting from '@/settings/microAppSetting'
export default {
path: '/appSecond',
name: 'appSecond',
component: Layout,
order: 2,
hidden: false,
meta: {
title: 'appSecond',
hideBreadcrumb: false,
icon: Document,
microAppOptions: microAppSetting.subAppConfigs!['appSecond'],
}
}
封装 MicroAppContainer
众所周知,路由切换时,可以给<router-view />
填充上对应路径的内容,同理,microApp中的<micro-app></micro-app>
也有同样的功能。我们可以对其进行二次封装,结合v-if
,以便于根据是路由指向的是子应用,还是本系统自由模块,来判断究竟是渲染微应用视图,还是渲染普通视图。
为了达到这个目的,我们可以新建一个 MicroAppContainer 文件夹,在其中创建一个index.vue
,然后键入以下内容:
<template>
<div :class="[`${prefixCls}-container`]">
<!-- name:应用名称, url:应用地址 -->
<micro-app v-bind="options" :name="options.name" keep-alive></micro-app>
</div>
</template>
<script setup lang="ts">
import { watch } from "vue";
const props = defineProps<{
options: {
[key: string]: any;
};
}>();
let prefixCls = props.options.name
watch(
() => props.options,
(newValue) => {
prefixCls = newValue.name
},
{ immediate: true, deep: true }
);
</script>
<style></style>
⚠注意:keep-alive 属性可根据需要决定是否设置。
区分是否微应用视图
-
在你需要加载子应用页面的地方:
<div :class="[`${prefixCls}-viewer-microapp`]" v-if="isMicroAppView">
<MicroAppContainer :options="microAppOptions" />
</div>
<div v-else>
<router-view />
</div>
-
一些必要的逻辑语句:
import { watchEffect, ref } from 'vue'
import { useRoute } from 'vue-router'
const route = useRoute()
let isMicroAppView: Ref = ref(false)
let microAppOptions: Ref = ref({})
watchEffect(async () => {
microAppOptions.value = route.meta.microAppOptions
isMicroAppView.value = !isNullOrUnDef(microAppOptions.value) && !isEmpty(microAppOptions.value)
})