docs(qiankun): 更新 qiankun 插件文档

docs/plugins/plugin-qiankun.md

@@ -1,23 +1,34 @@
----
-translateHelp: true
----
-
 # @umijs/plugin-qiankun
 
+Umi@3 plugin for [qiankun](https://github.com/umijs/qiankun).
+
+[![NPM version](https://img.shields.io/npm/v/@umijs/plugin-qiankun.svg?style=flat)](https://npmjs.org/package/@umijs/plugin-qiankun) [![Build Status](https://img.shields.io/travis/umijs/umi-plugin-qiankun.svg?style=flat)](https://travis-ci.org/umijs/umi-plugin-qiankun) [![NPM downloads](http://img.shields.io/npm/dm/@umijs/plugin-qiankun.svg?style=flat)](https://npmjs.org/package/@umijs/plugin-qiankun)
+
+## 启用方式
+
+配置 `qiankun` 开启。
 
-Umi plugin for [qiankun](https://github.com/umijs/qiankun).
+## 介绍
+
+Umi 应用一键开启 [qiankun](https://github.com/umijs/qiankun) 微前端模式。 
 
 ## Examples
 
-导航是主应用，App1 和 App2 是子应用，
+导航是主应用，App1/App2 是子应用，App1/App2 也支持单独打开。
 
 ![](https://img.alicdn.com/tfs/TB1ZMxEwKH2gK0jSZJnXXaT1FXa-1040-619.gif)
 
+```bash
+$ yarn
+$ yarn build
+$ cd packages/plguin-qiankun && yarn start
+```
+
 ## Features
 
 - ✔︎ 基于 qiankun
 - ✔︎ 支持主应用和子应用都用 umi
-- ✔︎ 支持主子应用 browser、hash 等多种 history 模式
+- ✔︎ 支持通过 `<MicroApp />` 组件引入子应用
 - ✔︎ 父子应用通讯
 - ✔︎ 子应用运行时配置自定义 `bootstrap()`、`mount()` 和 `unmount()`
 - ✔︎ 主应用、子应用联调
@@ -26,7 +37,11 @@ Umi plugin for [qiankun](https://github.com/umijs/qiankun).
 
 ### 主应用
 
-#### 构建期
+#### 第一步：注册子应用
+
+子应用注册有两种方式，**二选一即可**
+
+##### 在构建期配置子应用
 
 ```js
 export default {
@@ -37,104 +52,143 @@ export default {
         {
           name: 'app1', // 唯一 id
           entry: '//localhost:7001', // html entry
-          base: '/app1', // app1 的路由前缀，通过这个前缀判断是否要启动该应用，通常跟子应用的 base 保持一致
-          history: 'browser', // 子应用的 history 配置，默认为当前主应用 history 配置
         },
         {
-          name: 'app2',
-          entry: {
-            // TODO 支持 config entry
-            scripts: [],
-            styles: [],
-          },
-          base: '/app2',
+          name: 'app2', // 唯一 id
+          entry: '//localhost:7002', // html entry
         },
       ],
-      jsSandbox: true, // 是否启用 js 沙箱，默认为 false
+      jsSandbox: true, // 是否启用 js 沙箱，默认为 true
       prefetch: true, // 是否启用 prefetch 特性，默认为 true
     },
   },
 };
 ```
 
-Note: 当主应用跟子应用的 history 模式一致时（比如都是 browser 或 hash），插件会自动创建一些空路由来避免 404，所以建议主应用跟子应用使用相同的 history mode，否则需要自己处理这些情况。
-
-#### 运行时
-
-##### 1. src/app.js 里配置
+##### 在运行时动态配置子应用（src/app.js 里开启）
 
 ```js
 // 从接口中获取子应用配置，export 出的 qiankun 变量是一个 promise
-export const qiankun = fetch('/config').then(({ apps }) => ({
+export const qiankun = fetch('/config').then(({ apps }}) => ({
   // 注册子应用信息
   apps,
-  jsSandbox: true, // 是否启用 js 沙箱，默认为 false
+  jsSandbox: true, // 是否启用 js 沙箱，默认为 true
   prefetch: true, // 是否启用 prefetch 特性，默认为 true
   lifeCycles: {
-    // see https://github.com/umijs/qiankun#registermicroapps
+    // 完整生命周期钩子请看 https://qiankun.umijs.org/zh/api/#registermicroapps-apps-lifecycles
     afterMount: props => {
       console.log(props);
     },
   },
-  // ...even more options qiankun start() supported, see https://github.com/umijs/qiankun#start
+  // 支持更多的其他配置，详细看这里 https://qiankun.umijs.org/zh/api/#start-opts
 }));
 ```
 
-##### 2. 添加子应用路由
+完整的主应用配置项看这里 [masterOptions 配置列表](#masterOptions)
 
-由于 umi 不支持在应用 render 之后修改路由，故运行时配置方式插件无法自动生成子应用相关路由，（见[代码](https://github.com/umijs/umi-plugin-qiankun/blob/master/src/master/index.ts#L34)）。所以这里需要用户手动添加子应用相关路由配置避免 404 情况：
+#### 第二步：装载子应用
 
-###### 2.1 主应用新建 pages/subAppContainer.js
+子应用的装载有两种方式，**二选一即可：**
 
-```js
-import React from 'react';
+##### 使用路由绑定的方式
+
+假设我们的系统之前有这样的一些路由：
 
-export default function() {
-  return <div />;
+```js
+export default {
+	routes: [
+    {
+      path: '/',
+      component: '../layouts/index.js',
+      routes: [
+        {
+          path: '/app1',
+          component: './app1/index.js',
+          routes: [
+            {
+              path: '/app1/user',
+	          	component: './app1/user/index.js',
+            },
+          ],
+        },
+        {
+          path: '/',
+          component: './index.js',
+        },
+      ],
+    },
+  ],
 }
 ```
 
-###### 2.2 新建 pages/subAppContainer.js
+我们现在想在 `/app1/project` 和 `/app2` 这两个路径时分别加载微应用 app1 和 app2，只需要增加这样一些配置即可：
 
-```js
-// 主应用 config.js 中添加子应用相关路由配置
+```diff
 export default {
-  routes: [
-    { path: '/app1', exact: true, component: 'subAppContainer' },
-    { path: '/app2', exact: true, component: 'subAppContainer' },
+	routes: [
+    {
+      path: '/',
+      component: '../layouts/index.js',
+      routes: [
+        {
+          path: '/app1',
+          component: './app1/index.js',
+          routes: [
+            {
+              path: '/app1/user',
+	          	component: './app1/user/index.js',
+            },
++            // 配置微应用 app1 关联的路由
++            {
++              path: '/app1/project',
++	          	 microApp: 'app1',
++            },
+          ],
+        },
++        // 配置 app2 关联的路由
++        {
++        	path: '/app2',
++        	microApp: 'app2'
++        },
+        {
+          path: '/',
+          component: './index.js',
+        },
+      ],
+    },
   ],
-};
+}
 ```
 
-### 配置列表
-
-| 配置 | 说明 | 类型 | 是否必填 | 默认值 |
-| --- | --- | --- | --- | --- |
-| apps | 子应用配置 | App[] | 是 |  |
-| jsSandbox | 是否启用 js 沙箱 | boolean | 否 | false |
-| prefetch | 是否启用 prefetch 特性 | boolean | 否 | true |
-| defer | 是否异步渲染，比如子应用的渲染容器依赖主应用生成的节点，而主应用生成该节点的过程是异步的。<br />当该配置开启的时候，需要使用 `import { qiankunStart } from 'umi'` api 通知 qiankun 启动。参考 [example](https://github.com/umijs/umi-plugin-qiankun/blob/master/examples/master/models/base.js#L35) | boolean | 否 | false |
+##### 使用 `<MicroApp />` 组件的方式
 
-[qiankun start](https://github.com/umijs/qiankun#start) 方法其他可接收的参数在这里也都可以配置
+我们可以直接使用 React 标签的方式加载我们已注册过的子应用：
 
-#### App
+```diff
+import { MicroApp } from 'umi';
 
-| 配置 | 说明 | 类型 | 是否必填 | 默认值 |
-| --- | --- | --- | --- | --- |
-| name | 子应用唯一 id | string | 是 |  |
-| entry | 子应用 html 地址 | string \| { script: string[], styles: [] } | 是 |  |
-| base | 子应用路由前缀，通常跟子应用的 [base 配置](https://umijs.org/config/#base) 一致，框架会以这个配置作为前缀判断是否激活当前应用，支持配置一组前缀 | string \| string[] | 是 |  |
-| history | [umi history mode](https://umijs.org/config/#history) | string | 否 | 主应用 history 配置 |
-| mountElementId | 子应用挂载到主应用的哪个 id 节点上（注意不要跟子应用的 mountElementId 一致） | string | 否 | root-subapp |
-| props | 主应用传递给子应用的数据 | object | 否 | {} |
+export function MyPage() {
+
+  return (
+    <div>
+      <div>
++        <MicroApp name="app1" />
+      </div>
+    </div>
+  )
+}
+```
 
 ### 子应用
 
+#### 第一步：插件注册（config.js）
+
 ```js
 export default {
-  base: `/${appName}`, // 子应用的 base，默认为 package.json 中的 name 字段
-  plugins: ['@umijs/plugin-qiankun', { slave: {} }],
-};
+  qiankun: {
+    slave: {}
+  }
+}
 ```
 
 如果子应用配置项为空，即 slave: {}，则可以省略配置：
@@ -146,6 +200,27 @@ export default {
 };
 ```
 
+#### 第二步：配置运行时生命周期钩子（可选）
+
+在子应用的 `src/app.js` 里输出 `qiankun`，`props` 由主应用注入。
+
+```js
+export const qiankun = {
+  // 应用加载之前
+  async bootstrap(props) {
+    console.log('app1 bootstrap', props);
+  },
+  // 应用 render 之前触发
+  async mount(props) {
+    console.log('app1 mount', props);
+  },
+  // 应用卸载之后触发
+  async unmount(props) {
+    console.log('app1 unmount', props);
+  },
+};
+```
+
 #### 环境变量配置
 
 为了获得更好地本地开发及调试体验，我们建议您提前在子应用中指定应用启动的具体端口号，如通过`.env`指定
@@ -195,28 +270,23 @@ PORT=8081
 1. 约定父应用中在 `src/rootExports.js` 里 export 内容
 2. 子应用中通过 `import { useRootExports } from 'umi'; const rootExports = useRootExports();` 取到
 
-## 子应用运行时配置
+### <a name="masterOptions">MasterOptions</a>
 
-在子应用的 `src/app.js` 里输出 `qiankun`，`props` 由主应用注册子应用时提供
+| 配置 | 说明 | 类型 | 是否必填 | 默认值 |
+| --- | --- | --- | --- | --- |
+| apps | 子应用配置 | App[] | 是 |  |
+| jsSandbox | 是否启用 js 沙箱 | boolean | 否 | false |
+| prefetch | 是否启用 prefetch 特性 | boolean | 否 | true |
 
-```js
-export const qiankun = {
-  // 应用加载之前
-  async bootstrap(props) {
-    console.log('app1 bootstrap', props);
-  },
-  // 应用 render 之前触发
-  async mount(props) {
-    console.log('app1 mount', props);
-  },
-  // 应用卸载之后触发
-  async unmount(props) {
-    console.log('app1 unmount', props);
-  },
-};
-```
+#### App
+
+| 配置 | 说明 | 类型 | 是否必填 | 默认值 |
+| --- | --- | --- | --- | --- |
+| name | 子应用唯一 id | string | 是 |  |
+| entry | 子应用 html 地址 | string \| { script: string[], styles: [] } | 是 |  |
+| props | 主应用传递给子应用的数据 | object | 否 | {} |
 
 ## 相关
 
-- [RFC: 微前端（@umijs/plugin-qiankun） by sorrycc · Pull Request #3 · umijs/rfcs · GitHub](https://github.com/umijs/rfcs/pull/3)
-- [umi-example-monorepo](https://github.com/umijs/umi-example-monorepo) 之前尝试的另一种简单粗糙的微前端试验
+- [https://github.com/umijs/plugins/issues/64](https://github.com/umijs/plugins/issues/64)
+