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

村上小树2023-11-05 22:56

📝 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. 在路由模板文件中用注释做标记注入

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

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

js 复制代码 
import React from "react";

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

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

js 复制代码 
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文件，其文件内容如下所示：

jsx 复制代码 
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,
};

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

jsx 复制代码 
{
  path:'user',
  element:<PagesUsers/>,
  caseSensitive: false,
  ErrorBoundary: ComponentsErrorBoundary
}

可看以下效果图：

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

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

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

js 复制代码 
[
  // 写法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还支持相对路径的路由智能提示。假设有以下场景：

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

jsx 复制代码 
[
  {
    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不会对带变量的模板字符串作诊断，例如：

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

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

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

路由悬浮显示组件信息

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

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

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

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

js 复制代码 
// 不会冒泡显示，因为无法判断其中的变量的值
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去设置高亮样式，如下所示：

js 复制代码 
{
  "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

相关推荐
莹雨潇潇8 分钟前
Docker 快速入门（Ubuntu版）
java·前端·docker·容器
Jiaberrr16 分钟前
Element UI教程：如何将Radio单选框的圆框改为方框
前端·javascript·vue.js·ui·elementui
Tiffany_Ho1 小时前
【TypeScript】知识点梳理（三）
前端·typescript
安冬的码畜日常2 小时前
【D3.js in Action 3 精译_029】3.5 给 D3 条形图加注图表标签（上）
开发语言·前端·javascript·信息可视化·数据可视化·d3.js
小白学习日记3 小时前
【复习】HTML常用标签＜table＞
前端·html
丁总学Java3 小时前
微信小程序-npm支持-如何使用npm包
前端·微信小程序·npm·node.js
yanlele3 小时前
前瞻 - 盘点 ES2025 已经定稿的语法规范
前端·javascript·代码规范
懒羊羊大王呀4 小时前
CSS——属性值计算
前端·css
DOKE4 小时前
VSCode终端：提升命令行使用体验
前端
热门推荐
01分享几个惊艳的 Three.js 个人站点02【经验分享】Ubuntu22.04安装微信(linux官方版)032024年高教社杯数学建模国赛C题超详细解题思路分析04组基轨迹建模 GBTM的介绍与实现（Stata 或 R）05安卓系列机型永久去除data分区加密 详细步骤解析06【2024数模国赛赛题思路公开】国赛B题思路丨附可运行代码丨无偿自提07CTF网络安全大赛简单的web抓包题目：HEADache08Ubuntu24.04安装中文输入法09【2024高教社杯全国大学生数学建模竞赛】B题 生产过程中的决策问题——解题思路 代码 论文10springer 在线投稿编译踩坑