From 9671b5329be612fe8476b6de329c3135c8ae2c41 Mon Sep 17 00:00:00 2001 From: raoenhui Date: Tue, 30 Jul 2024 17:09:47 +0800 Subject: [PATCH 01/10] fix: fix docs api --- docs/navbar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/navbar.md b/docs/navbar.md index 4ea4bbdcc..23b6cadd6 100755 --- a/docs/navbar.md +++ b/docs/navbar.md @@ -1,4 +1,4 @@ -- [API](zh-cn/api) +- [API](zh-cn/api/base-app) - [Micro-App-DevTools](zh-cn/micro-app-devtools) - [常见问题](zh-cn/questions) - Translations From 4f62d3463f86be62859c635255a34b0e295fdeb8 Mon Sep 17 00:00:00 2001 From: raoenhui Date: Tue, 30 Jul 2024 17:50:42 +0800 Subject: [PATCH 02/10] =?UTF-8?q?fix:=20=E5=A4=A7=E5=B0=8F=E5=86=99?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/zh-cn/API/base-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh-cn/API/base-app.md b/docs/zh-cn/API/base-app.md index fe27686ff..71fbcb51f 100644 --- a/docs/zh-cn/API/base-app.md +++ b/docs/zh-cn/API/base-app.md @@ -1,5 +1,5 @@ ## start -**描述：**micro-app注册函数，全局执行一次 +**描述：**micro-app注册函数，全局执行一次。 **介绍：** ```js From 170633d6db65cdded2176d32bd317ee9bc6e0572 Mon Sep 17 00:00:00 2001 From: raoenhui Date: Tue, 30 Jul 2024 18:22:39 +0800 Subject: [PATCH 03/10] fix: delete api docs: add api --- docs/zh-cn/API/base-app.md | 614 ------------------------------------ docs/zh-cn/API/child-app.md | 184 ----------- 2 files changed, 798 deletions(-) delete mode 100644 docs/zh-cn/API/base-app.md delete mode 100644 docs/zh-cn/API/child-app.md diff --git a/docs/zh-cn/API/base-app.md b/docs/zh-cn/API/base-app.md deleted file mode 100644 index 71fbcb51f..000000000 --- a/docs/zh-cn/API/base-app.md +++ /dev/null @@ -1,614 +0,0 @@ -## start -**描述：**micro-app注册函数，全局执行一次。 - -**介绍：** -```js -start (options?: { - tagName?: string, // 设置标签名称，默认为micro-app - iframe?: boolean, // 全局开启iframe沙箱，默认为false - inline?: boolean, // 全局开启内联script模式运行js，默认为false - destroy?: boolean, // 全局开启destroy模式，卸载时强制删除缓存资源，默认为false - // shadowDOM?: boolean, // 全局开启shadowDOM模式，默认为false - ssr?: boolean, // 全局开启ssr模式，默认为false - 'disable-scopecss'?: boolean, // 全局禁用样式隔离，默认为false - 'disable-sandbox'?: boolean, // 全局禁用沙箱，默认为false - 'keep-alive'?: boolean, // 全局开启保活模式，默认为false - 'disable-memory-router'?: boolean, // 全局关闭虚拟路由系统，默认值false - 'keep-router-state'?: boolean, // 子应用在卸载时保留路由状态，默认值false - 'disable-patch-request'?: boolean, // 关闭子应用请求的自动补全功能，默认值false - 'router-mode'?: string, // 设置路由模式，共四种：search、native、native-scope、pure，默认为search - iframeSrc?: string, // 设置iframe沙箱中iframe的src地址，默认为子应用所在页面地址 - // 全局生命周期 - lifeCycles?: { - created?(e?: CustomEvent): void - beforemount?(e?: CustomEvent): void - mounted?(e?: CustomEvent): void - unmount?(e?: CustomEvent): void - error?(e?: CustomEvent): void - }, - // 预加载，支持数组或函数 - preFetchApps?: Array<{ - name: string, - url: string, - disableScopecss?: boolean, - disableSandbox?: boolean, - // shadowDOM?: boolean - }> | (() => Array<{ - name: string, - url: string, - disableScopecss?: boolean, - disableSandbox?: boolean, - // shadowDOM?: boolean - }>), - // 插件系统，用于处理子应用的js文件 - plugins?: { - // 全局插件，作用于所有子应用的js文件 - global?: Array<{ - // 可选，强隔离的全局变量(默认情况下子应用无法找到的全局变量会兜底到主应用中，scopeProperties可以禁止这种情况) - scopeProperties?: string[], - // 可选，可以逃逸到外部的全局变量(escapeProperties中的变量会同时赋值到子应用和外部真实的window上) - escapeProperties?: string[], - // 可选，如果函数返回 `true` 则忽略 script 和 link 标签的创建 - excludeChecker?: (url: string) => boolean - // 可选，如果函数返回 `true` ，则 micro-app 不会处理它，元素将原封不动进行渲染 - ignoreChecker?: (url: string) => boolean - // 可选，传递给loader的配置项 - options?: any, - // 可选，js处理函数，必须返回 code 值 - loader?: (code: string, url: string, options: any, info: sourceScriptInfo) => string, - // 可选，html 处理函数，必须返回 code 值 - processHtml?: (code: string, url: string, options: unknown) => string - }> - - // 子应用插件 - modules?: { - // appName为应用的名称，这些插件只会作用于指定的应用 - [name: string]: Array<{ - // 可选，强隔离的全局变量(默认情况下子应用无法找到的全局变量会兜底到主应用中，scopeProperties可以禁止这种情况) - scopeProperties?: string[], - // 可选，可以逃逸到外部的全局变量(escapeProperties中的变量会同时赋值到子应用和外部真实的window上) - escapeProperties?: string[], - // 可选，如果函数返回 `true` 则忽略 script 和 link 标签的创建 - excludeChecker?: (url: string) => boolean - // 可选，如果函数返回 `true` ，则 micro-app 不会处理它，元素将原封不动进行渲染 - ignoreChecker?: (url: string) => boolean - // 可选，传递给loader的配置项 - options?: any, - // 必填，js处理函数，必须返回code值 - loader?: (code: string, url: string, options: any, info: sourceScriptInfo) => string, - // 可选，html 处理函数，必须返回 code 值 - processHtml?: (code: string, url: string, options: unknown) => string - }> - } - }, - // 重定义fetch方法，可以用于拦截资源请求操作 - fetch?: (url: string, options: Record, appName: string | null) => Promise - // 设置全局静态资源 - globalAssets?: { - js?: string[], // js地址 - css?: string[], // css地址 - }, - // 指定部分特殊的动态加载的微应用资源（css/js) 不被 micro-app 劫持处理 - excludeAssetFilter?: (assetUrl: string) => boolean - // 基座对子应用 document 的一些属性进行自定义代理扩展 - customProxyDocumentProps?: Map void> -}) -``` - -**使用方式：** -```js -// index.js -import microApp from '@micro-zoe/micro-app' - -microApp.start() -``` - -## preFetch -**描述：**预加载，在浏览器空闲时间，依照开发者传入的顺序，依次加载每个应用的静态资源 - -**介绍：** -```js -preFetch([ - { - name: string, - url: string, - disableScopecss?: boolean, - disableSandbox?: boolean, - }, -]) -``` - -**使用方式：** -```js -import { preFetch } from '@micro-zoe/micro-app' - -// 方式一 -preFetch([ - { name: 'my-app1', url: 'xxx' }, - { name: 'my-app2', url: 'xxx' }, -]) - -// 方式二 -preFetch(() => [ - { name: 'my-app1', url: 'xxx' }, - { name: 'my-app2', url: 'xxx' }, -]) -``` - - -## getActiveApps -**描述：**获取正在运行的子应用，不包含已卸载和预加载的应用 - -**版本限制：** 0.5.2及以上版本 - -**介绍：** -```js -/** - * getActiveApps接受一个对象作为参数，详情如下： - * @param excludeHiddenApp 是否过滤处于隐藏状态的keep-alive应用，默认false - * @param excludePreRender 是否过滤预渲染的应用，默认false - */ -function getActiveApps({ - excludeHiddenApp?: boolean, - excludePreRender?: boolean, -}): string[] -``` - -**使用方式：** -```js -import { getActiveApps } from '@micro-zoe/micro-app' - -// 获取所有正在运行的应用的名称 -getActiveApps() // [子应用1name, 子应用2name, ...] - -// 获取所有正在运行的应用的名称，但不包括已经处于隐藏状态的keep-alive应用 -getActiveApps({ excludeHiddenApp: true }) - -// 获取所有正在运行的应用的名称，但不包括预渲染应用 -getActiveApps({ excludePreRender: true }) -``` - -## getAllApps -**描述：**获取所有子应用，包含已卸载和预加载的应用 - -**版本限制：** 0.5.2及以上版本 - -**介绍：** -```js -function getAllApps(): string[] -``` - -**使用方式：** -```js -import { getAllApps } from '@micro-zoe/micro-app' - -getAllApps() // [子应用name, 子应用name, ...] -``` - - -## version -**描述：**查看版本号 - -**方式1：** -```js -import { version } from '@micro-zoe/micro-app' -``` - -**方式2：**通过micro-app元素上的version属性查看 -```js -document.querySelector('micro-app').version -``` - -## pureCreateElement -**描述：**创建无绑定的纯净元素 - -**使用方式：** -```js -import { pureCreateElement } from '@micro-zoe/micro-app' - -const pureDiv = pureCreateElement('div') - -document.body.appendChild(pureDiv) -``` - - -## removeDomScope -**描述：**解除元素绑定，通常用于受子应用元素绑定影响，导致主应用元素错误绑定到子应用的情况 - -**介绍：** -```js -/** - * @param force 解除元素绑定，并且一定时间内(一个微任务Promise时间)阻止再次绑定。 - */ -function removeDomScope(force?: boolean): void -``` - -**使用方式：** -```js -import { removeDomScope } from '@micro-zoe/micro-app' - -removeDomScope(true) // 解除元素绑定 -/** - * 中间区域的元素操作都指向主应用 - * 例如： - * document.body.appendChild(document.createElement('div')) - * div元素将插入到主应用body中 - */ -removeDomScope(false) // 恢复元素绑定 -``` - - -## unmountApp -**描述：**手动卸载应用 - -**版本限制：** 0.6.1及以上版本 - -**介绍：** -```js -// unmountApp 参数配置 -interface unmountAppParams { - /** - * destroy: 是否强制卸载应用并删除缓存资源，默认值：false - * 优先级: 高于 clearAliveState - * 对于已经卸载的应用: 当子应用已经卸载或keep-alive应用已经推入后台，则清除应用状态及缓存资源 - * 对于正在运行的应用: 当子应用正在运行，则卸载应用并删除状态及缓存资源 - */ - destroy?: boolean - /** - * clearAliveState: 是否清空应用的缓存状态，默认值：false - * 解释: 如果子应用是keep-alive，则卸载并清空状态，并保留缓存资源，如果子应用不是keep-alive，则执行正常卸载流程，并保留缓存资源 - * 补充: 无论keep-alive应用正在运行还是已经推入后台，都将执行卸载操作，清空应用缓存状态，并保留缓存资源 - */ - clearAliveState?: boolean -} - -function unmountApp(appName: string, options?: unmountAppParams): Promise -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -// 正常流程 -microApp.unmountApp(子应用名称).then(() => console.log('卸载成功')) - -// 卸载应用并清空缓存资源 -microApp.unmountApp(子应用名称, { destroy: true }).then(() => console.log('卸载成功')) - -// 如果子应用是keep-alive应用，则卸载并清空状态，如果子应用不是keep-alive应用，则正常卸载 -microApp.unmountApp(子应用名称, { clearAliveState: true }).then(() => console.log('卸载成功')) - -// 如果destroy和clearAliveState同时为true，则clearAliveState将失效 -microApp.unmountApp(子应用名称, { destroy: true, clearAliveState: true }).then(() => console.log('卸载成功')) -``` - -## unmountAllApps -**描述：**手动卸载所有应用 - -**版本限制：** 0.6.1及以上版本 - -**介绍：** -```js -// unmountAllApps 参数配置 -interface unmountAppParams { - /** - * destroy: 是否强制卸载应用并删除缓存资源，默认值：false - * 优先级: 高于 clearAliveState - * 对于已经卸载的应用: 当子应用已经卸载或keep-alive应用已经推入后台，则清除应用状态及缓存资源 - * 对于正在运行的应用: 当子应用正在运行，则卸载应用并删除状态及缓存资源 - */ - destroy?: boolean - /** - * clearAliveState: 是否清空应用的缓存状态，默认值：false - * 解释: 如果子应用是keep-alive，则卸载并清空状态，并保留缓存资源，如果子应用不是keep-alive，则执行正常卸载流程，并保留缓存资源 - * 补充: 无论keep-alive应用正在运行还是已经推入后台，都将执行卸载操作，清空应用缓存状态，并保留缓存资源 - */ - clearAliveState?: boolean -} - -function unmountAllApps(options?: unmountAppParams): Promise -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -// 正常流程 -microApp.unmountAllApps().then(() => console.log('卸载成功')) - -// 卸载所有应用并清空缓存资源 -microApp.unmountAllApps({ destroy: true }).then(() => console.log('卸载成功')) - -// 如果子应用是keep-alive应用，则卸载并清空状态，如果子应用不是keep-alive应用，则正常卸载 -microApp.unmountAllApps({ clearAliveState: true }).then(() => console.log('卸载成功')) - -// 如果destroy和clearAliveState同时为true，则clearAliveState将失效 -microApp.unmountAllApps({ destroy: true, clearAliveState: true }).then(() => console.log('卸载成功')) -``` - - -## reload -**描述：**重新渲染子应用 - -**版本限制：** 1.0.0及以上版本 - -**介绍：** -```js -/** - * @param appName 应用名称，必传 - * @param destroy 重新渲染时是否彻底删除缓存值，可选 - */ -function reload(appName: string, destroy?: boolean): Promise -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -// 案例一：重新渲染子应用my-app -microApp.reload('my-app').then((result) => { - if (result) { - console.log('重新渲染成功') - } else { - console.log('重新渲染失败') - } -}) - -// 案例二：重新渲染子应用my-app，并彻底删除缓存值 -microApp.reload('my-app', true).then((result) => { - if (result) { - console.log('重新渲染成功') - } else { - console.log('重新渲染失败') - } -}) -``` - -## renderApp -**描述：**手动渲染子应用 - -**介绍：** -```js -interface RenderAppOptions { - name: string, // 应用名称，必传 - url: string, // 应用地址，必传 - container: string | Element, // 应用容器或选择器，必传 - iframe?: boolean, // 是否切换为iframe沙箱，可选 - inline?: boolean, // 开启内联模式运行js，可选 - 'disable-scopecss'?: boolean, // 关闭样式隔离，可选 - 'disable-sandbox'?: boolean, // 关闭沙箱，可选 - 'disable-memory-router'?: boolean, // 关闭虚拟路由系统，可选 - 'default-page'?: string, // 指定默认渲染的页面，可选 - 'keep-router-state'?: boolean, // 保留路由状态，可选 - 'disable-patch-request'?: boolean, // 关闭子应用请求的自动补全功能，可选 - 'keep-alive'?: boolean, // 开启keep-alive模式，可选 - destroy?: boolean, // 卸载时强制删除缓存资源，可选 - fiber?: boolean, // 开启fiber模式，可选 - baseroute?: string, // 设置子应用路由系统的基础路径，可选 - ssr?: boolean, // 开启ssr模式，可选 - // shadowDOM?: boolean, // 开启shadowDOM，可选 - data?: Object, // 传递给子应用的数据，可选 - onDataChange?: Function, // 获取子应用发送数据的监听函数，可选 - // 注册子应用的生命周期 - lifeCycles?: { - created(e: CustomEvent): void, // 加载资源前触发 - beforemount(e: CustomEvent): void, // 加载资源完成后，开始渲染之前触发 - mounted(e: CustomEvent): void, // 子应用渲染结束后触发 - unmount(e: CustomEvent): void, // 子应用卸载时触发 - error(e: CustomEvent): void, // 子应用渲染出错时触发 - beforeshow(e: CustomEvent): void, // 子应用推入前台之前触发（keep-alive模式特有） - aftershow(e: CustomEvent): void, // 子应用推入前台之后触发（keep-alive模式特有） - afterhidden(e: CustomEvent): void, // 子应用推入后台时触发（keep-alive模式特有） - }, -} - -/** - * @param options RenderAppOptions 配置项 - */ -function renderApp(options: RenderAppOptions): Promise -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -// 案例一 -microApp.renderApp({ - name: 'my-app', - url: 'http://localhost:3000', - container: '#container', -}).then((result) => { - if (result) { - console.log('渲染成功') - } else { - console.log('渲染失败') - } -}) - -// 案例二 -microApp.renderApp({ - name: 'my-app', - url: 'http://localhost:3000', - container: '#container', - inline: true, - data: { key: '初始化数据' }, - lifeCycles: { - mounted () { - console.log('子应用已经渲染') - }, - unmount () { - console.log('子应用已经卸载') - }, - } -}) -``` - -## document.microAppElement -**描述：**获取子应用所在的`micro-app`元素。 - -**限制：**只能在子应用内部使用，基座中可以使用`document.querySelector`获取micro-app元素 - -**使用方式：** -```js -document.microAppElement.appendChild(...) -``` - - -## setData -**描述：**向指定的子应用发送数据 - -**介绍：** -```js -setData(appName: String, data: Object) -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -// 发送数据给子应用 my-app，setData第二个参数只接受对象类型 -microApp.setData('my-app', {type: '新的数据'}) -``` - -## getData -**描述：**获取指定的子应用data数据 - -**介绍：** -```js -getData(appName: String): Object -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -const childData = microApp.getData('my-app') // 返回my-app子应用的data数据 -``` - -## addDataListener -**描述：**监听指定子应用的数据变化 - -**介绍：** -```js -/** - * 绑定监听函数 - * appName: 应用名称 - * dataListener: 绑定函数 - * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false - */ -microApp.addDataListener(appName: string, dataListener: Function, autoTrigger?: boolean) -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -function dataListener (data) { - console.log('来自子应用my-app的数据', data) -} - -microApp.addDataListener('my-app', dataListener) -``` - -## removeDataListener -**描述：**解除主应用的数据监听函数 - -**使用方式：** - -```js -import microApp from '@micro-zoe/micro-app' - -function dataListener (data) { - console.log('来自子应用my-app的数据', data) -} - -// 解绑监听my-app子应用的数据监听函数 -microApp.removeDataListener('my-app', dataListener) -``` - -## clearDataListener -**描述：**清空主应用的所有数据监听函数 - -**使用方式：** - -```js -import microApp from '@micro-zoe/micro-app' - -// 清空所有监听appName子应用的数据监听函数 -microApp.clearDataListener('my-app') -``` - - -## getGlobalData -**描述：**获取全局数据 - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -// 直接获取数据 -const globalData = microApp.getGlobalData() // 返回全局数据 -``` - - -## addGlobalDataListener -**描述：**绑定数据监听函数 - -**介绍：** -```js -/** - * 绑定监听函数 - * dataListener: 绑定函数 - * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false - */ -microApp.addGlobalDataListener(dataListener: Function, autoTrigger?: boolean) -``` - -**使用方式：** -```js -import microApp from '@micro-zoe/micro-app' - -function dataListener (data) { - console.log('全局数据', data) -} - -microApp.addGlobalDataListener(dataListener) -``` - -## removeGlobalDataListener -**描述：**解绑全局数据监听函数 - -**使用方式：** - -```js -import microApp from '@micro-zoe/micro-app' - -function dataListener (data) { - console.log('全局数据', data) -} - -microApp.removeGlobalDataListener(dataListener) -``` - -## clearGlobalDataListener -**描述：**清空主应用绑定的所有全局数据监听函数 - -**使用方式：** - -```js -import microApp from '@micro-zoe/micro-app' - -microApp.clearGlobalDataListener() -``` - -## setGlobalData -**描述：**发送全局数据 - -**使用方式：** - -```js -import microApp from '@micro-zoe/micro-app' - -// setGlobalData只接受对象作为参数 -microApp.setGlobalData({type: '全局数据'}) -``` diff --git a/docs/zh-cn/API/child-app.md b/docs/zh-cn/API/child-app.md deleted file mode 100644 index 5ed9a0565..000000000 --- a/docs/zh-cn/API/child-app.md +++ /dev/null @@ -1,184 +0,0 @@ -## pureCreateElement -**描述：**创建无绑定的纯净元素，该元素可以逃离元素隔离的边界，不受子应用沙箱的控制 - -**版本限制：** 0.8.2及以上版本 - -**使用方式：** -```js -const pureDiv = window.microApp.pureCreateElement('div') - -document.body.appendChild(pureDiv) -``` - - -## removeDomScope -**描述：**解除元素绑定，通常用于受子应用元素绑定影响，导致主应用元素错误绑定到子应用的情况 - -**版本限制：** 0.8.2及以上版本 - -**介绍：** -```js -/** - * @param force 解除元素绑定，并且一定时间内(一个微任务Promise时间)阻止再次绑定。 - */ -function removeDomScope(force?: boolean): void -``` - -**使用方式：** -```js -window.microApp.removeDomScope(true) // 解除元素绑定 -/** - * 中间区域的元素操作都指向主应用 - * 例如： - * document.body.appendChild(document.createElement('div')) - * div元素将插入到主应用body中 - */ -window.microApp.removeDomScope(false) // 恢复元素绑定 -``` - -## rawWindow -**描述：**获取真实的window - -**使用方式：** -```js -window.rawWindow -``` - -## rawDocument -**描述：**获取真实的document - -**使用方式：** -```js -window.rawDocument -``` - - -## getData -**描述：**获取主应用下发的data数据 - -**使用方式：** -```js -const data = window.microApp.getData() // 返回主应用下发的data数据 -``` - -## addDataListener -**描述：**绑定数据监听函数 - -**介绍：** -```js -/** - * 绑定监听函数，监听函数只有在数据变化时才会触发 - * dataListener: 绑定函数 - * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false - * !!!重要说明: 因为子应用是异步渲染的，而主应用发送数据是同步的， - * 如果在子应用渲染结束前主应用发送数据，则在绑定监听函数前数据已经发送，在初始化后不会触发绑定函数， - * 但这个数据会放入缓存中，此时可以设置autoTrigger为true主动触发一次监听函数来获取数据。 - */ -window.microApp.addDataListener(dataListener: Function, autoTrigger?: boolean) -``` - -**使用方式：** -```js -function dataListener (data) { - console.log('来自主应用的数据', data) -} - -window.microApp.addDataListener(dataListener) -``` - -## removeDataListener -**描述：**解绑数据监听函数 - -**使用方式：** - -```js -function dataListener (data) { - console.log('来自主应用的数据', data) -} - -window.microApp.removeDataListener(dataListener) -``` - -## clearDataListener -**描述：**清空当前子应用的所有数据监听函数(全局数据函数除外) - -**使用方式：** - -```js -window.microApp.clearDataListener() -``` - -## dispatch -**描述：**向主应用发送数据 - -**使用方式：** - -```js -// dispatch只接受对象作为参数 -window.microApp.dispatch({type: '子应用发送的数据'}) -``` - - -## getGlobalData -**描述：**获取全局数据 - -**使用方式：** -```js -const globalData = window.microApp.getGlobalData() // 返回全局数据 -``` - - -## addGlobalDataListener -**描述：**绑定数据监听函数 - -**介绍：** -```js -/** - * 绑定监听函数 - * dataListener: 绑定函数 - * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false - */ -window.microApp.addGlobalDataListener(dataListener: Function, autoTrigger?: boolean) - -``` - -**使用方式：** -```js -function dataListener (data) { - console.log('全局数据', data) -} - -window.microApp.addGlobalDataListener(dataListener) -``` - -## removeGlobalDataListener -**描述：**解绑全局数据监听函数 - -**使用方式：** - -```js -function dataListener (data) { - console.log('全局数据', data) -} - -window.microApp.removeGlobalDataListener(dataListener) -``` - -## clearGlobalDataListener -**描述：**清空当前子应用绑定的所有全局数据监听函数 - -**使用方式：** - -```js -window.microApp.clearGlobalDataListener() -``` - -## setGlobalData -**描述：**发送全局数据 - -**使用方式：** - -```js -// setGlobalData只接受对象作为参数 -window.microApp.setGlobalData({type: '全局数据'}) -``` From 9bb18cf4a1b44184057e1721737e68a826559f45 Mon Sep 17 00:00:00 2001 From: raoenhui Date: Tue, 30 Jul 2024 18:04:05 +0800 Subject: [PATCH 04/10] =?UTF-8?q?fix:=20=E5=A4=A7=E5=B0=8F=E5=86=99?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/zh-cn/api/base-app.md | 614 ++++++++++++++++++++++++++++++++++++ docs/zh-cn/api/child-app.md | 184 +++++++++++ 2 files changed, 798 insertions(+) create mode 100644 docs/zh-cn/api/base-app.md create mode 100644 docs/zh-cn/api/child-app.md diff --git a/docs/zh-cn/api/base-app.md b/docs/zh-cn/api/base-app.md new file mode 100644 index 000000000..71fbcb51f --- /dev/null +++ b/docs/zh-cn/api/base-app.md @@ -0,0 +1,614 @@ +## start +**描述：**micro-app注册函数，全局执行一次。 + +**介绍：** +```js +start (options?: { + tagName?: string, // 设置标签名称，默认为micro-app + iframe?: boolean, // 全局开启iframe沙箱，默认为false + inline?: boolean, // 全局开启内联script模式运行js，默认为false + destroy?: boolean, // 全局开启destroy模式，卸载时强制删除缓存资源，默认为false + // shadowDOM?: boolean, // 全局开启shadowDOM模式，默认为false + ssr?: boolean, // 全局开启ssr模式，默认为false + 'disable-scopecss'?: boolean, // 全局禁用样式隔离，默认为false + 'disable-sandbox'?: boolean, // 全局禁用沙箱，默认为false + 'keep-alive'?: boolean, // 全局开启保活模式，默认为false + 'disable-memory-router'?: boolean, // 全局关闭虚拟路由系统，默认值false + 'keep-router-state'?: boolean, // 子应用在卸载时保留路由状态，默认值false + 'disable-patch-request'?: boolean, // 关闭子应用请求的自动补全功能，默认值false + 'router-mode'?: string, // 设置路由模式，共四种：search、native、native-scope、pure，默认为search + iframeSrc?: string, // 设置iframe沙箱中iframe的src地址，默认为子应用所在页面地址 + // 全局生命周期 + lifeCycles?: { + created?(e?: CustomEvent): void + beforemount?(e?: CustomEvent): void + mounted?(e?: CustomEvent): void + unmount?(e?: CustomEvent): void + error?(e?: CustomEvent): void + }, + // 预加载，支持数组或函数 + preFetchApps?: Array<{ + name: string, + url: string, + disableScopecss?: boolean, + disableSandbox?: boolean, + // shadowDOM?: boolean + }> | (() => Array<{ + name: string, + url: string, + disableScopecss?: boolean, + disableSandbox?: boolean, + // shadowDOM?: boolean + }>), + // 插件系统，用于处理子应用的js文件 + plugins?: { + // 全局插件，作用于所有子应用的js文件 + global?: Array<{ + // 可选，强隔离的全局变量(默认情况下子应用无法找到的全局变量会兜底到主应用中，scopeProperties可以禁止这种情况) + scopeProperties?: string[], + // 可选，可以逃逸到外部的全局变量(escapeProperties中的变量会同时赋值到子应用和外部真实的window上) + escapeProperties?: string[], + // 可选，如果函数返回 `true` 则忽略 script 和 link 标签的创建 + excludeChecker?: (url: string) => boolean + // 可选，如果函数返回 `true` ，则 micro-app 不会处理它，元素将原封不动进行渲染 + ignoreChecker?: (url: string) => boolean + // 可选，传递给loader的配置项 + options?: any, + // 可选，js处理函数，必须返回 code 值 + loader?: (code: string, url: string, options: any, info: sourceScriptInfo) => string, + // 可选，html 处理函数，必须返回 code 值 + processHtml?: (code: string, url: string, options: unknown) => string + }> + + // 子应用插件 + modules?: { + // appName为应用的名称，这些插件只会作用于指定的应用 + [name: string]: Array<{ + // 可选，强隔离的全局变量(默认情况下子应用无法找到的全局变量会兜底到主应用中，scopeProperties可以禁止这种情况) + scopeProperties?: string[], + // 可选，可以逃逸到外部的全局变量(escapeProperties中的变量会同时赋值到子应用和外部真实的window上) + escapeProperties?: string[], + // 可选，如果函数返回 `true` 则忽略 script 和 link 标签的创建 + excludeChecker?: (url: string) => boolean + // 可选，如果函数返回 `true` ，则 micro-app 不会处理它，元素将原封不动进行渲染 + ignoreChecker?: (url: string) => boolean + // 可选，传递给loader的配置项 + options?: any, + // 必填，js处理函数，必须返回code值 + loader?: (code: string, url: string, options: any, info: sourceScriptInfo) => string, + // 可选，html 处理函数，必须返回 code 值 + processHtml?: (code: string, url: string, options: unknown) => string + }> + } + }, + // 重定义fetch方法，可以用于拦截资源请求操作 + fetch?: (url: string, options: Record, appName: string | null) => Promise + // 设置全局静态资源 + globalAssets?: { + js?: string[], // js地址 + css?: string[], // css地址 + }, + // 指定部分特殊的动态加载的微应用资源（css/js) 不被 micro-app 劫持处理 + excludeAssetFilter?: (assetUrl: string) => boolean + // 基座对子应用 document 的一些属性进行自定义代理扩展 + customProxyDocumentProps?: Map void> +}) +``` + +**使用方式：** +```js +// index.js +import microApp from '@micro-zoe/micro-app' + +microApp.start() +``` + +## preFetch +**描述：**预加载，在浏览器空闲时间，依照开发者传入的顺序，依次加载每个应用的静态资源 + +**介绍：** +```js +preFetch([ + { + name: string, + url: string, + disableScopecss?: boolean, + disableSandbox?: boolean, + }, +]) +``` + +**使用方式：** +```js +import { preFetch } from '@micro-zoe/micro-app' + +// 方式一 +preFetch([ + { name: 'my-app1', url: 'xxx' }, + { name: 'my-app2', url: 'xxx' }, +]) + +// 方式二 +preFetch(() => [ + { name: 'my-app1', url: 'xxx' }, + { name: 'my-app2', url: 'xxx' }, +]) +``` + + +## getActiveApps +**描述：**获取正在运行的子应用，不包含已卸载和预加载的应用 + +**版本限制：** 0.5.2及以上版本 + +**介绍：** +```js +/** + * getActiveApps接受一个对象作为参数，详情如下： + * @param excludeHiddenApp 是否过滤处于隐藏状态的keep-alive应用，默认false + * @param excludePreRender 是否过滤预渲染的应用，默认false + */ +function getActiveApps({ + excludeHiddenApp?: boolean, + excludePreRender?: boolean, +}): string[] +``` + +**使用方式：** +```js +import { getActiveApps } from '@micro-zoe/micro-app' + +// 获取所有正在运行的应用的名称 +getActiveApps() // [子应用1name, 子应用2name, ...] + +// 获取所有正在运行的应用的名称，但不包括已经处于隐藏状态的keep-alive应用 +getActiveApps({ excludeHiddenApp: true }) + +// 获取所有正在运行的应用的名称，但不包括预渲染应用 +getActiveApps({ excludePreRender: true }) +``` + +## getAllApps +**描述：**获取所有子应用，包含已卸载和预加载的应用 + +**版本限制：** 0.5.2及以上版本 + +**介绍：** +```js +function getAllApps(): string[] +``` + +**使用方式：** +```js +import { getAllApps } from '@micro-zoe/micro-app' + +getAllApps() // [子应用name, 子应用name, ...] +``` + + +## version +**描述：**查看版本号 + +**方式1：** +```js +import { version } from '@micro-zoe/micro-app' +``` + +**方式2：**通过micro-app元素上的version属性查看 +```js +document.querySelector('micro-app').version +``` + +## pureCreateElement +**描述：**创建无绑定的纯净元素 + +**使用方式：** +```js +import { pureCreateElement } from '@micro-zoe/micro-app' + +const pureDiv = pureCreateElement('div') + +document.body.appendChild(pureDiv) +``` + + +## removeDomScope +**描述：**解除元素绑定，通常用于受子应用元素绑定影响，导致主应用元素错误绑定到子应用的情况 + +**介绍：** +```js +/** + * @param force 解除元素绑定，并且一定时间内(一个微任务Promise时间)阻止再次绑定。 + */ +function removeDomScope(force?: boolean): void +``` + +**使用方式：** +```js +import { removeDomScope } from '@micro-zoe/micro-app' + +removeDomScope(true) // 解除元素绑定 +/** + * 中间区域的元素操作都指向主应用 + * 例如： + * document.body.appendChild(document.createElement('div')) + * div元素将插入到主应用body中 + */ +removeDomScope(false) // 恢复元素绑定 +``` + + +## unmountApp +**描述：**手动卸载应用 + +**版本限制：** 0.6.1及以上版本 + +**介绍：** +```js +// unmountApp 参数配置 +interface unmountAppParams { + /** + * destroy: 是否强制卸载应用并删除缓存资源，默认值：false + * 优先级: 高于 clearAliveState + * 对于已经卸载的应用: 当子应用已经卸载或keep-alive应用已经推入后台，则清除应用状态及缓存资源 + * 对于正在运行的应用: 当子应用正在运行，则卸载应用并删除状态及缓存资源 + */ + destroy?: boolean + /** + * clearAliveState: 是否清空应用的缓存状态，默认值：false + * 解释: 如果子应用是keep-alive，则卸载并清空状态，并保留缓存资源，如果子应用不是keep-alive，则执行正常卸载流程，并保留缓存资源 + * 补充: 无论keep-alive应用正在运行还是已经推入后台，都将执行卸载操作，清空应用缓存状态，并保留缓存资源 + */ + clearAliveState?: boolean +} + +function unmountApp(appName: string, options?: unmountAppParams): Promise +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +// 正常流程 +microApp.unmountApp(子应用名称).then(() => console.log('卸载成功')) + +// 卸载应用并清空缓存资源 +microApp.unmountApp(子应用名称, { destroy: true }).then(() => console.log('卸载成功')) + +// 如果子应用是keep-alive应用，则卸载并清空状态，如果子应用不是keep-alive应用，则正常卸载 +microApp.unmountApp(子应用名称, { clearAliveState: true }).then(() => console.log('卸载成功')) + +// 如果destroy和clearAliveState同时为true，则clearAliveState将失效 +microApp.unmountApp(子应用名称, { destroy: true, clearAliveState: true }).then(() => console.log('卸载成功')) +``` + +## unmountAllApps +**描述：**手动卸载所有应用 + +**版本限制：** 0.6.1及以上版本 + +**介绍：** +```js +// unmountAllApps 参数配置 +interface unmountAppParams { + /** + * destroy: 是否强制卸载应用并删除缓存资源，默认值：false + * 优先级: 高于 clearAliveState + * 对于已经卸载的应用: 当子应用已经卸载或keep-alive应用已经推入后台，则清除应用状态及缓存资源 + * 对于正在运行的应用: 当子应用正在运行，则卸载应用并删除状态及缓存资源 + */ + destroy?: boolean + /** + * clearAliveState: 是否清空应用的缓存状态，默认值：false + * 解释: 如果子应用是keep-alive，则卸载并清空状态，并保留缓存资源，如果子应用不是keep-alive，则执行正常卸载流程，并保留缓存资源 + * 补充: 无论keep-alive应用正在运行还是已经推入后台，都将执行卸载操作，清空应用缓存状态，并保留缓存资源 + */ + clearAliveState?: boolean +} + +function unmountAllApps(options?: unmountAppParams): Promise +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +// 正常流程 +microApp.unmountAllApps().then(() => console.log('卸载成功')) + +// 卸载所有应用并清空缓存资源 +microApp.unmountAllApps({ destroy: true }).then(() => console.log('卸载成功')) + +// 如果子应用是keep-alive应用，则卸载并清空状态，如果子应用不是keep-alive应用，则正常卸载 +microApp.unmountAllApps({ clearAliveState: true }).then(() => console.log('卸载成功')) + +// 如果destroy和clearAliveState同时为true，则clearAliveState将失效 +microApp.unmountAllApps({ destroy: true, clearAliveState: true }).then(() => console.log('卸载成功')) +``` + + +## reload +**描述：**重新渲染子应用 + +**版本限制：** 1.0.0及以上版本 + +**介绍：** +```js +/** + * @param appName 应用名称，必传 + * @param destroy 重新渲染时是否彻底删除缓存值，可选 + */ +function reload(appName: string, destroy?: boolean): Promise +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +// 案例一：重新渲染子应用my-app +microApp.reload('my-app').then((result) => { + if (result) { + console.log('重新渲染成功') + } else { + console.log('重新渲染失败') + } +}) + +// 案例二：重新渲染子应用my-app，并彻底删除缓存值 +microApp.reload('my-app', true).then((result) => { + if (result) { + console.log('重新渲染成功') + } else { + console.log('重新渲染失败') + } +}) +``` + +## renderApp +**描述：**手动渲染子应用 + +**介绍：** +```js +interface RenderAppOptions { + name: string, // 应用名称，必传 + url: string, // 应用地址，必传 + container: string | Element, // 应用容器或选择器，必传 + iframe?: boolean, // 是否切换为iframe沙箱，可选 + inline?: boolean, // 开启内联模式运行js，可选 + 'disable-scopecss'?: boolean, // 关闭样式隔离，可选 + 'disable-sandbox'?: boolean, // 关闭沙箱，可选 + 'disable-memory-router'?: boolean, // 关闭虚拟路由系统，可选 + 'default-page'?: string, // 指定默认渲染的页面，可选 + 'keep-router-state'?: boolean, // 保留路由状态，可选 + 'disable-patch-request'?: boolean, // 关闭子应用请求的自动补全功能，可选 + 'keep-alive'?: boolean, // 开启keep-alive模式，可选 + destroy?: boolean, // 卸载时强制删除缓存资源，可选 + fiber?: boolean, // 开启fiber模式，可选 + baseroute?: string, // 设置子应用路由系统的基础路径，可选 + ssr?: boolean, // 开启ssr模式，可选 + // shadowDOM?: boolean, // 开启shadowDOM，可选 + data?: Object, // 传递给子应用的数据，可选 + onDataChange?: Function, // 获取子应用发送数据的监听函数，可选 + // 注册子应用的生命周期 + lifeCycles?: { + created(e: CustomEvent): void, // 加载资源前触发 + beforemount(e: CustomEvent): void, // 加载资源完成后，开始渲染之前触发 + mounted(e: CustomEvent): void, // 子应用渲染结束后触发 + unmount(e: CustomEvent): void, // 子应用卸载时触发 + error(e: CustomEvent): void, // 子应用渲染出错时触发 + beforeshow(e: CustomEvent): void, // 子应用推入前台之前触发（keep-alive模式特有） + aftershow(e: CustomEvent): void, // 子应用推入前台之后触发（keep-alive模式特有） + afterhidden(e: CustomEvent): void, // 子应用推入后台时触发（keep-alive模式特有） + }, +} + +/** + * @param options RenderAppOptions 配置项 + */ +function renderApp(options: RenderAppOptions): Promise +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +// 案例一 +microApp.renderApp({ + name: 'my-app', + url: 'http://localhost:3000', + container: '#container', +}).then((result) => { + if (result) { + console.log('渲染成功') + } else { + console.log('渲染失败') + } +}) + +// 案例二 +microApp.renderApp({ + name: 'my-app', + url: 'http://localhost:3000', + container: '#container', + inline: true, + data: { key: '初始化数据' }, + lifeCycles: { + mounted () { + console.log('子应用已经渲染') + }, + unmount () { + console.log('子应用已经卸载') + }, + } +}) +``` + +## document.microAppElement +**描述：**获取子应用所在的`micro-app`元素。 + +**限制：**只能在子应用内部使用，基座中可以使用`document.querySelector`获取micro-app元素 + +**使用方式：** +```js +document.microAppElement.appendChild(...) +``` + + +## setData +**描述：**向指定的子应用发送数据 + +**介绍：** +```js +setData(appName: String, data: Object) +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +// 发送数据给子应用 my-app，setData第二个参数只接受对象类型 +microApp.setData('my-app', {type: '新的数据'}) +``` + +## getData +**描述：**获取指定的子应用data数据 + +**介绍：** +```js +getData(appName: String): Object +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +const childData = microApp.getData('my-app') // 返回my-app子应用的data数据 +``` + +## addDataListener +**描述：**监听指定子应用的数据变化 + +**介绍：** +```js +/** + * 绑定监听函数 + * appName: 应用名称 + * dataListener: 绑定函数 + * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false + */ +microApp.addDataListener(appName: string, dataListener: Function, autoTrigger?: boolean) +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +function dataListener (data) { + console.log('来自子应用my-app的数据', data) +} + +microApp.addDataListener('my-app', dataListener) +``` + +## removeDataListener +**描述：**解除主应用的数据监听函数 + +**使用方式：** + +```js +import microApp from '@micro-zoe/micro-app' + +function dataListener (data) { + console.log('来自子应用my-app的数据', data) +} + +// 解绑监听my-app子应用的数据监听函数 +microApp.removeDataListener('my-app', dataListener) +``` + +## clearDataListener +**描述：**清空主应用的所有数据监听函数 + +**使用方式：** + +```js +import microApp from '@micro-zoe/micro-app' + +// 清空所有监听appName子应用的数据监听函数 +microApp.clearDataListener('my-app') +``` + + +## getGlobalData +**描述：**获取全局数据 + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +// 直接获取数据 +const globalData = microApp.getGlobalData() // 返回全局数据 +``` + + +## addGlobalDataListener +**描述：**绑定数据监听函数 + +**介绍：** +```js +/** + * 绑定监听函数 + * dataListener: 绑定函数 + * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false + */ +microApp.addGlobalDataListener(dataListener: Function, autoTrigger?: boolean) +``` + +**使用方式：** +```js +import microApp from '@micro-zoe/micro-app' + +function dataListener (data) { + console.log('全局数据', data) +} + +microApp.addGlobalDataListener(dataListener) +``` + +## removeGlobalDataListener +**描述：**解绑全局数据监听函数 + +**使用方式：** + +```js +import microApp from '@micro-zoe/micro-app' + +function dataListener (data) { + console.log('全局数据', data) +} + +microApp.removeGlobalDataListener(dataListener) +``` + +## clearGlobalDataListener +**描述：**清空主应用绑定的所有全局数据监听函数 + +**使用方式：** + +```js +import microApp from '@micro-zoe/micro-app' + +microApp.clearGlobalDataListener() +``` + +## setGlobalData +**描述：**发送全局数据 + +**使用方式：** + +```js +import microApp from '@micro-zoe/micro-app' + +// setGlobalData只接受对象作为参数 +microApp.setGlobalData({type: '全局数据'}) +``` diff --git a/docs/zh-cn/api/child-app.md b/docs/zh-cn/api/child-app.md new file mode 100644 index 000000000..5ed9a0565 --- /dev/null +++ b/docs/zh-cn/api/child-app.md @@ -0,0 +1,184 @@ +## pureCreateElement +**描述：**创建无绑定的纯净元素，该元素可以逃离元素隔离的边界，不受子应用沙箱的控制 + +**版本限制：** 0.8.2及以上版本 + +**使用方式：** +```js +const pureDiv = window.microApp.pureCreateElement('div') + +document.body.appendChild(pureDiv) +``` + + +## removeDomScope +**描述：**解除元素绑定，通常用于受子应用元素绑定影响，导致主应用元素错误绑定到子应用的情况 + +**版本限制：** 0.8.2及以上版本 + +**介绍：** +```js +/** + * @param force 解除元素绑定，并且一定时间内(一个微任务Promise时间)阻止再次绑定。 + */ +function removeDomScope(force?: boolean): void +``` + +**使用方式：** +```js +window.microApp.removeDomScope(true) // 解除元素绑定 +/** + * 中间区域的元素操作都指向主应用 + * 例如： + * document.body.appendChild(document.createElement('div')) + * div元素将插入到主应用body中 + */ +window.microApp.removeDomScope(false) // 恢复元素绑定 +``` + +## rawWindow +**描述：**获取真实的window + +**使用方式：** +```js +window.rawWindow +``` + +## rawDocument +**描述：**获取真实的document + +**使用方式：** +```js +window.rawDocument +``` + + +## getData +**描述：**获取主应用下发的data数据 + +**使用方式：** +```js +const data = window.microApp.getData() // 返回主应用下发的data数据 +``` + +## addDataListener +**描述：**绑定数据监听函数 + +**介绍：** +```js +/** + * 绑定监听函数，监听函数只有在数据变化时才会触发 + * dataListener: 绑定函数 + * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false + * !!!重要说明: 因为子应用是异步渲染的，而主应用发送数据是同步的， + * 如果在子应用渲染结束前主应用发送数据，则在绑定监听函数前数据已经发送，在初始化后不会触发绑定函数， + * 但这个数据会放入缓存中，此时可以设置autoTrigger为true主动触发一次监听函数来获取数据。 + */ +window.microApp.addDataListener(dataListener: Function, autoTrigger?: boolean) +``` + +**使用方式：** +```js +function dataListener (data) { + console.log('来自主应用的数据', data) +} + +window.microApp.addDataListener(dataListener) +``` + +## removeDataListener +**描述：**解绑数据监听函数 + +**使用方式：** + +```js +function dataListener (data) { + console.log('来自主应用的数据', data) +} + +window.microApp.removeDataListener(dataListener) +``` + +## clearDataListener +**描述：**清空当前子应用的所有数据监听函数(全局数据函数除外) + +**使用方式：** + +```js +window.microApp.clearDataListener() +``` + +## dispatch +**描述：**向主应用发送数据 + +**使用方式：** + +```js +// dispatch只接受对象作为参数 +window.microApp.dispatch({type: '子应用发送的数据'}) +``` + + +## getGlobalData +**描述：**获取全局数据 + +**使用方式：** +```js +const globalData = window.microApp.getGlobalData() // 返回全局数据 +``` + + +## addGlobalDataListener +**描述：**绑定数据监听函数 + +**介绍：** +```js +/** + * 绑定监听函数 + * dataListener: 绑定函数 + * autoTrigger: 在初次绑定监听函数时如果有缓存数据，是否需要主动触发一次，默认为false + */ +window.microApp.addGlobalDataListener(dataListener: Function, autoTrigger?: boolean) + +``` + +**使用方式：** +```js +function dataListener (data) { + console.log('全局数据', data) +} + +window.microApp.addGlobalDataListener(dataListener) +``` + +## removeGlobalDataListener +**描述：**解绑全局数据监听函数 + +**使用方式：** + +```js +function dataListener (data) { + console.log('全局数据', data) +} + +window.microApp.removeGlobalDataListener(dataListener) +``` + +## clearGlobalDataListener +**描述：**清空当前子应用绑定的所有全局数据监听函数 + +**使用方式：** + +```js +window.microApp.clearGlobalDataListener() +``` + +## setGlobalData +**描述：**发送全局数据 + +**使用方式：** + +```js +// setGlobalData只接受对象作为参数 +window.microApp.setGlobalData({type: '全局数据'}) +``` From 1794813f7a1387a579dae0c2cfd44541b8a0f113 Mon Sep 17 00:00:00 2001 From: iceRao Date: Wed, 31 Jul 2024 21:33:16 +0800 Subject: [PATCH 05/10] Update Contact.md --- Contact.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Contact.md b/Contact.md index 72332fee6..fb5f421aa 100644 --- a/Contact.md +++ b/Contact.md @@ -1,7 +1,8 @@ 欢迎小伙伴们加入micro-app微信群交流^ ^ -![IMG_9187](https://github.com/user-attachments/assets/64d16edc-311a-46ea-8ce7-c6fcbe0651d3) +![IMG_9654](https://github.com/user-attachments/assets/f94085c2-5f69-4e47-8380-830d14a19e03) + From 7e216ce3b23f71764f6eae24cf0758793c458560 Mon Sep 17 00:00:00 2001 From: iceRao Date: Wed, 7 Aug 2024 14:00:09 +0800 Subject: [PATCH 06/10] Update Contact.md --- Contact.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contact.md b/Contact.md index fb5f421aa..635ed0de9 100644 --- a/Contact.md +++ b/Contact.md @@ -1,7 +1,7 @@ 欢迎小伙伴们加入micro-app微信群交流^ ^ -![IMG_9654](https://github.com/user-attachments/assets/f94085c2-5f69-4e47-8380-830d14a19e03) +![IMG_0020](https://github.com/user-attachments/assets/7f0d6e15-4230-47fb-923a-202ee34e7415) From dd43e4fb0c30e51eec568cb198f51177d44b03e9 Mon Sep 17 00:00:00 2001 From: bailicangdu <1264889788@qq.com> Date: Tue, 13 Aug 2024 23:07:34 +0800 Subject: [PATCH 07/10] docs(1.0.0-rc.7): add question 18 of cookie --- dev/children/react16/src/index.js | 2 ++ dev/main-react16/src/pages/react16/react16.js | 4 ++-- docs/navbar.md | 4 +++- docs/sidebar.md | 2 +- docs/zh-cn/advanced.md | 4 ++-- docs/zh-cn/questions.md | 22 +++++++++++++++++++ src/sandbox/router/location.ts | 12 +++++----- 7 files changed, 38 insertions(+), 12 deletions(-) diff --git a/dev/children/react16/src/index.js b/dev/children/react16/src/index.js index b3c759871..d11c37971 100644 --- a/dev/children/react16/src/index.js +++ b/dev/children/react16/src/index.js @@ -615,3 +615,5 @@ console.log('micro-app容器元素document.microAppElement', document.microAppEl // // window.microApp.removeDomScope(false) // }, 1000); // } + +console.log(111111, location.href) diff --git a/dev/main-react16/src/pages/react16/react16.js b/dev/main-react16/src/pages/react16/react16.js index 8657c03ac..a3ac3ec73 100644 --- a/dev/main-react16/src/pages/react16/react16.js +++ b/dev/main-react16/src/pages/react16/react16.js @@ -23,7 +23,7 @@ export default class App extends React.Component { showMicroApp: true, testNum: 0, showModal: false, - routerMode: 'state', + routerMode: 'native', baseroute: '/micro-app/demo/react16', } @@ -442,7 +442,7 @@ export default class App extends React.Component { // disable-memory-router router-mode={this.state.routerMode} // keep-router-state - // default-page='/micro-app/react16/page2' + default-page='/micro-app/react16/page2' // hidden-router // disable-patch-request // fiber diff --git a/docs/navbar.md b/docs/navbar.md index 4ea4bbdcc..11a52c874 100755 --- a/docs/navbar.md +++ b/docs/navbar.md @@ -1,6 +1,8 @@ -- [API](zh-cn/api) - [Micro-App-DevTools](zh-cn/micro-app-devtools) - [常见问题](zh-cn/questions) +- API + - [主应用API](zh-cn/api/base-app) + - [子应用API](zh-cn/api/child-app) - Translations - [:cn: 中文](/zh-cn/) - [:uk: English](/en-us/) diff --git a/docs/sidebar.md b/docs/sidebar.md index 6f3c5c668..6d7aeb111 100755 --- a/docs/sidebar.md +++ b/docs/sidebar.md @@ -34,7 +34,7 @@ - [子应用API](zh-cn/api/child-app) - 其他 + - [常见问题](zh-cn/questions) - [Micro-App-DevTools](zh-cn/micro-app-devtools) - [部署](zh-cn/deploy) - - [常见问题](zh-cn/questions) - [更新日志](zh-cn/changelog) diff --git a/docs/zh-cn/advanced.md b/docs/zh-cn/advanced.md index 02d15b9b8..2829f4761 100644 --- a/docs/zh-cn/advanced.md +++ b/docs/zh-cn/advanced.md @@ -1,4 +1,4 @@ -## 1、自定义fetch +## 1、自定义fetch :id=custom-fetch 通过自定义fetch替换框架自带的fetch，可以修改fetch配置(添加cookie或header信息等等)，或拦截HTML、JS、CSS等静态资源。 自定义的fetch必须是一个返回string类型的Promise。 @@ -33,4 +33,4 @@ microApp.start({ ``` > [!NOTE] -> 1、如果跨域请求带cookie，那么`Access-Control-Allow-Origin`不能设置为`*`，必须指定域名，同时设置`Access-Control-Allow-Credentials: true` \ No newline at end of file +> 需要注意的是，如果跨域请求带cookie，那么`Access-Control-Allow-Origin`不能设置为`*`，必须指定域名，同时设置`Access-Control-Allow-Credentials: true` diff --git a/docs/zh-cn/questions.md b/docs/zh-cn/questions.md index d8ff681eb..e0f9e5f60 100644 --- a/docs/zh-cn/questions.md +++ b/docs/zh-cn/questions.md @@ -138,3 +138,25 @@ micro-app依赖于CustomElements和Proxy两个较新的API。 ## 17、一个页面加载过多个微前端 :id=17 微前端在过多加载和深度嵌套时，要谨慎使用，尤其同个页面在不同版本微前端之间可能会有相互影响，使用者要酌情处理。 + +## 18、子应用加载资源或请求接口时没有带上cookie :id=18 + + +#### ** 场景1：加载子应用的静态资源时没有带上cookie ** + +**原因：**MicroApp加载子应用的html、js等静态资源时默认不带cookie + +**解决方式：**通过自定义MicroApp的fetch方法，修改fetch的credentials配置，具体步骤参考[自定义fetch](/zh-cn/advanced?id=custom-fetch) + +> [!NOTE] +> 需要注意的是，由于带了cookie，那么子应用的跨域配置`Access-Control-Allow-Origin`不能设置为`*`，必须指定域名，同时设置`Access-Control-Allow-Credentials: true` + + + +#### ** 场景2：子应用请求接口时没有带上cookie ** + +**原因：**常见于子应用域名与接口域名相同，而与主应用域名不同的场景，主应用域名与cookie Domain不匹配，导致无法携带cookie + +**解决方式：**让后端在写入cookie时设置SameSite为None + + diff --git a/src/sandbox/router/location.ts b/src/sandbox/router/location.ts index b79b50d98..c515a9ff3 100644 --- a/src/sandbox/router/location.ts +++ b/src/sandbox/router/location.ts @@ -364,12 +364,12 @@ export function updateMicroLocation ( } /** - * native模式从state中取值，而浏览器地址的修改无法控制，很可能出现浏览器地址和__MICRO_APP_STATE__不一致的情况 - * 尤其是在初始化和前进后退时，由于vue-router4会主动修改url地址，倒是上述情况经常出现 - * 为了结局这个问题，在子应用初始化和响应popstate事件后，判断__MICRO_APP_STATE__和浏览器地址是否一致，如果不一致，则将浏览器地址更新为__MICRO_APP_STATE__的地址 - * 说明： - * 1、如果__MICRO_APP_STATE__和url不一样，那么更新url的操作是对的，否则会产生url和渲染页面不一致的问题，开发者会更加困惑 - * 2、当native模式有多个子应用同时存在，其中一个修改url地址，另外一个并不会改变__MICRO_APP_STATE__，刷新就产生问题，不一致，第二是根据谁更新url？ + * The native mode also base of history.state, and the modification of the browser url cannot be controlled. It is very likely that the browser url and __MICRO_APP_STATE__ are different. + * Especially during init of child or forward and backward of browser, because vue-router@4 will actively modify the browser URL, the above situation often occurs + * To solve this problem, after child app is initialized and responds to the popstateEvent, it is determined whether __MICRO_APP_STATE__ and the browser url are different. If they are different, the browser url will updated to the address of __MICRO_APP_STATE__ + * NOTE: + * 1. If __MICRO_APP_STATE__ is different from the URL, then the operation of updating the URL is correct, otherwise there will be a problem of inconsistency between the URL and the rendered page + * 2. When there are multiple child app in native mode, if one of them changes the URL address, the other one will not change __MICRO_APP_STATE__, and refresh browser will cause problems */ const rawLocation = globalEnv.rawWindow.location if ( From 9197f1ec99f19402c1fb6ecb0a4cbe99e50044a3 Mon Sep 17 00:00:00 2001 From: iceRao Date: Thu, 15 Aug 2024 16:08:50 +0800 Subject: [PATCH 08/10] Update Contact.md --- Contact.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Contact.md b/Contact.md index 635ed0de9..1754b434d 100644 --- a/Contact.md +++ b/Contact.md @@ -1,7 +1,8 @@ 欢迎小伙伴们加入micro-app微信群交流^ ^ -![IMG_0020](https://github.com/user-attachments/assets/7f0d6e15-4230-47fb-923a-202ee34e7415) +![image](https://github.com/user-attachments/assets/35f37851-32e1-4751-aa80-2cfc28741988) + From 1925f3e55349f01bdb9282fb09a3ec622dcf85fe Mon Sep 17 00:00:00 2001 From: bailicangdu <1264889788@qq.com> Date: Mon, 19 Aug 2024 21:10:42 +0800 Subject: [PATCH 09/10] fix(1.0.0-rc.7): fix bug for default-page of vue-router@4 in rc.6 --- dev/children/react16/src/index.js | 2 -- dev/main-react16/src/pages/react16/react16.js | 2 +- docs/zh-cn/changelog.md | 19 +++++++++++-------- docs/zh-cn/configure.md | 2 +- docs/zh-cn/sandbox.md | 9 ++++++--- src/sandbox/iframe/document.ts | 19 ++++++++++++++++--- src/sandbox/iframe/index.ts | 2 +- 7 files changed, 36 insertions(+), 19 deletions(-) diff --git a/dev/children/react16/src/index.js b/dev/children/react16/src/index.js index d11c37971..b3c759871 100644 --- a/dev/children/react16/src/index.js +++ b/dev/children/react16/src/index.js @@ -615,5 +615,3 @@ console.log('micro-app容器元素document.microAppElement', document.microAppEl // // window.microApp.removeDomScope(false) // }, 1000); // } - -console.log(111111, location.href) diff --git a/dev/main-react16/src/pages/react16/react16.js b/dev/main-react16/src/pages/react16/react16.js index a3ac3ec73..2f1445ddc 100644 --- a/dev/main-react16/src/pages/react16/react16.js +++ b/dev/main-react16/src/pages/react16/react16.js @@ -448,7 +448,7 @@ export default class App extends React.Component { // fiber // ssr // clear-data - iframe + // iframe > ) diff --git a/docs/zh-cn/changelog.md b/docs/zh-cn/changelog.md index 9eb543730..2a403d1b4 100644 --- a/docs/zh-cn/changelog.md +++ b/docs/zh-cn/changelog.md @@ -8,12 +8,22 @@ --- +### 1.0.0-rc.7 + +`2024-8-20` + +- **Bug Fix** + - 🐞 修复 vue3子应用初始化时，`createWebHistory()`参数为空导致默认页面跳转异常的问题，[issue 1317](https://github.com/micro-zoe/micro-app/issues/1317)、[issue 1318](https://github.com/micro-zoe/micro-app/issues/1318)、[issue 1335](https://github.com/micro-zoe/micro-app/issues/1335)。 + +- **Update** + - 🚀 更新 内存优化相关文档。 + + ### 1.0.0-rc.6 `2024-7-29` - **Bug Fix** - - 🐞 修复 iframe沙箱下history.go传入的是非0数字时iframe被重置导致异常的问题，[PR 1112](https://github.com/micro-zoe/micro-app/pull/1112) by [keuby](https://github.com/keuby)。 - 🐞 修复 iframe沙箱下子应用事件类型判断异常的问题，[issue 975](https://github.com/micro-zoe/micro-app/issues/975)，[issue 1120](https://github.com/micro-zoe/micro-app/issues/1120)，[PR 985](https://github.com/micro-zoe/micro-app/pull/985) by [keuby](https://github.com/keuby)。 - 🐞 修复 UnoCSS等异步注册mount、unmount场景下导致umd模式加载失败的问题，[issue 881](https://github.com/micro-zoe/micro-app/issues/881)、[issue 1047](https://github.com/micro-zoe/micro-app/issues/1047)、[issue 1179](https://github.com/micro-zoe/micro-app/issues/1179)、[issue 1218](https://github.com/micro-zoe/micro-app/issues/1218)。 @@ -54,11 +64,9 @@ `2024-4-29` - **New** - - 🆕 新增虚拟路由系统`state`模式，用于适配更多使用场景。 - **Bug Fix** - - 🐞 修复了iframe沙箱下`unhandledrejection`事件失效的问题，[issue 1102](https://github.com/micro-zoe/micro-app/issues/1102)、[issue 1159](https://github.com/micro-zoe/micro-app/issues/1159)。 - 🐞 修复了with沙箱下`keep-alive`子应用二次渲染后无法通过`microApp.router`控制跳转的问题，[issue 1115](https://github.com/micro-zoe/micro-app/issues/1115)。 - 🐞 修复了with沙箱下预渲染子应用路由跳转异常的问题。 @@ -73,7 +81,6 @@ - 🐞 修复了虚拟路由系统pure模式下，通过location进行跳转表现异常的问题，[issue 1135](https://github.com/micro-zoe/micro-app/issues/1135)。 - **Update** - - 🚀 优化了生命周期全局监听函数的传递参数。 - 🚀 更新了路由相关文档。 @@ -83,7 +90,6 @@ `2024-1-31` - **New** - - 🆕 新增全局配置`iframeSrc`，用于动态设置iframe沙箱的src地址。 - 🆕 新增micro-app元素公有变量`publicPath`、`baseRoute`，用于支持chrome插件，[PR 1052](https://github.com/micro-zoe/micro-app/pull/1052) by [raoenhui](https://github.com/raoenhui)。 - 🆕 新增了在iframe沙箱下对`Document.prototype.createElementNS`、`Document.prototype.createDocumentFragment`的拦截和处理。 @@ -91,7 +97,6 @@ - 🆕 新增了with沙箱对于`Document.prototype.createElementNS`的直接处理，规避可能存在的元素泄漏风险。 - **Bug Fix** - - 🐞 修复了父应用非根目录下微应用无法正常渲染的问题，[PR 1037](https://github.com/micro-zoe/micro-app/pull/1037) by [xuhongbo](https://github.com/xuhongbo)。 - 🐞 修复了iframe沙箱下antd `Dropdown`、`Tooltip`等组件渲染异常的问题，[PR 1015](https://github.com/micro-zoe/micro-app/pull/1015) by [keuby](https://github.com/keuby)。 - 🐞 修复了micro-app url属性为相对地址时没有自动补全导致子应用渲染失败的问题，[PR 1056](https://github.com/micro-zoe/micro-app/pull/1056)。 @@ -142,13 +147,11 @@ `2023-10-30` - **New** - - 🆕 新增了子应用全局变量`__MICRO_APP_STATE__`，用于标记当前应用的状态。 - 🆕 新增了子应用document变量`__MICRO_APP_NAME__`，用于标记document所属应用。 - 🆕 重写了原型方法`Node.prototype.parentNode`，用于处理特殊元素parentNode的指向问题。 - **Bug Fix** - - 🐞 修复了在iframe沙箱下循环嵌套的问题。 - 🐞 修复了在iframe沙箱下开启`inline`模式导致通过`getElementsByTagName`获取script元素失败的问题。 diff --git a/docs/zh-cn/configure.md b/docs/zh-cn/configure.md index f21ed7099..fb50e2e35 100644 --- a/docs/zh-cn/configure.md +++ b/docs/zh-cn/configure.md @@ -7,7 +7,7 @@ - 使用方式: `` - 注意事项: 必须以字母开头，且不可以带特殊符号(中划线、下划线除外) -每个`name`都对应一个应用，当多个应用同时渲染时，name不可以重复。 +每个`name`对应一个子应用，当多个应用同时渲染时，name不可以重复。 当`name`的值发生变化时，会卸载当前应用并重新渲染。 diff --git a/docs/zh-cn/sandbox.md b/docs/zh-cn/sandbox.md index 79809d800..6ccefc50b 100644 --- a/docs/zh-cn/sandbox.md +++ b/docs/zh-cn/sandbox.md @@ -163,10 +163,13 @@ window.stop虽然可以阻止脚本执行，但对于已经发送的js请求无 初始化时占用的内存是一次性的，不会一直增长。 -如果在切换子应用时内存一直增长，造成内存泄漏风险，需要进行以下操作： +如果在切换子应用时内存一直增长，造成内存泄漏风险，需要检查以下操作： - 1、将子应用切换到umd模式，切换方式参考[umd模式](/zh-cn/umd) -- 2、不要设置[destroy](/zh-cn/configure?id=destroy)属性 -- 3、保证name和url一一对应 +- 2、不要设置[destroy](/zh-cn/configure?id=destroy)属性，destroy只适合一次性渲染的子应用。 +- 3、不要频繁使用新的[name](/zh-cn/configure?id=name)，因为内存是基于name进行缓存的，新的name会重新初始化应用，导致内存不断增长。 + + 推荐的方式：一个子应用对应一个name，通过路由控制子应用渲染哪一个页面。 + 做到以上几点基本上不会有内存泄漏问题，如果问题依然存在，可以试着切换到[iframe](/zh-cn/configure?id=iframe)沙箱。 diff --git a/src/sandbox/iframe/document.ts b/src/sandbox/iframe/document.ts index 2e8682879..1d50b8774 100644 --- a/src/sandbox/iframe/document.ts +++ b/src/sandbox/iframe/document.ts @@ -137,7 +137,19 @@ function patchDocumentPrototype (appName: string, microAppWindow: microAppWindow return rawMicroQuerySelector.call(_this, selectors) } - return appInstanceMap.get(appName)?.querySelector(selectors) ?? rawMicroQuerySelector.call(microDocument, selectors) ?? null + /** + * The child app cannot query the base element inside iframe + * Same for querySelectorAll + * + * Scenes: + * 1. vue-router@4.x --> createWebHistory(base?: string) + * const baseEl = document.querySelector('base') + * base = (baseEl && baseEl.getAttribute('href')) || '/' + * + * Issue: https://github.com/micro-zoe/micro-app/issues/1335 + */ + const result = appInstanceMap.get(appName)?.querySelector(selectors) + return result || selectors === 'base' ? result : rawMicroQuerySelector.call(microDocument, selectors) } function querySelectorAll (this: Document, selectors: string): any { @@ -151,7 +163,7 @@ function patchDocumentPrototype (appName: string, microAppWindow: microAppWindow } const result = appInstanceMap.get(appName)?.querySelectorAll(selectors) ?? [] - return result.length ? result : rawMicroQuerySelectorAll.call(microDocument, selectors) + return result.length || selectors === 'base' ? result : rawMicroQuerySelectorAll.call(microDocument, selectors) } microRootDocument.prototype.querySelector = querySelector @@ -190,7 +202,8 @@ function patchDocumentPrototype (appName: string, microAppWindow: microAppWindow isInvalidQuerySelectorKey(key) ) { return rawMicroGetElementsByTagName.call(_this, key) - } else if (/^script|base$/i.test(key)) { + // just script, not base + } else if (/^script$/i.test(key)) { return rawMicroGetElementsByTagName.call(microDocument, key) } diff --git a/src/sandbox/iframe/index.ts b/src/sandbox/iframe/index.ts index e4f987a40..1e81338d5 100644 --- a/src/sandbox/iframe/index.ts +++ b/src/sandbox/iframe/index.ts @@ -423,7 +423,7 @@ export default class IframeSandbox { this.microHead.appendChild(this.baseElement) } - // 初始化和每次跳转时都要更新base的href + // Update the base.href when initial and each redirect public updateIframeBase = (): void => { // origin must be child app origin this.baseElement?.setAttribute('href', createURL(this.url).origin + this.proxyLocation.pathname) From 2e2b29c1879a74edc9eae54c8ebd723e8ca01807 Mon Sep 17 00:00:00 2001 From: tim66 Date: Tue, 20 Aug 2024 17:26:03 +0800 Subject: [PATCH 10/10] feat: release 1.0.0-rc.7 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 65ff663bc..a8889a2fb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@micro-zoe/micro-app", - "version": "1.0.0-rc.6", + "version": "1.0.0-rc.7", "description": "A lightweight, efficient and powerful micro front-end framework", "private": false, "main": "lib/index.min.js",