v-micro-app-plugin 使用指南 #

​ v-micro-app-plugin 是一款基于京东MicroApp框架的微前端插件，旨在帮助开发者快速地将微应用集成到不同的系统中，实现高效、灵活的前端模块化开发。以下是详细的使用指南，帮助你快速上手。

特性 #

快速集成：通过简单的配置，即可将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 调用参数 #

注意：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 对象，该对象包含以下参数：

注意：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 对象 #

​ 该对象用于获取当前应用的一些基本信息，提供多个方法。具体如下：

使用示例：

import { microAppUtils } from "v-micro-app-plugin";

const { isMicroApp, isBaseApp } = microAppUtils;
import { onBeforeMount } from "vue";

onBeforeMount(() => {
  	console.log('是否在微前端环境中：',isMicroApp(), '是否为主应用：'isBaseApp())
})

getMicroAppMessage 方法 #

​ 此方法直接返回一个通信实例对象，该对象用于实现应用之间的通信，提供一系列 API 方便使用。具体如下：

注意：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参数来指定某个具体子应用名称。

可直接引入的方法 #

使用示例：

import { getMainAppConfigs, getSubAppConfigs } from "v-micro-app-plugin";
import { onBeforeMount } from "vue";

onBeforeMount(() => {
	console.log('使用示例：',getMainAppConfigs(), getSubAppConfigs())
})
// 将会输出当前主应用配置信息，以及其包含的子应用配置信息

贡献者 #

Vivien

Staff Frontend Engineer

github