✨✨ 开源一款可以补全提示、诊断、定位、高亮的约定式路由vscode插件

📝 sagaroute-vscode 简介

阅前须知：该插件生成的约定式路由列表仅适用于react-router@6+(适用于 vue-router@4 特性的仍在开发中)

sagaroute-vscode是一款约定式路由管理插件，除了快速生成约定式路由 ，还支持在编码过程中对路由的智能提示 、快速定位 、诊断 、高亮显示等功能。运行效果可看以下展示：

文件变化后触发约定式路由的更新

支持路由的样式高亮、智能提示、悬浮显示和点击跳转到路由对应组件

支持对路由的诊断，不匹配的路由将以警告显示

github 仓库地址

gitee 仓库地址

✨ 核心特性

• 🌴 泛用性: 生成的约定式路由列表 遵循ES6 Module格式，适用于任何开发环境
• 🔖 智能提示: 在填写路由参数处会冒出路由选择项，在选择项中可查看该路由对应的组件文件信息
• 🎯 精准定位: 可通过点击路由和解析url跳转到路由对应的组件文件
• 📇 路由诊断: 支持对路由进行检测，不匹配的路由将以警告显示

🏗️ 使用指南

1. 安装插件

从vscode的EXTENSTIONS: MARKETPLACE中下载，如下所示 👇：

下载sagaroute-vscode后会发现Vscode右下角的状态栏出现了一个如下的控件：

此时代表Sagaroute没有开启监听

sagaroute-vscode在每个项目中是默认不开启监听工作的，需要开发者手动点击上面 👆 的控件切换监听状态，当开启监听后控件会如下所示

此时代表Sagaroute已开启监听

2. 在路由模板文件中用注释做标记注入

路由模板文件是指要被注入路由列表的文件，我们需要通过注释来指明路由模板文件 中哪个位置被注入路由列表 和依赖

例如存在路由模板文件，其内容如下：

import React from "react";

const routes = [];
const router = createBrowserRouter(routes);
export default router;

我们需要对上述文件用注释进行标记，标记后如下所示：

import React from "react";
import { createBrowserRouter } from "react-router-dom";
/* sagaroute-inject:imports */

/* sagaroute-inject:routes */
const routes = [];
const router = createBrowserRouter(routes);
export default router;

其中/* sagaroute-inject:imports */用于标记依赖 注入的位置，/* sagaroute-inject:routes */用于标记路由列表注入的位置。

3. 生成路由列表

sagaroute-vscode会监听页面文件目录 里的文件，当更改的文件CRTL+S保存时开始执行生成路由，同时你也可以使用命令要求本插件开始生成路由，即(CMD/CTRL + Shift + P)唤出命令面板后输入Sagaroute: routing，如下 👇 所示：

📐 常见问题

如何设置路由属性

答：你可以在组件的routeProps字段中设置属性，routeProps上的所有属性会复制到注册路由上：

假如存在src/pages/users.tsx文件，其文件内容如下所示：

import ErrorBoundary from "@/components/ErrorBoundary";

export default function Users() {
  return <div>Users...</div>;
}

// 设置routeProps
/** @type {import('react-router-dom').RouteObject} */
Users.routeProps = {
  caseSensitive: false,
  ErrorBoundary: ErrorBoundary,
};

生成的注册路由如下所示：

{
  path:'user',
  element:<PagesUsers/>,
  caseSensitive: false,
  ErrorBoundary: ComponentsErrorBoundary
}

可看以下效果图：

支持生成懒加载的路由吗？

答：是的。sagaroute-vscode支持批量生成lazy路由

lazy是react-router@6.4新增的路由属性，用于路由文件的懒加载，lazy有多种写法，如下所示：

[
  // 写法1: 只对路由文件进行懒加载
  {
    path: "projects",
    loader: ({ request }) => fetchDataForUrl(request.url),
    lazy: () => import("./projects"),
  },
  // 写法2: 对路由文件及其路由属性变量进行懒加载
  {
    path: "messages",
    async lazy() {
      let { messagesLoader, Messages } = await import("./pages/Dashboard");
      return {
        loader: messagesLoader,
        Component: Messages,
      };
    },
  },
];

本插件可以通过设置lazy配置项统一生成上述 👆 第 2 种写法的lazy路由，如下 👇 效果图：

每次文件内容的变动都会触发路由列表的更新吗？

答：不一定。

本插件内部实现了路由对象的缓存机制，因此存在以下优点：

1. 加速二次生成路由的速度：对内容未更改的文件会直接取缓存作为生成结果，加快生成整个路由列表的生成速度
2. 只在路由列表变化时更新文件：对每个非缓存的新路由，会与缓存中的路由进行对比，如果所有对比结果与上次相同且没有增删的路由，则不会更改文件内容，避免频繁的热更新

可看以下 👇 效果图：

1. 生成路由与上次一致时，不会更改路由文件的内容

2. 生成路由与上次不一致时，才会更改路由文件的内容

若要无视缓存强制生成路由列表，则可使用Sagaroute: routing命令

📮 高级特性

路由智能提示

sagaroute-vscode会对react-router提供的API中需要传入路由字符串的形参处提供路由可选项，例如<Link/>和<Navigate/>的to参数、useHref和useLinkClickHandler的第一形参等。路由可选项会在用户键入/后弹出。如下 👇 所示：

在路由可选项的右侧会提供提供以下信息：

1. 该路由对应的组件文件路径
2. 该路由对应的组件的注释信息（如果存在则显示，否则不显示）

---

除此之外，sagaroute-vscode还支持相对路径的路由智能提示。假设有以下场景：

当前项目的路由列表如下所示：

[
  {
    path: "form",
    children: [
      {
        path: ":type",
        element: <PagesFormType />,
      },
      {
        index: true,
        element: <PagesFormIndex />,
      },
      {
        path: "review",
        element: <PagesFormReview />,
      },
    ],
  },
  // 其余路由对象省略...
];

当我们在上述路由列表中的<PagesFormIndex />组件对应的文件进行编码且使用相对路径时，会有以下效果 👇：

从上述效果可看出：

1. 当键入./时，会给予当前文件对应的路由(/form)去提供路由可选项，此时出现:type和review两个可选值
2. 当键入../时，结合当前文件对应的路由(/form)算出此时路由为/，即根路径，此时出现的路由可选值为整个路由列表

路由诊断

sagaroute-vscode会对react-router提供的API（如Link、Navigate、useHref等）中传入路由字符串的形参处进行路由诊断，所谓路由诊断就是查看路由字符串是否匹配路由列表中的路由，如果不匹配，sagaroute-vscode会对该路由字符串标黄警告显示，如下所示：

从上述效果可知，路由诊断对相对路径和绝对路径的路由都会进行诊断。

注意 ❗：sagaroute-vscode不会对带变量的模板字符串作诊断，例如：

// 不会诊断，因为无法判断其中的变量的值
navigate(`/form/${params}`);
// 会诊断，因为是常量
navigate(`/form/review`);

如果用户想手动禁止路由诊断，可通过添加sagaroute-vscode提供的以下两种注释内容去禁止：

1. sagaroute-ignore-next-line: 禁止该注释的下一行代码的路由诊断，例如：

   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会跳转到该路由字符串对应的文件页面上，如下所示：

注意 ❗：路由跳转对相对路径和绝对路径都生效，但对带变量的模板字符串不生效，例如：

// 不会跳转，因为无法判断其中的变量的值
navigate(`/form/${params}`);

路由悬浮显示组件信息

sagaroute-vscode会对react-router提供的API（如Link、Navigate、useHref等）中传入路由字符串的形参处提供查看组件信息功能。当鼠标悬浮到该路由字符串，而该路由字符串有可以匹配路由列表中的路由时，sagaroute-vscode会冒泡呈现该路由组件的信息，如下所示：

悬浮内容会提供以下信息：

1. 该路由对应的组件文件路径
2. 该路由对应的组件的注释信息（如果存在则显示，否则不显示）

注意 ❗：路由跳转对相对路径和绝对路径都生效，但对带变量的模板字符串不生效，例如：

// 不会冒泡显示，因为无法判断其中的变量的值
navigate(`/form/${params}`);

通过 url 定位路由文件

可通过Sagaroute: parse指令唤出输入框，在输入框中输入要定位的url，sagaroute-vscode会解析url并在编辑窗口中打开该url对应的文件，如下效果图所示：

开发者无须关心url对应的路由模式是hash还是browser，sagaroute-vscode会自行判断处理

注意 ❗: 在vscode项目首次打开时，要先做保存操作或者强制Sagaroute: routing触发路由列表刷新后，才会有开启快捷选择路由路径

路由高亮

sagaroute-vscode会对react-router提供的API（如Link、Navigate、useHref等）中传入路由字符串的形参处进行高亮显示，如下所示：

用户也可以自定义路由的高亮样式，在.vscode/settings.json中，提供了sagaroute.decoration去设置高亮样式，如下所示：

{
  "sagaroute.decoration": {
    "color": "#ad4e00", // 路由字体颜色
    "backgroundColor": "#ffe7ba" // 路由背景颜色
  }
}

效果如下所示：

注意 ❗：路由跳转对对带变量的模板字符串不生效

🔨 本插件的可靠性

本vscode插件包含两部分：sagaroute-vscode和其依赖的核心库@sagaroute/react，其测试用例情况如下 👇 所示：

• sagaroute-vscode: 含 14 个快照测试，代码覆盖率未统计（暂未找到如何在vscode extension测试中统计代码覆盖率的方法）
• @sagaroute/react: 含 86 个单例测试和快照测试，代码覆盖率 98%

以上测试用例在window、macOS、ubuntu环境均可跑通，因此大家可以放心食用。

关于流水线的运行详情请看github action workflow