Merge pull request #7 from Hitotsubashi/feature-doc

Feature doc

README.md

@@ -27,7 +27,7 @@
 
 如果只是想在日常开发中为项目生成路由列表，那以下**基础插件**可以满足大部分需求
 
-- [`sagaroute-vscode`](./packages/vscode-ext/README.md): 用于快速生成约定式路由列表的`VSCode`插件，可持续监听工作区的文件变动以动态生成路由列表
+- [`sagaroute-vscode`](./packages/vscode-ext/README.md): 一款约定式路由管理插件，除了**快速生成约定式路由**，还支持在编码过程中对路由的**智能提示**、**快速定位**、**诊断**、**高亮显示**等功能
 - [`@sagaroute/cmd`](./packages/cmd/README.md): 快速生成约定式路由列表的命令行工具
 
 ### 高级插件

packages/vscode-ext/.vscode/settings.json

@@ -4,5 +4,6 @@
   },
   "typescript.tsc.autoDetect": "off",
   "prettier.printWidth": 100,
-  "auto-rename-tag.activationOnLanguage": ["*"]
+  "auto-rename-tag.activationOnLanguage": ["*"],
+  "sagaroute.working": false
 }

packages/vscode-ext/README.md

@@ -6,40 +6,31 @@
 
 ## 介绍
 
-`sagaroute-vscode`是一款基于`@sagaroute/react`开发的约定式路由管理插件，它能**监听文件变化以快速更新路由列表**，且会根据路由列表提供[**快捷提示路由信息**](#快捷选择路由路径)和[**快速定位路由页面**](#支持通过url快速定位文件)的交互优化。运行效果可看以下展示：
+`sagaroute-vscode`是一款约定式路由管理插件，除了**快速生成约定式路由**，还支持在编码过程中对路由的**智能提示**、**快速定位**、**诊断**、**高亮显示**等功能。运行效果可看以下展示：
 
 <p align="center">
     <img alt="overview-generate-after-save" src="./doc/images/overview-generate-after-save.gif" width="500">
-    <div align="center">文件变化后触发路由列表更新</div>
+    <div align="center">文件变化后触发约定式路由的更新</div>
 </p>
 
 <p align="center">
-    <!-- TODO: 快捷键快速选择路由重新截图 -->
-    <img alt="overview-completion" src="./doc/images/overview-completion.gif" width="500">
-    <div align="center">支持通过快捷键快速查看和选择路由</div>
+    <img alt="overview-completion" src="./doc/images/route-completion-hover-definition.gif" width="500">
+    <div align="center">支持路由的样式高亮、智能提示、悬浮显示和点击跳转到路由对应组件</div>
 </p>
 
 <p align="center">
-    <!-- TODO: 悬浮提示路由信息截图 -->
-    <img alt="overview-completion" src="./doc/images/overview-completion.gif" width="500">
-    <div align="center">支持鼠标悬浮查看路由文件信息</div>
-</p>
-
-<p align="center">
-    <!-- TODO: parse截图 -->
-    <img alt="overview-completion" src="./doc/images/overview-completion.gif" width="500">
-    <div align="center">支持快速打开url对应的页面文件</div>
+    <img alt="overview-completion" src="./doc/images/route-diagnostic.gif" width="500">
+    <div align="center">支持对路由的诊断，不匹配的路由将以警告显示</div>
 </p>
 
 ## 特点
 
+<!-- TODO以下功能新增链接 -->
+
 - 🌴 泛用性: 生成的**约定式路由列表**遵循`ES6 Module`格式，适用于任何开发环境
-- 🎯 路由提示: 支持快速选择路由和查看路由组件信息
-- 🚀 快速稳定: 合理利用[缓存机制](#缓存)，使第二次的生成速度更快。若生成结果与上次相同，则不会更改**路由模板文件**
-- 📇 样式一致: 生成**路由列表**保存后会自动触发代码风格约束插件的格式化(如`prettier`、`eslint`，取决于`vscode`安装了哪些插件)
-- 📲 快捷定位: 支持快速打开`url`对应的页面文件
-  <!-- - 📲 实用性: 采用近似于[`umi`](https://v3.umijs.org/zh-CN/docs/convention-routing)的[约定式路由规则](../react/doc/Routing.md)，更贴近实际开发场景 -->
-    <!-- - 🎉 可扩展: 支持[配置文件](../react/README.md#配置文件)，可通过钩子函数控制工作流程或增强路由对象 -->
+- 🔖 [智能提示](./doc/Advanced.md#路由智能提示): 在填写路由参数处会冒出路由选择项，在选择项中可查看该路由对应的组件文件信息
+- 🎯 精准定位: 可通过[点击路由](./doc/Advanced.md#路由跳转)和[解析`url`跳转](./doc/Advanced.md#通过url定位路由文件)到路由对应的组件文件
+- 📇 [路由诊断](./doc/Advanced.md#路由诊断): 支持对路由进行检测，不匹配的路由将以警告显示
 
 ## 使用
 
@@ -51,30 +42,20 @@
     <img alt="status-sleeping" src="./doc/images/download-marketplace.png" >
 </p>
 
-下载`Sagaroute`后会发现`Vscode`右下角的状态栏出现了一个如下的控件：
+下载`sagaroute-vscode`后会发现`Vscode`右下角的状态栏出现了一个如下的控件：
 
 <p align="center">
     <img alt="status-sleeping" src="./doc/images/status-sleeping.png" >
     <div align="center">此时代表Sagaroute没有开启监听</div>
 </p>
 
-`Sagaroute`在每个项目中是默认不开启监听工作的，需要开发者手动点击上面 👆 的控件切换监听状态，当开启监听后控件会如下所示
+`sagaroute-vscode`在每个项目中是默认不开启监听工作的，需要开发者手动点击上面 👆 的控件切换监听状态，当开启监听后控件会如下所示
 
 <p align="center">
     <img alt="status-watching" src="./doc/images/status-watching.png" >
     <div align="center">此时代表Sagaroute已开启监听</div>
 </p>
 
-<!-- ### 2. 在项目中下载`@sagaroute/react`(非必须但推荐)
-
-```bash
-npm install @sagaroute/react
-```
-
-**_与`prettier-vscode`一样，在`sagaroute-vscode`中有内嵌的`@sagaroute/react`，因此即使不做这一步也不会影响运行。但这里推荐做做这一步是因为这样确保不同开发者在同一项目中使用的`@sagaroute/react`的版本是一致的，避免因版本不同导致的差异化情况_**
-
-**执行该步骤后需要重启`Vscode`才会生效** -->
-
 ### 2. 在路由模板文件中用注释做标记注入
 
 [**路由模板文件**](../react/doc/Template.md)是指要被注入路由列表的文件，我们需要通过注释来指明**路由模板文件**中哪个位置被注入**路由列表**和**依赖**
@@ -106,7 +87,7 @@ export default router;
 
 ### 3. 生成路由列表
 
-`@sagaorute/vscode-extension`会监听**页面文件目录**里的文件，当更改的文件`CRTL+S`保存时开始执行生成路由，同时你也可以使用命令要求本插件开始生成路由，即(CMD/CTRL + Shift + P)唤出命令面板后输入`Sagaroute: routing`，如下 👇 所示：
+`sagaroute-vscode`会监听**页面文件目录**里的文件，当更改的文件`CRTL+S`保存时开始执行生成路由，同时你也可以使用命令要求本插件开始生成路由，即(CMD/CTRL + Shift + P)唤出命令面板后输入`Sagaroute: routing`，如下 👇 所示：
 
 <p align="center">
     <img alt="command-routing" src="./doc/images/command-routing.gif" >
@@ -152,7 +133,7 @@ Users.routeProps = {
 
 ## 配置参数
 
-`@sagaroute/cmd`中支持指定的配置项如下所示：
+`sagaroute`中支持指定的配置项如下所示：
 
 配置项中所有参数的简要说明如下所示：
 
@@ -191,82 +172,43 @@ module.exports = {
 
 - `Sagaroute: routing`: 生成路由列表，若存在缓存，则无视缓存重新构建
 - `Sagaroute: rebuild`: 重新根据[配置文件](#配置设置方式)构建配置，并执行生成路由列表的操作
-- `Sagaroute: show`: 打开`Sagaroute`的`output`输出面板
-- `Sagaroute: parse`: 用于根据`url`快速定位文件，详情请看[高级特性-通过url快速定位文件](#支持通过url快速定位文件)
+- `Sagaroute: show`: 打开`sagaroute-vscode`的`output`输出面板
+- `Sagaroute: parse`: 用于根据`url`快速定位文件，详情请看[高级特性-通过url快速定位文件](./doc/Advanced.md#通过url定位路由文件)
 
-## `.vscode/settings.json`中的`Sagaroute`设定
+## `.vscode/settings.json`中的设置
 
-你可以在`.vscode/settings.json`中设置`sagaroute.working`变量，以决定`Sagaroute`是否开启监听**路由文件目录**的变化以动态生成约定式路由列表，如下所示：
+1. `sagaroute.working`: 决定`sagaroute-vscode`是否开启监听**路由文件目录**的变化以动态生成约定式路由列表，如下所示：
 
-```json
-{
-  // true代表开启监控
-  "sagaroute.working": true
-}
-```
+   ```js
+   {
+     // true代表开启监控
+     "sagaroute.working": true
+   }
+   ```
+
+2. `sagaroute.decoration`: 决定路由高亮的样式，详细可看[路由高亮](./doc/Advanced.md#路由高亮)
 
 ## 状态栏
 
-在`vscode`底部的状态栏中会有`Sagaroute`的状态控件，以显示`Sagaroute`是否处于监听**路由文件目录**中。如下所示：
+在`vscode`底部的状态栏中会有`sagaroute-vscode`的状态控件，以显示`sagaroute-vscode`是否处于监听**路由文件目录**中。如下所示：
 
 <p align="center">
     <img alt="status-sleeping" src="./doc/images/status-sleeping.png" >
-    <div align="center">白字代表Sagaroute没有监听</div>
+    <div align="center">白字代表sagaroute-vscode没有监听</div>
 </p>
 
 <p align="center">
     <img alt="status-watching" src="./doc/images/status-watching.png">
-    <div align="center">绿字代表Sagaroute正在监听</div>
+    <div align="center">绿字代表sagaroute-vscode正在监听</div>
 </p>
 
 你也可以通过点击该状态控件来切换监听状态。监听状态会同步到`.vscode/settings.json`的`sagaroute.working`变量中
 
-## 高级特性
-
-### 快捷选择路由
-
-你可以在项目中通过键入快捷键`"//"`调出所有可选路由，如下所示：
-
-<!-- TODO:替换图片 -->
-
-![overview-completion](./doc/images/overview-completion.gif)
+## 常见问题🤔️
 
-选择后，`"//"`会被替换成所选择的路由路径
+### 支持生成懒加载的路由吗？
 
-其中可选项会展示以下信息：
-
-![completion-documentaion](./doc/images/completion-documentaion.png)
-
-1. 路由对应的文件路径链接
-2. 路由对应的文件中的默认导出组件的注释（如果存在）
-
-**注意: 在`vscode`项目首次打开时，要先做保存操作或者强制`Sagaroute: routing`触发路由列表刷新后，才会有开启快捷选择路由路径**
-
-### 快捷查看路由对应的文件信息
-
-<!-- TODO:如果实现了路由高亮，则去掉cannot not find match route的功能，否则就保持 -->
-
-你可以通过鼠标停留路由字符串查看路由信息，此时路由信息会以悬浮冒泡的形式展示，如下所示：
-
-<!-- TODO: 补充悬浮显示路由信息的gif图，用``作为路由格式-->
-
-所展示路由信息的内容与[快捷选择路由](#快捷选择路由)的一致。若该路由字符串不存在能与之匹配的路由，则会显示以下信息：
-
-![no-route-matched](./doc/images/no-route-matched.png)
-
-**注意: 在`vscode`项目首次打开时，要先做保存操作或者强制`Sagaroute: routing`触发路由列表刷新后，才会有开启快捷选择路由路径**
-
-### 支持通过url快速定位文件
-
-可通过`Sagaroute: parse`指令唤出输入框，在输入框中输入要定位的`url`，`sagaroute-vscode`会解析`url`并在编辑窗口中打开该`url`对应的文件，如下效果图所示：
-
-<!-- TODO 添加sagaroute.parse效果图 -->
-
-**_开发者无须关心`url`对应的路由模式是`hash`还是`browser`，`sagaroute-vscode`会自行判断处理_**
-
-**注意: 在`vscode`项目首次打开时，要先做保存操作或者强制`Sagaroute: routing`触发路由列表刷新后，才会有开启快捷选择路由路径**
-
-### 支持批量生成`lazy`路由
+答：是的。`sagaroute-vscode`支持批量生成`lazy`路由
 
 [`lazy`](https://reactrouter.com/en/main/route/lazy#lazy)是`react-router@6.4`新增的路由属性，用于路由文件的懒加载，`lazy`有多种写法，如下所示：
 
@@ -296,7 +238,9 @@ module.exports = {
 
 ![save-with-lazy](./doc/images/save-with-lazy.gif)
 
-### 缓存
+### 每次文件内容的变动都会触发路由列表的更新吗？
+
+答：不一定。
 
 本插件内部实现了路由对象的缓存机制，因此存在以下优点：
 

packages/vscode-ext/doc/Advanced.md

@@ -0,0 +1,155 @@
+# 高级特性
+
+## 路由智能提示
+
+`sagaroute-vscode`会对`react-router`提供的`API`中需要传入路由字符串的形参处提供路由可选项，例如`<Link/>`和`<Navigate/>`的`to`参数、`useHref`和`useLinkClickHandler`的第一形参等。路由可选项会在用户键入`/`后弹出。如下👇所示：
+
+![route-just-completion](./images/route-just-completion.gif)
+
+在路由可选项的右侧会提供提供以下信息：
+
+1. 该路由对应的组件文件路径
+2. 该路由对应的组件的注释信息（如果存在则显示，否则不显示）
+
+---
+
+除此之外，`sagaroute-vscode`还支持**相对路径**的路由智能提示。假设有以下场景：
+
+当前项目的路由列表如下所示：
+
+```jsx
+[
+  {
+    path: 'form',
+    children: [
+      {
+        path: ':type',
+        element: <PagesFormType />,
+      },
+      {
+        index: true,
+        element: <PagesFormIndex />,
+      },
+      {
+        path: 'review',
+        element: <PagesFormReview />,
+      },
+    ],
+  },
+  // 其余路由对象省略...
+];
+```
+
+当我们在上述路由列表中的`<PagesFormIndex />`组件对应的文件进行编码且使用相对路径时，会有以下效果👇：
+
+![route-relative-completion](./images/route-relative-completion.gif)
+
+从上述效果可看出：
+
+1. 当键入`./`时，会给予当前文件对应的路由(`/form`)去提供路由可选项，此时出现`:type`和`review`两个可选值
+2. 当键入`../`时，结合当前文件对应的路由(`/form`)算出此时路由为`/`，即根路径，此时出现的路由可选值为整个路由列表
+
+## 路由诊断
+
+`sagaroute-vscode`会对`react-router`提供的`API`（如`Link`、`Navigate`、`useHref`等）中传入路由字符串的形参处进行路由诊断，所谓路由诊断就是查看路由字符串是否匹配路由列表中的路由，如果不匹配，`sagaroute-vscode`会对该路由字符串标黄警告显示，如下所示：
+
+![route-diagnostic-both](./images/route-diagnostic-both.gif)
+
+从上述效果可知，路由诊断对相对路径和绝对路径的路由都会进行诊断。
+
+**注意❗：`sagaroute-vscode`不会对带变量的模板字符串作诊断**，例如：
+
+```js
+// 不会诊断，因为无法判断其中的变量的值
+navigate(`/form/${params}`);
+// 会诊断，因为是常量
+navigate(`/form/review`);
+```
+
+如果用户想手动禁止路由诊断，可通过添加`sagaroute-vscode`提供的以下两种注释内容去禁止：
+
+1.  `sagaroute-ignore-next-line`: 禁止该注释的下一行代码的路由诊断，例如：
+
+    ```jsx
+    function() {
+        const navigate = useNavigate();
+        /* sagaroute-ignore-next-line */
+        const toPage = () => { navigate("/form/index"); };//此处不会进行代码诊断
+
+        return (
+            <div>
+                UserPage-d
+                {
+                    // sagaroute-ignore-next-line
+                    <Link to="../b1">toPage</Link> //此处不会进行代码诊断
+                }
+            </div>
+        );
+    }
+    ```
+
+2.  `sagaroute-ignore`: 禁止对该注释下的文件内容进行路由诊断
+
+## 路由跳转
+
+`sagaroute-vscode`会对`react-router`提供的`API`（如`Link`、`Navigate`、`useHref`等）中传入路由字符串的形参处提供路由跳转功能。当`ctrl`+`鼠标点击`该路由字符串，而该路由字符串有可以匹配路由列表中的路由时，`sagaroute-vscode`会跳转到该路由字符串对应的文件页面上，如下所示：
+
+![route-definition](./images/route-definition.gif)
+
+**注意❗：路由跳转对相对路径和绝对路径都生效，但对带变量的模板字符串不生效**，例如：
+
+```js
+// 不会跳转，因为无法判断其中的变量的值
+navigate(`/form/${params}`);
+```
+
+## 路由悬浮显示组件信息
+
+`sagaroute-vscode`会对`react-router`提供的`API`（如`Link`、`Navigate`、`useHref`等）中传入路由字符串的形参处提供查看组件信息功能。当鼠标悬浮到该路由字符串，而该路由字符串有可以匹配路由列表中的路由时，`sagaroute-vscode`会冒泡呈现该路由组件的信息，如下所示：
+
+![route-hover](./images/route-hover.gif)
+
+悬浮内容会提供以下信息：
+
+1. 该路由对应的组件文件路径
+2. 该路由对应的组件的注释信息（如果存在则显示，否则不显示）
+
+**注意❗：路由跳转对相对路径和绝对路径都生效，但对带变量的模板字符串不生效**，例如：
+
+```js
+// 不会冒泡显示，因为无法判断其中的变量的值
+navigate(`/form/${params}`);
+```
+
+## 通过url定位路由文件
+
+可通过`Sagaroute: parse`指令唤出输入框，在输入框中输入要定位的`url`，`sagaroute-vscode`会解析`url`并在编辑窗口中打开该`url`对应的文件，如下效果图所示：
+
+![route-parse](./images/route-parse.gif)
+
+开发者无须关心`url`对应的路由模式是`hash`还是`browser`，`sagaroute-vscode`会自行判断处理
+
+**注意❗: 在`vscode`项目首次打开时，要先做保存操作或者强制`Sagaroute: routing`触发路由列表刷新后，才会有开启快捷选择路由路径**
+
+## 路由高亮
+
+`sagaroute-vscode`会对`react-router`提供的`API`（如`Link`、`Navigate`、`useHref`等）中传入路由字符串的形参处进行高亮显示，如下所示：
+
+![route-highlight](./images/route-highlight.png)
+
+用户也可以自定义路由的高亮样式，在`.vscode/settings.json`中，提供了`sagaroute.decoration`去设置高亮样式，如下所示：
+
+```js
+{
+  "sagaroute.decoration": {
+    "color": "#ad4e00", // 路由字体颜色
+    "backgroundColor": "#ffe7ba" // 路由背景颜色
+  }
+}
+```
+
+效果如下所示：
+
+![route-hightlight](./images/route-highlight.gif)
+
+**注意❗：路由跳转对对带变量的模板字符串不生效**