docs: 添加"问题及解决方案",优化文档

bhuh12 · bhuh12 · commit a6efe5ac9045 · 2019-07-11T00:39:06.000+08:00
diff --git a/README.md b/README.md
@@ -46,73 +46,74 @@
 
 <h2 align="center">Vue Router Tab</h2>
 
-Vue Router Tab 是基于 `Vue Router` 的路由页签组件，用来实现多页签页面的管理。
+Vue Router Tab 是基于 Vue Router 的路由页签组件，用来实现多页签页面的管理。
 
 
-## 功能
+## 📌 功能
 
-- 响应路由变化来打开或切换页签
-- 页签右键菜单操作
-- [页签规则](https://bhuh12.github.io/vue-router-tab/guide/essentials/rule.html)配置
-- 内置页签和页面[过渡效果](https://bhuh12.github.io/vue-router-tab/guide/advanced/transition.html)，支持自定义配置
-- [自定义页签模板](https://bhuh12.github.io/vue-router-tab/guide/advanced/slot.html)
-- [初始页签数据](https://bhuh12.github.io/vue-router-tab/guide/advanced/initial-tabs.html)，进入页面时默认显示的页签
-- [动态更新页签信息](https://bhuh12.github.io/vue-router-tab/guide/advanced/dynamic-tab-info.html) (标题/图标/提示)
-- [iframe 页签嵌入外部网站](https://bhuh12.github.io/vue-router-tab/guide/essentials/iframe.html)
-- [页签页面离开 (页签关闭/刷新/替换) 前确认](https://bhuh12.github.io/vue-router-tab/guide/advanced/page-leave.html)
-- [多语言支持](https://bhuh12.github.io/vue-router-tab/guide/essentials/i18n.html)
+✅ 响应路由变化来打开或切换页签
 
+✅ 页签右键菜单操作
 
-## 安装
+✅ [页签规则](https://bhuh12.github.io/vue-router-tab/guide/essentials/rule.html)配置
 
-### npm
+✅ 内置页签和页面[过渡效果](https://bhuh12.github.io/vue-router-tab/guide/advanced/transition.html)，支持自定义配置
 
-``` bash
-npm i vue-router-tab -S
-```
+✅ [自定义页签模板](https://bhuh12.github.io/vue-router-tab/guide/advanced/slot.html)
 
-### yarn (推荐)
+✅ [初始页签数据](https://bhuh12.github.io/vue-router-tab/guide/advanced/initial-tabs.html)，进入页面时默认显示的页签
 
-``` bash
-yarn add vue-router-tab
-```
+✅ [动态更新页签信息](https://bhuh12.github.io/vue-router-tab/guide/advanced/dynamic-tab-info.html) (标题/图标/提示)
 
+✅ [iframe 页签嵌入外部网站](https://bhuh12.github.io/vue-router-tab/guide/essentials/iframe.html)
+
+✅ [页签页面离开 (页签关闭/刷新/替换) 前确认](https://bhuh12.github.io/vue-router-tab/guide/advanced/page-leave.html)
+
+✅ [多语言支持](https://bhuh12.github.io/vue-router-tab/guide/essentials/i18n.html)
+
+
+## 🛠 安装
+
+[https://bhuh12.github.io/vue-router-tab/guide/installation.html](https://bhuh12.github.io/vue-router-tab/guide/installation.html)
+
+## 📝 文档
 
-## 文档：
 [https://bhuh12.github.io/vue-router-tab/](https://bhuh12.github.io/vue-router-tab/)
 
   - 介绍：
   [https://bhuh12.github.io/vue-router-tab/guide/](https://bhuh12.github.io/vue-router-tab/guide/)
 
-  - 安装：
-  [https://bhuh12.github.io/vue-router-tab/guide/installation.html](https://bhuh12.github.io/vue-router-tab/guide/installation.html)
-
   - 入门：
   [https://bhuh12.github.io/vue-router-tab/guide/essentials/](https://bhuh12.github.io/vue-router-tab/guide/essentials/)
 
-## 演示：
+  - API：
+  [https://bhuh12.github.io/vue-router-tab/api/](https://bhuh12.github.io/vue-router-tab/api/)
+
+## 📺 演示
+
 [https://bhuh12.github.io/vue-router-tab/demo/](https://bhuh12.github.io/vue-router-tab/demo/)
 
-## 更新日志
+## 📃 更新日志
+
 [https://github.com/bhuh12/vue-router-tab/releases](https://github.com/bhuh12/vue-router-tab/releases)
 
 ---
 
 
-## NPM 任务
+## 🏷 NPM 任务
 
 | 任务 | 命令 | 备注 |
 | ---- | ---- | ---- |
-| **插件**：构建 | `npm run lib:build` |
-| **插件**：构建并生成报告 | `npm run lib:build:report` |
-| **插件**：发布 | `npm run lib:publish` | 操作前：更改 `package.json` 中的 `version` 为新的版本号 |
-| **Demo**：开发 | `npm run demo:dev` |
-| **Demo**：构建 | `npm run demo:build` |
-| **文档**：开发 | `npm run docs:dev` |
-| **文档**：构建 | `npm run docs:build` |
-| **代码**风格：检查 | `npm run lint` |
-| **代码**风格：检查并修复 | `npm run lint:fix` |
-| **代码**：提交 | `npm run commit` |
+| 插件构建 | `npm run lib:build` |
+| 插件构建并生成报告 | `npm run lib:build:report` |
+| 插件发布 | `npm run lib:publish` | 操作前更改 `package.json` 中的 `version` 为新的版本号 |
+| Demo 开发 | `npm run demo:dev` |
+| Demo 构建 | `npm run demo:build` |
+| 文档开发 | `npm run docs:dev` |
+| 文档构建 | `npm run docs:build` |
+| 代码风格检查 | `npm run lint` |
+| 代码风格检查并修复 | `npm run lint:fix` |
+| 代码提交 | `npm run commit` |
 
 
 ## License
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -14,6 +14,8 @@ module.exports = {
   // 输出目录
   dest: 'dist/docs',
 
+  host: 'localhost',
+
   // 主题配置
   themeConfig: {
     // 页头导航
@@ -54,7 +56,8 @@ module.exports = {
             'advanced/dynamic-tab-info',
             'advanced/page-leave'
           ]
-        }
+        },
+        'program',
       ]
     },
 
diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -1,19 +1,28 @@
 # 介绍
 
-Vue Router Tab 是基于 `Vue Router` 的路由页签组件，用来实现多页签页面的管理。
+Vue Router Tab 是基于 Vue.js 和 Vue Router 的路由页签组件，用来实现多页签页面的管理。
 
 ### 包含的功能
 
-- 响应路由变化来打开或切换页签
-- 页签右键菜单操作
-- [页签规则](essentials/rule.md)配置
-- 内置页签和页面[过渡效果](advanced/transition.md)，支持自定义配置
-- [自定义页签模板](advanced/slot.md)
-- [初始页签数据](advanced/initial-tabs.md)，进入页面时默认显示的页签
-- [动态更新页签信息](advanced/dynamic-tab-info.md) (标题/图标/提示)
-- [iframe 页签嵌入外部网站](essentials/iframe.md)
-- [页签页面离开 (页签关闭/刷新/替换) 前确认](advanced/page-leave.md)
-- [多语言支持](essentials/i18n.md)
+✅ 响应路由变化来打开或切换页签
+
+✅ 页签右键菜单操作
+
+✅ [页签规则](essentials/rule.md)配置
+
+✅ 内置页签和页面[过渡效果](advanced/transition.md)，支持自定义配置
+
+✅ [自定义页签模板](advanced/slot.md)
+
+✅ [初始页签数据](advanced/initial-tabs.md)，进入页面时默认显示的页签
+
+✅ [动态更新页签信息](advanced/dynamic-tab-info.md) (标题/图标/提示)
+
+✅ [iframe 页签嵌入外部网站](essentials/iframe.md)
+
+✅ [页签页面离开 (页签关闭/刷新/替换) 前确认](advanced/page-leave.md)
+
+✅ [多语言支持](essentials/i18n.md)
 
 
 ### 主流多页签方案的缺陷
@@ -29,25 +38,27 @@ Vue Router Tab 是基于 `Vue Router` 的路由页签组件，用来实现多页
 4. 无法定制页签打开的规则
 
 
-另外还看到一种方案，是弃用 `Vue Router`，自行实现路由和缓存控制。该方案需要使用其提供的 API 来控制页签打开和切换，对于现有的 `Vue Router` 项目引入改动量比较大。
+另外还看到一种方案，是弃用 Vue Router，自行实现路由和缓存控制。该方案需要使用其提供的 API 来控制页签打开和切换，对于现有的 Vue Router 项目引入改动量比较大。
 
 ---
 
-### Vue Router Tab 方案
+### Vue Router Tab 的优势
+
+针对现存方案的各种问题，Vue Router Tab 定制开发了 `<router-alive>` 缓存组件来控制路由页面缓存（感兴趣的朋友可以看看：[问题与解决方案](program.md)）。
 
-针对现存方案的各种问题，`Vue Router Tab` 定制开发了 `<router-alive>` 缓存组件来控制路由页面缓存。除了解决了其他方案的不足，`Vue Router Tab` 还拥有以下优势：
+除了解决了其他方案的不足，Vue Router Tab 还拥有以下优势：
 
-1. `Vue Router Tab` 是完全响应 `Vue Router` 路由的。使用熟悉的 `<router-link>` 或者 `router.push` 等 api 即可方便的打开和切换页签，您可以使用 `Vue Router` 的完整功能。
+1. Vue Router Tab 是完全响应 Vue Router 路由的。使用熟悉的 `<router-link>` 或者 `router.push` 等 api 即可方便的打开和切换页签，您可以使用 Vue Router 的完整功能。
 
-2. `Vue Router Tab` 只依赖 `Vue` 和 `Vue Router` 。不会引入额外的依赖。
+2. Vue Router Tab 只依赖 Vue.js 和 Vue Router 。不会引入额外的依赖。
 
 3. 配置简单，引入组件后通过路由的 `meta` 配置页签信息即可
 
 4. 可以方便的定制页签的打开规则，精准控制路由页签
 
 5. 丰富的选项提供你可能需要的额外功能和自定义配置
 
-6. 提供完善的文档说明、代码示例和Demo演示
+6. 提供完善的文档说明、代码示例和 Demo 演示
 
 ---
 
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
@@ -1,17 +1,24 @@
 # 安装
 
+::: warning
+请确保你的 Node.js 版本 >= 8.6，旧的版本可能存在错误。
+:::
+
 ### NPM
 
+推荐使用 yarn：
+
 ``` bash
-npm install vue-router-tab
+yarn add vue-router-tab
 ```
 
-**yarn** (推荐)
+你也可以用 npm：
 
 ``` bash
-yarn add vue-router-tab
+npm i vue-router-tab -S
 ```
 
+
 ### 构建开发版
 
 如果你想使用最新的开发版，就得从 GitHub 上直接 clone，然后自己 build 一个 `vue-router-tab`。
diff --git a/docs/guide/program.md b/docs/guide/program.md
@@ -0,0 +1,33 @@
+# 方案
+
+Vue Router Tab 实现过程中遇到的**问题及解决方案**，也欢迎提出更好的点子。
+
+
+1. `keep-alive` 仅支持根据组件 `name` 控制缓存，无法针对路由精确控制：
+
+    参考 `keep-alive` 实现 `router-alive` 组件，基于 Vue Router 路由规则的缓存控制
+
+2. 页面组件强制刷新：
+
+   1. 销毁页面组件实例
+   2. `router-view` 组件通过 `v-if` 隐藏，在 `nextTick` 后再显示
+
+3. 由于缓存，Webpack 热加载后的页面不刷新：
+   
+    在路由页面组件全局混入的 `activated` 钩子里，记录 `vm.$vnode.componentOptions.Ctor.cid`。如果与上一次的值不一致，则销毁页面，组件重新渲染
+
+4. 当快速频繁切换页签时，页面显示空白：
+
+    根因：旧页面离开的过渡效果尚未完成，新页面内容来不及 mount 又被后面的路由替换
+
+    方案：路由切换结束后，如果路由页面节点 `nodeType` 为 8 (comment 类型)，强制刷新页面组件
+
+5. iframe 页面页签切换后会重新加载：
+
+   1. 将  `<iframe>` 节点放在页面所在 `<router-view>` 的外层，通过 `v-show` 控制显示隐藏。
+
+   2. 建立 iframe 路由页面组件，通过生命周期钩子来添加、显示、隐藏、移除 `<iframe>` dom 节点
+
+6. 打包后的 js 文件太庞大：
+
+    构建库时，配置 `babel.config.js` 中 `useBuiltIns` 为 `false`，打包时不包含 Polyfill
diff --git a/yarn.lock b/yarn.lock
