From 185e3cc1002e5d29af805d44985456a17a661dc2 Mon Sep 17 00:00:00 2001 From: System Administrator <747010491@qq.com> Date: Fri, 3 Nov 2023 19:24:29 +0800 Subject: [PATCH 1/2] [feat]Add react MicroApp component api documentation --- .dumirc.ts | 4 +- docs/api/README.md | 126 ++++++++++++++++++++++++++++ docs/api/README.zh-CN.md | 125 +++++++++++++++++++++++++++ docs/guide/getting-started.md | 25 ++++++ docs/guide/getting-started.zh-CN.md | 14 +++- docs/guide/tutorial.md | 21 +++++ docs/guide/tutorial.zh-CN.md | 20 +++++ 7 files changed, 332 insertions(+), 3 deletions(-) diff --git a/.dumirc.ts b/.dumirc.ts index ba6ef426b..73ac6f343 100644 --- a/.dumirc.ts +++ b/.dumirc.ts @@ -32,8 +32,8 @@ export default defineConfig({ title: 'Version Notice', children: [ { title: 'Changelog', link: 'https://github.com/umijs/qiankun/releases' }, - { title: 'Upgrade Guide', link: '/cookbook#upgrade-from-1x-version-to-2x-version' }, - { title: '1.x Version', link: 'https://v1.qiankun.umijs.org/' }, + { title: 'Upgrade Guide', link: '/cookbook#upgrade-from-2x-version-to-3x-version' }, + { title: '2.x Version', link: 'https://v2.qiankun.umijs.org/' }, ], }, ], diff --git a/docs/api/README.md b/docs/api/README.md index c2248750f..0faf751ab 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -351,6 +351,132 @@ A criterion for judging whether the business is closely related: Look at ]); ``` +## component load micro applications +### React project +#### Usage + +```bash +npm i @qiankunjs/react +``` + +#### MicroApp component + +Load (or unload) child apps directly through the `` component, which provides loading and error catching-related capabilities: + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + +When the sub-app loading animation or error capture capability is enabled, the sub-app accepts an additional style class `wrapperClassName`, and the rendered result is as follows: + +```tsx +
+ + + +
+``` + +#### Load animation + +When this capability is enabled, loading animations are automatically displayed when child apps are loading. When the sub-application is mounted and changes to the `MOUNTED` state, the loading status ends and the sub-application content is displayed. + +Just pass `autoSetLoading` as a parameter: + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + +#### Custom loading animation + +If you want to override the default loading animation style, you can set a custom loading component `loader` as the loading animation for the child app. + +```tsx +import CustomLoader from '@/components/CustomLoader'; +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ( + } /> + ); +} +``` + +where `loading` is the `boolean` type parameter, `true` indicates that the loading state is still being loaded, and `false` indicates that the loading state has ended. + +#### Error catching + +When this capability is enabled, an error message is automatically displayed when a child app loads unexpectedly. You can pass the `autoCaptureError` property to the sub-app to enable sub-app error capture capabilities: + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + +#### Custom error capture + +If you want to override the default error capture component style, you can set a custom component `errorBoundary` as the error capture component for the child app: + +```tsx +import CustomErrorBoundary from '@/components/CustomErrorBoundary'; +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ( + } + /> + ); +} +``` + +#### Component Props + +| Name | Required | Description | Type | Default | +| --- | --- | --- | --- | --- | +| `name` | yes | The name of the microapp | `string` | +| `entry` | yes | The HTML address of the microapp | `string` | +| `autoSetLoading` | no | Automatically set the loading state of your microapp | `boolean` | `false` | +| `loader` | no | Custom microapps load state components | `(loading) => React.ReactNode` | `undefined` | +| `autoCaptureError` | no | Automatically set up error capture for microapps | `boolean` | `false` | +| `errorBoundary` | no | Custom microapp error capture component | `(error: any) => React.ReactNode` | `undefined` | +| `className` | no | The style class for the microapp | `string` | `undefined` | +| `wrapperClassName` | no | Wrap the microapp loading component, error capture component, and microapp's style classes, and are only valid when the load component or error capture component is enabled | `string` | `undefined` | + +#### Get the child app load status + +The loading status includes: "NOT_LOADED" | "LOADING_SOURCE_CODE" | "NOT_BOOTSTRAPPED" | "BOOTSTRAPPING" | "NOT_MOUNTED" | "MOUNTING" | "MOUNTED" | "UPDATING" | "UNMOUNTING" | "UNLOADING" | + +```tsx +import { useRef } from 'react'; +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + const microAppRef = useRef(); + + useEffect(() => { + // Get the child app load status + console.log(microAppRef.current?.getStatus()); + }, []); + + return ; +} +``` + + ## [addErrorHandler/removeErrorHandler](https://single-spa.js.org/docs/api#adderrorhandler) ## `addGlobalUncaughtErrorHandler(handler)` diff --git a/docs/api/README.zh-CN.md b/docs/api/README.zh-CN.md index f77c34013..dd274b0bb 100644 --- a/docs/api/README.zh-CN.md +++ b/docs/api/README.zh-CN.md @@ -359,6 +359,131 @@ toc: menu ]); ``` +## 组件加载微应用 +### React 项目 +#### 安装 + +```bash +npm i @qiankunjs/react +``` + +#### MicroApp 组件 + +直接通过 `` 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力： + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + +当启用子应用加载动画或错误捕获能力时，子应用接受一个额外的样式类 `wrapperClassName`，渲染的结果如下所示： + +```tsx +
+ + + +
+``` + +#### 加载动画 + +启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 `MOUNTED` 状态时，加载状态结束，显示子应用内容。 + +直接将 `autoSetLoading` 作为参数传入即可： + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + +#### 自定义加载动画 + +如果您希望覆盖默认的加载动画样式时，可以设置一个自定义的加载组件 `loader` 作为子应用的加载动画。 + +```tsx +import CustomLoader from '@/components/CustomLoader'; +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ( + } /> + ); +} +``` + +其中，`loading` 为 `boolean` 类型参数，为 `true` 时表示仍在加载状态，为 `false` 时表示加载状态已结束。 + +#### 错误捕获 + +启用此能力后，当子应用加载出现异常时，会自动显示错误信息。可以向子应用传入 `autoCaptureError` 属性以开启子应用错误捕获能力： + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + +#### 自定义错误捕获 + +如果您希望覆盖默认的错误捕获组件样式时，可以设置一个自定义的组件 `errorBoundary` 作为子应用的错误捕获组件： + +```tsx +import CustomErrorBoundary from '@/components/CustomErrorBoundary'; +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ( + } + /> + ); +} +``` + +#### 组件属性 + +| 属性 | 必填 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | --- | +| `name` | 是 | 微应用的名称 | `string` | +| `entry` | 是 | 微应用的 HTML 地址 | `string` | +| `autoSetLoading` | 否 | 自动设置微应用的加载状态 | `boolean` | `false` | +| `loader` | 否 | 自定义的微应用加载状态组件 | `(loading) => React.ReactNode` | `undefined` | +| `autoCaptureError` | 否 | 自动设置微应用的错误捕获 | `boolean` | `false` | +| `errorBoundary` | 否 | 自定义的微应用错误捕获组件 | `(error: any) => React.ReactNode` | `undefined` | +| `className` | 否 | 微应用的样式类 | `string` | `undefined` | +| `wrapperClassName` | 否 | 包裹微应用加载组件、错误捕获组件和微应用的样式类，仅在启用加载组件或错误捕获组件时有效 | `string` | `undefined` | + +#### 获取子应用加载状态 + +加载状态包括："NOT_LOADED" | "LOADING_SOURCE_CODE" | "NOT_BOOTSTRAPPED" | "BOOTSTRAPPING" | "NOT_MOUNTED" | "MOUNTING" | "MOUNTED" | "UPDATING" | "UNMOUNTING" | "UNLOADING" | + +```tsx +import { useRef } from 'react'; +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + const microAppRef = useRef(); + + useEffect(() => { + // 获取子应用加载状态 + console.log(microAppRef.current?.getStatus()); + }, []); + + return ; +} +``` + ## [addErrorHandler/removeErrorHandler](https://single-spa.js.org/docs/api#adderrorhandler) ## `addGlobalUncaughtErrorHandler(handler)` diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index c2991b706..e11178fa4 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -37,6 +37,31 @@ start(); After the sub-application information is registered, the matching logic of the qiankun will be automatically triggered once the browser url changes, and all the render methods corresponding to the subapplications whose activeRule methods returns `true` will be called, at the same time the subapplications' exposed lifecycle hooks will be called in turn. +If the microapplication is not directly associated with the route, you can also choose to load the microapplication manually or as a component: + +Load microapplications manually +```ts +import { loadMicroApp } from 'qiankun'; + +loadMicroApp({ + name: 'app', + entry: '//localhost:7100', + container: '#yourContainer', +}); +``` + +Component to load microapplications +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + + + + ## Sub Application Sub applications do not need to install any additional dependencies to integrate to qiankun master application. diff --git a/docs/guide/getting-started.zh-CN.md b/docs/guide/getting-started.zh-CN.md index f3dfb8961..05dff76a1 100644 --- a/docs/guide/getting-started.zh-CN.md +++ b/docs/guide/getting-started.zh-CN.md @@ -37,8 +37,9 @@ start(); 当微应用信息注册完之后，一旦浏览器的 url 发生变化，便会自动触发 qiankun 的匹配逻辑，所有 activeRule 规则匹配上的微应用就会被插入到指定的 container 中，同时依次调用微应用暴露出的生命周期钩子。 -如果微应用不是直接跟路由关联的时候，你也可以选择手动加载微应用的方式： +如果微应用不是直接跟路由关联的时候，你也可以选择手动的方式或者组件的形式加载微应用： +手动的方式加载微应用 ```ts import { loadMicroApp } from 'qiankun'; @@ -49,6 +50,17 @@ loadMicroApp({ }); ``` +组件的形式加载微应用 +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + + + ## 微应用 微应用不需要额外安装任何其他依赖即可接入 qiankun 主应用。 diff --git a/docs/guide/tutorial.md b/docs/guide/tutorial.md index 8885d7fcb..51ac988d1 100644 --- a/docs/guide/tutorial.md +++ b/docs/guide/tutorial.md @@ -165,6 +165,27 @@ It's important, When mount a sub-application through ReactDOM.render, need to en - "eject": "react-scripts eject" ``` +### React MicroApp component +1. Usage + +```bash +npm i @qiankunjs/react +``` + +2. use microApp component + +Load (or unload) child apps directly through the `` component, which provides loading and error catching-related capabilities: + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + + + ### Vue micro app Take the `vue 2.x` project generated by `vue-cli 3+` as an example, and add it after the `vue 3` version becomes stable. diff --git a/docs/guide/tutorial.zh-CN.md b/docs/guide/tutorial.zh-CN.md index f480d6eac..7f78ea2f1 100644 --- a/docs/guide/tutorial.zh-CN.md +++ b/docs/guide/tutorial.zh-CN.md @@ -165,6 +165,26 @@ start(); - "eject": "react-scripts eject" ``` +### react 微应用组件 +1. 安装 + +```bash +npm i @qiankunjs/react +``` + +2. 使用 MicroApp 组件 + +直接通过 `` 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力： + +```tsx +import { MicroApp } from '@qiankunjs/react'; + +export default function Page() { + return ; +} +``` + + ### Vue 微应用 以 `vue-cli 3+` 生成的 `vue 2.x` 项目为例，`vue 3` 版本等稳定后再补充。 From 6bfd2630b178cbc82958828c316b548eb079c02c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=86=9B?= <747010491@qq.com> Date: Mon, 6 Nov 2023 10:48:50 +0800 Subject: [PATCH 2/2] [fix]add dependence --- docs/guide/tutorial.md | 5 +++-- docs/guide/tutorial.zh-CN.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/guide/tutorial.md b/docs/guide/tutorial.md index 51ac988d1..2b9c6f775 100644 --- a/docs/guide/tutorial.md +++ b/docs/guide/tutorial.md @@ -166,13 +166,14 @@ It's important, When mount a sub-application through ReactDOM.render, need to en ``` ### React MicroApp component -1. Usage +1. Install ```bash +npm i qiankun npm i @qiankunjs/react ``` -2. use microApp component +2. Usage Load (or unload) child apps directly through the `` component, which provides loading and error catching-related capabilities: diff --git a/docs/guide/tutorial.zh-CN.md b/docs/guide/tutorial.zh-CN.md index 7f78ea2f1..b3eee2405 100644 --- a/docs/guide/tutorial.zh-CN.md +++ b/docs/guide/tutorial.zh-CN.md @@ -169,10 +169,11 @@ start(); 1. 安装 ```bash +npm i qiankun npm i @qiankunjs/react ``` -2. 使用 MicroApp 组件 +2. 使用 直接通过 `` 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力：