sagaroute-vscode

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

介绍

sagaroute-vscode是一款基于@sagaroute/react开发的用于快速生成约定式路由列表的VSCode插件，它会监听路由文件目录的变化以动态生成约定式路由列表，并把生成结果插入到指定路由模板文件

特点

• 🌴 泛用性: 生成的约定式路由列表遵循ES6 Module格式，适用于任何开发环境
• 🎯 智能提示: 具有路由路径智能提示机制
• 🚀 快且稳: 合理利用缓存机制，使第二次的生成速度更快。若生成结果与上次相同，则不会更改路由模板文件
• 📲 实用性: 采用近似于umi的约定式路由规则，更贴近实际开发场景
• 📇 样式一致: 生成路由列表保存后会自动触发代码风格约束插件的格式化(如prettier、eslint，取决于vscode安装了哪些插件)
• 🎉 可扩展: 支持配置文件，可通过钩子函数控制工作流程或增强路由对象

使用

1. 安装插件

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

2. 在项目中下载@sagaroute/react(非必须但推荐)

npm install @sagaroute/react

与prettier-vscode一样，在sagaroute-vscode中有内嵌的@sagaroute/react，因此即使不做这一步也不会影响运行。但这里推荐做做这一步是因为这样确保不同开发者在同一项目中使用的@sagaroute/react的版本是一致的，避免因版本不同导致的差异化情况

执行该步骤后需要重启Vscode才会生效

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

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

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

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 */用于标记路由列表注入的位置。关于这些注释的含义和路由模板文件的更多说明可看此处

4. 生成路由列表

@sagaorute/vscode-extension会监听页面文件目录里的文件，当更改的文件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,
};

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

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

可看以下效果图：

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

配置参数

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

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

注意❗：在该插件中，hooks的print.inject.after、print.write.before、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的output输出面板

.vscode/settings.json中的Sagaroute设定

你可以在.vscode/settings.json中设置sagaroute.working变量，以决定Sagaroute是否开启监听路由文件目录的变化以动态生成约定式路由列表，如下所示：

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

状态栏

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

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

高级特性

路由路径智能拼写

你可以在项目中通过键入"//"，sagaroute插件会提供所有所有路由的路径提示，如下所示：

选择后，"//"会被替换成所选择的路由路径

注意：在vscode项目首次打开时，要先做保存操作或者强制Sagaroute: routing后，才会有开启路由路径智能拼写

支持批量生成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命令