[feat]add react MicroApp component api documentation

.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/' },
             ],
           },
         ],

docs/api/README.md

@@ -351,6 +351,132 @@ A criterion for judging whether the business is closely related: <strong>Look at
   ]);
   ```
 
+## component load micro applications
+### React project
+#### Usage
+
+```bash
+npm i @qiankunjs/react
+```
+
+#### MicroApp component
+
+Load (or unload) child apps directly through the `<MicroApp/>` component, which provides loading and error catching-related capabilities:
+
+```tsx
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return <MicroApp name="app1" entry="http://localhost:8000" />;
+}
+```
+
+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
+<div style={{ position: 'relative' }} className={wrapperClassName}>
+  <MicroAppLoader loading={loading} />
+  <ErrorBoundary error={e} />
+  <MicroApp className={className} />
+</div>
+```
+
+#### 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 <MicroApp name="app1" entry="http://localhost:8000" autoSetLoading />;
+}
+```
+
+#### 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 (
+    <MicroApp name="app1" entry="http://localhost:8000" loader={(loading) => <CustomLoader loading={loading} />} />
+  );
+}
+```
+
+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 <MicroApp name="app1" entry="http://localhost:8000" autoCaptureError />;
+}
+```
+
+#### 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 (
+    <MicroApp
+      name="app1"
+      entry="http://localhost:8000"
+      errorBoundary={(error) => <CustomErrorBoundary error={error} />}
+    />
+  );
+}
+```
+
+#### 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 <MicroApp name="app1" entry="http://localhost:8000" ref={microAppRef} />;
+}
+```
+
+
 ## [addErrorHandler/removeErrorHandler](https://single-spa.js.org/docs/api#adderrorhandler)
 
 ## `addGlobalUncaughtErrorHandler(handler)`

docs/api/README.zh-CN.md

@@ -359,6 +359,131 @@ toc: menu
   ]);
   ```
 
+## 组件加载微应用
+### React 项目
+#### 安装
+
+```bash
+npm i @qiankunjs/react
+```
+
+#### MicroApp 组件
+
+直接通过 `<MicroApp />` 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力：
+
+```tsx
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return <MicroApp name="app1" entry="http://localhost:8000" />;
+}
+```
+
+当启用子应用加载动画或错误捕获能力时，子应用接受一个额外的样式类 `wrapperClassName`，渲染的结果如下所示：
+
+```tsx
+<div style={{ position: 'relative' }} className={wrapperClassName}>
+  <MicroAppLoader loading={loading} />
+  <ErrorBoundary error={e} />
+  <MicroApp className={className} />
+</div>
+```
+
+#### 加载动画
+
+启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 `MOUNTED` 状态时，加载状态结束，显示子应用内容。
+
+直接将 `autoSetLoading` 作为参数传入即可：
+
+```tsx
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return <MicroApp name="app1" entry="http://localhost:8000" autoSetLoading />;
+}
+```
+
+#### 自定义加载动画
+
+如果您希望覆盖默认的加载动画样式时，可以设置一个自定义的加载组件 `loader` 作为子应用的加载动画。
+
+```tsx
+import CustomLoader from '@/components/CustomLoader';
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return (
+    <MicroApp name="app1" entry="http://localhost:8000" loader={(loading) => <CustomLoader loading={loading} />} />
+  );
+}
+```
+
+其中，`loading` 为 `boolean` 类型参数，为 `true` 时表示仍在加载状态，为 `false` 时表示加载状态已结束。
+
+#### 错误捕获
+
+启用此能力后，当子应用加载出现异常时，会自动显示错误信息。可以向子应用传入 `autoCaptureError` 属性以开启子应用错误捕获能力：
+
+```tsx
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return <MicroApp name="app1" entry="http://localhost:8000" autoCaptureError />;
+}
+```
+
+#### 自定义错误捕获
+
+如果您希望覆盖默认的错误捕获组件样式时，可以设置一个自定义的组件 `errorBoundary` 作为子应用的错误捕获组件：
+
+```tsx
+import CustomErrorBoundary from '@/components/CustomErrorBoundary';
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return (
+    <MicroApp
+      name="app1"
+      entry="http://localhost:8000"
+      errorBoundary={(error) => <CustomErrorBoundary error={error} />}
+    />
+  );
+}
+```
+
+#### 组件属性
+
+| 属性 | 必填 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- | --- |
+| `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 <MicroApp name="app1" entry="http://localhost:8000" ref={microAppRef} />;
+}
+```
+
 ## [addErrorHandler/removeErrorHandler](https://single-spa.js.org/docs/api#adderrorhandler)
 
 ## `addGlobalUncaughtErrorHandler(handler)`

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 <MicroApp name="app1" entry="http://localhost:8000" />;
+}
+```
+
+
+
+
 ## Sub Application
 
 Sub applications do not need to install any additional dependencies to integrate to qiankun master application.

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 <MicroApp name="app1" entry="http://localhost:8000" />;
+}
+```
+
+
+
 ## 微应用
 
 微应用不需要额外安装任何其他依赖即可接入 qiankun 主应用。

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 `<MicroApp/>` component, which provides loading and error catching-related capabilities:
+
+```tsx
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return <MicroApp name="app1" entry="http://localhost:8000" />;
+}
+```
+
+
+
 ### 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.

docs/guide/tutorial.zh-CN.md

@@ -165,6 +165,26 @@ start();
    -   "eject": "react-scripts eject"
    ```
 
+### react 微应用组件
+1. 安装
+
+```bash
+npm i @qiankunjs/react
+```
+
+2. 使用 MicroApp 组件
+
+直接通过 `<MicroApp />` 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力：
+
+```tsx
+import { MicroApp } from '@qiankunjs/react';
+
+export default function Page() {
+  return <MicroApp name="app1" entry="http://localhost:8000" />;
+}
+```
+
+
 ### Vue 微应用
 
 以 `vue-cli 3+` 生成的 `vue 2.x` 项目为例，`vue 3` 版本等稳定后再补充。