From 91d45a2b7d8ff29acb4721822120ae58ff9ff1d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A4=A7=E6=9E=9C?= <sobear.me@gmail.com>
Date: Thu, 5 Mar 2020 13:22:18 +0800
Subject: [PATCH] docs: adjust router docs (#3102)

* docs: adjust router docs

* docs: format docs

* chore: fix typo

* docs: why migrate to icejs

* docs: fix typo

* docs: adjust the API order
---
 docs/cli/config/config-file.md |   2 +-
 docs/guide/basic/app.md        |  29 +++--
 docs/guide/basic/router.md     | 192 ++++++++++++++++++++++-----------
 docs/guide/migrate.md          |   9 ++
 4 files changed, 155 insertions(+), 77 deletions(-)

diff --git a/docs/cli/config/config-file.md b/docs/cli/config/config-file.md
index e222a29687..05236e1b40 100644
--- a/docs/cli/config/config-file.md
+++ b/docs/cli/config/config-file.md
@@ -22,7 +22,7 @@ module.exports = {
 
   // 2. 插件配置
   plugins: [
-    ['ice-plugins-fusion', { themePackage: '@icedesign/theme' }],
+    ['ice-plugin-fusion', { themePackage: '@icedesign/theme' }],
   ],
 
   // 3. 自定义 webpack 配置
diff --git a/docs/guide/basic/app.md b/docs/guide/basic/app.md
index 77ed9ba1de..5237bdb171 100644
--- a/docs/guide/basic/app.md
+++ b/docs/guide/basic/app.md
@@ -12,21 +12,23 @@ order: 2
 ```ts
 import { createApp } from 'ice';
 
-// 用于配置
+// 应用配置
 const appConfig = {
   // 启动项配置
-  app: {
-    rootId: 'ice-container'
-  },
+  app: { },
+
+  // 状态管理配置
+  store: { },
+
   // 路由配置
-  router: {
-  },
+  router: { },
+
   // 请求配置
-  request: {
-  },
+  request: { },
+
   // 日志配置
-  logger: {
-  }
+  logger: { }
+
   // ...其他更多配置
 };
 
@@ -42,8 +44,13 @@ import { createApp } from 'ice';
 
 const appConfig = {
   app: {
+    // 可选，根节点 id，默认为 ice-container
     rootId: 'ice-container',
+
+    // 可选，根节点 DOM 元素
     mountNode: document.getElementById('#ice-container'),
+
+    // 可选，自定义添加 Provider
     addProvider: (children) => {
       return <ConfigProvider>{children}</ConfigProvider>;
     }
@@ -51,4 +58,4 @@ const appConfig = {
 };
 
 createApp(appConfig);
-```
\ No newline at end of file
+```
diff --git a/docs/guide/basic/router.md b/docs/guide/basic/router.md
index 3fc7242be4..e2502d06b4 100644
--- a/docs/guide/basic/router.md
+++ b/docs/guide/basic/router.md
@@ -192,13 +192,14 @@ export default [
 
 在 `src/app.ts` 中，我们可以配置路由的类型和基础路径等路由信息，具体配置如下：
 
-```js
-import { createApp } from 'ice'
+```jsx
+import { createApp } from 'ice';
 
 const appConfig = {
   router: {
     type: 'browser',
     basename: '/seller',
+    fallback: <div>loading...</div>
     modifyRoutes: (routes) => {
       return routes;
     }
@@ -212,6 +213,7 @@ createApp(appConfig);
 
 - type: 路由类型，默认值 `hash`，可选值 `browser|hash|static`
 - basename: 路由基准地址
+- fallback: 开启按需加载时配置 fallback UI
 - modifyRoutes: 动态修改路由
 
 ### 构建配置
@@ -233,9 +235,73 @@ createApp(appConfig);
 - **ignoreRoutes**: 仅约定式路由，类型 `string[]`，默认值 `[]`，忽略指定路由的生成
 - **ignorePaths**: 仅约定式路由，类型 `string[]`，默认值 `['components']`，生成路由时忽略指定目录
 
-## 路由跳转
+## 按需加载
+
+### 配置式路由
+
+在配置式路由中如果需要开启按需加载，只需要在路由文件中通过 `import()` 语法引入组件即可： 
+
+```diff
+// src/routes.ts
+- import UserLogin from '@/pages/UserLogin';
++ const UserLogin = import('@/pages/UserLogin');
 
-### 通过 Link 组件跳转
+const routerConfig = [
+  {
+    path: '/login',
+    component: UserLogin,
+  },
+]
+```
+
+### 约定式路由
+
+在约定式路由中如果需要开启按需加载，只需要在 `build.json` 中的 router 选项配置 lazy 属性即可：
+
+```diff
+// build.json
+{
+  "router": {
++    "lazy": true
+  }
+}
+```
+
+### fallback
+
+当组件动态加载过程中或者组件渲染失败时，可以通过 fallback 属性设置提示：
+
+```diff
+import { createApp } from 'ice';
+
+const appConfig = {
+  router: {
++    fallback: <div>loading...</div>
+  }
+}
+
+createApp(appConfig);
+```
+
+## 路由 API
+
+icejs 的路由能力基于 react-router，因此你也可以获取到 react-router 支持的其他路由 API：
+
+```js
+import {
+  Link,
+  useHistory,
+  useLocation,
+  useParams,
+  useRouteMatch,
+  withRouter,
+  matchPath,
+  NavLink,
+  Prompt,
+} from 'ice';
+```
+
+### Link
 
 通过 `<Link />` 标签组件可实现路由跳转，使用方式：
 
@@ -245,7 +311,7 @@ import { Link } from 'ice';
 function Demo() {
   return (
     <div>
-      <Link to="/courses?sort=name" />
+      <Link to='/courses?sort=name' />
 
       {/* 可以携带额外的数据 `state` 到路由中。 */}
       <Link
@@ -261,9 +327,46 @@ function Demo() {
 }
 ```
 
-### 通过 withRouter 方法调用实现跳转
+### useHistory
+
+useHistory hook 用于获取导航的 history 实例。
 
-如果调用方法的地方在 React 组件内部，可以直接在组件上添加 `withRouter` 的装饰器，然后组件内可以通过 `props` 获取到相关 API：
+
+```js
+mport { useHistory } from 'ice';
+
+function HomeButton() {
+  const history = useHistory();
+
+  function handleClick() {
+    history.push('/home);
+  }
+
+  return (
+    <button type='button' onClick={handleClick}>
+      Go home
+    </button>
+  );
+}
+```
+
+### useLocation
+
+useLocation hook 返回代表当前 URL 的 location 对象。可以像 useState 一样使用它，只要 URL 更改，它就会返回一个新位置。
+
+### useParams
+
+useParams hook 返回 URL 参数的 key/value 的对象。 使用它来访问当前 <Route> 的 match.params。
+
+### useRouteMatch
+
+useRouteMatch hook 尝试以与 <Route> 相同的方式匹配当前URL。它主要用于在不实际渲染 <Route> 的情况下访问匹配数据。
+
+[更多使用示例](https://reacttraining.com/react-router/web/example/basic)
+
+### withRouter
+
+通过 withRouter 方法调用实现跳转；如果调用方法的地方在 React 组件内部，可以直接在组件上添加 `withRouter` 的装饰器，然后组件内可以通过 `props` 获取到相关 API：
 
 ```javascript
 import React from 'react';
@@ -286,74 +389,33 @@ function ShowTheLocation(props) {
 export default withRouter(ShowTheLocation);
 ```
 
-## 路由 API
+### matchPath
 
-icejs 的路由能力基于 react-router，因此你也可以获取到 react-router 支持的其他路由 API：
+判断当前 URL 是否匹配。
 
 ```js
-import {
-  Link,
-  NavLink,
-  Prompt,
-
-  withRouter,
-  matchPath,
-  generatePath,
-
-  useHistory,
-  useLocation,
-  useParams,
-  useRouteMatch
-} from 'ice';
-```
-
-## 按需加载
-
-### 配置式路由
+import { matchPath } from 'ice';
 
-在配置式路由中如果需要开启按需加载，只需要在路由文件中通过 `import()` 语法引入组件即可： 
-
-```diff
-// src/routes.ts
-- import UserLogin from '@/pages/UserLogin';
-+ const UserLogin = import('@/pages/UserLogin');
-
-const routerConfig = [
-  {
-    path: '/login',
-    component: UserLogin,
-  },
-]
+const match = matchPath('/users/123', {
+  path: '/users/:id',
+  exact: true,
+  strict: false
+});
 ```
 
-### 约定式路由
+### NavLink
 
-在约定式路由中如果需要开启按需加载，只需要在 `build.json` 中的 router 选项配置 lazy 属性即可：
+NavLink 组件的用法和 Link 组件基本相同，区别在于 NavLink 组件匹配时可以添加 active 属性。
 
-```diff
-// build.json
-{
-  "router": {
-+    "lazy": true
-  }
-}
+```jsx
+<NavLink to='/faq' activeClassName='selected'>
+  FAQs
+</NavLink>
 ```
 
-### fallback
-
-当组件动态加载过程中或者组件渲染失败时，可以通过 fallback 属性设置提示：
+### Prompt
 
-```diff
-import { createApp } from 'ice'
-
-const appConfig = {
-  router: {
-+    fallback: <div>loading...</div>
-  }
-}
-
-createApp(appConfig)
-```
+在离开页面路由跳转时，自定义拦截组件。
 
 ## 常见问题
 
@@ -376,7 +438,7 @@ createApp(appConfig)
 本地开发时，只需要在 `src/app.ts` 中增加以下配置即可：
 
 ```diff
-import { createApp } from 'ice'
+import { createApp } from 'ice';
 
 const appConfig = {
   router: {
diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md
index feeb88ebc5..bbce9a95ff 100644
--- a/docs/guide/migrate.md
+++ b/docs/guide/migrate.md
@@ -3,6 +3,15 @@ title: 迁移到 icejs
 order: 4
 ---
 
+## 为什么要迁移到 icejs
+
+只需要添加一个 icejs 依赖，即可拥有以下功能：
+
+* 基于 build-scripts 实现，且完全兼容 ice-scripts@2.x 的配置能力，更好的构建体验
+* 内置支持基于 icestore 的状态管理方案，使用更简单更友好
+* 内置支持基于 axios 的数据请求方案，以及日志、工具函数等功能
+* 丰富的插件支持，通过插件可快速接入和编写 SPA、MPA、微前端、SSR 等应用类型
+
 ## 从 ice-scripts@2.x 迁移
 
 ### 修改 package.json