sagaroute-vscode

❗注意: 在vscode extension marketplace中该文档会存在图片和链接不能查看的情况，请前往github或gitee进行阅读

介绍

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

特点

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

使用

1. 安装插件

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

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

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

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
}

可看以下效果图：

routeProps属性的设置值支持任意类型，不过要遵循编码规则，详情请看此处

配置参数

sagaroute中支持指定的配置项如下所示：

配置项中所有参数的简要说明如下所示：

注意❗：在该插件中，hooks的print.write.after不会被执行。

对上述配置参数中更详细的说明可看API

配置设置方式

往项目中添加sagaroute.config.js或sagaroute.config.cjs作为配置文件，在文件中以CommonJS的格式编写和导出部分上述配置项，例如：

/** @type {import('@sagaroute/react').RoutingOption} */
module.exports = {
  // 指定页面文件目录
  dirpath: 'src/views',
  // 指定路由模板文件
  routeFilePath: 'src/router/index.jsx',
};

命令

sagaroute-vscode提供了以下命令，可通过(CMD/CTRL + Shift + P)唤出命令面板后输入使用：

• Sagaroute: routing: 生成路由列表，若存在缓存，则无视缓存重新构建
• Sagaroute: rebuild: 重新根据配置文件构建配置，并执行生成路由列表的操作
• Sagaroute: show: 打开sagaroute-vscode的output输出面板
• Sagaroute: parse: 用于根据url快速定位文件，详情请看高级特性-通过url快速定位文件

.vscode/settings.json中的设置

1. sagaroute.working: 决定sagaroute-vscode是否开启监听路由文件目录的变化以动态生成约定式路由列表，如下所示：

   {
     // true代表开启监控
     "sagaroute.working": true
   }
   

2. sagaroute.decoration: 决定路由高亮的样式，详细可看路由高亮

状态栏

在vscode底部的状态栏中会有sagaroute-vscode的状态控件，以显示sagaroute-vscode是否处于监听路由文件目录中。如下所示：

你也可以通过点击该状态控件来切换监听状态。监听状态会同步到.vscode/settings.json的sagaroute.working变量中

常见问题🤔️

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

答：是的。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. 只在路由列表变化时更新文件：对每个非缓存的新路由，会与缓存中的路由进行对比，如果所有对比结果与上次相同且没有增删的路由，则不会更改文件内容，避免频繁的热更新

可看以下👇效果图：

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