sagaroute-vscode

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

介绍

sagaroute-vscode是一款基于@sagaroute/react开发的约定式路由管理插件，它能监听文件变化以快速更新路由列表，且会根据路由列表提供快捷提示路由信息和快速定位路由页面的交互优化。运行效果可看以下展示：

特点

• 🌴 泛用性: 生成的约定式路由列表遵循ES6 Module格式，适用于任何开发环境
• 🎯 路由提示: 支持快速选择路由和查看路由组件信息
• 🚀 快速稳定: 合理利用缓存机制，使第二次的生成速度更快。若生成结果与上次相同，则不会更改路由模板文件
• 📇 样式一致: 生成路由列表保存后会自动触发代码风格约束插件的格式化(如prettier、eslint，取决于vscode安装了哪些插件)
• 📲 快捷定位: 支持快速打开url对应的页面文件

使用

1. 安装插件

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

下载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. 生成路由列表

@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,
  ErrorBoundary: ErrorBoundary,
};

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

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

可看以下效果图：

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

配置参数

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

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

注意❗：在该插件中，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的output输出面板
• Sagaroute: parse: 用于根据url快速定位文件，详情请看高级特性-通过url快速定位文件

.vscode/settings.json中的Sagaroute设定

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

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

状态栏

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

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

高级特性

快捷选择路由

你可以在项目中通过键入快捷键"//"调出所有可选路由，如下所示：

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

其中可选项会展示以下信息：

1. 路由对应的文件路径链接
2. 路由对应的文件中的默认导出组件的注释（如果存在）

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

快捷查看路由对应的文件信息

你可以通过鼠标停留路由字符串查看路由信息，此时路由信息会以悬浮冒泡的形式展示，如下所示：

所展示路由信息的内容与快捷选择路由的一致。若该路由字符串不存在能与之匹配的路由，则会显示以下信息：

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

支持通过url快速定位文件

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

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

注意: 在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命令