[RFC] 103 - 桌面端拦截路由

[arvinxx]

背景概述

在做 #6878 时，我们期望在桌面端 settings 可以在独立窗口打开，但如果是在web里仍然跳转页面。这里需要的是在桌面端模式下的拦截路由逻辑，使得桌面端可以相对灵活地控制特定路由的处理方式。进而获得更好的用户体验。

本文档描述了这样一个全局路由拦截机制实现逻辑，该机制能够在用户尝试通过各种方式导航到特定路径（如/settings）时自动拦截请求，并在特定的独立窗口中打开相应内容，同时支持子路径处理。

设计目标

1. 无缝拦截用户导航

   • 捕获所有导航尝试，包括链接点击、编程导航和地址栏输入
   • 使拦截过程对用户和应用代码透明

2. 灵活的窗口管理

   • 基于拦截的路径打开或切换到指定的独立窗口
   • 正确处理窗口可见性和焦点

3. 子路径精确识别

   • 从拦截的URL中提取子路径
   • 在目标窗口中导航到对应的子路径内容

4. 扩展性设计

   • 支持动态配置拦截规则
   • 易于添加新的拦截路径和窗口类型

技术架构

LobeHub 桌面应用的路由拦截机制由三个主要部分组成：

1. 拦截器定义（渲染进程 - Preload）

在预加载脚本中设置DOM级别的拦截器，捕获:

• <a> 元素点击事件
• History API调用（pushState和replaceState）
• 可能的路由错误处理

// apps/desktop/src/preload/routeInterceptor.ts
export const setupRouteInterceptors = function () {
  // 拦截<a>标签点击
  document.addEventListener('click', async (e) => {
    const link = (e.target as HTMLElement).closest('a');
    if (link && shouldIntercept(link.href)) {
      e.preventDefault();
      await interceptRoute(url.pathname, 'link-click', link.href);
    }
  }, true);

  // 拦截history.pushState
  history.pushState = function () {
    const url = arguments[2];
    if (shouldIntercept(url)) {
      interceptRoute(parsedUrl.pathname, 'push-state', parsedUrl.href);
      return;
    }
    return Reflect.apply(originalPushState, this, arguments);
  };

  // 拦截history.replaceState
  // ...类似pushState的实现...
}

2. 拦截配置（共享配置）

定义哪些路径需要拦截及其对应的目标窗口：

// apps/desktop/src/common/routes.ts
export interface RouteInterceptConfig {
  description: string;    // 拦截规则描述
  enabled: boolean;       // 是否启用
  pathPrefix: string;     // 路径前缀（如'/settings'）
  targetWindow: string;   // 目标窗口标识符
  alwaysOpenNew?: boolean; // 是否总是打开新窗口
}

// 拦截路由配置列表
export const interceptRoutes: RouteInterceptConfig[] = [
  {
    description: '设置页面',
    enabled: true,
    pathPrefix: '/settings',
    targetWindow: 'settings',
  },
  {
    description: '开发者工具',
    enabled: true,
    pathPrefix: '/desktop/devtools',
    targetWindow: 'devtools',
  },
  // 可添加更多拦截规则
];

3. 主进程处理（Electron主进程）

处理来自渲染进程的拦截请求，并执行相应的窗口操作：

// apps/desktop/src/main/controllers/BrowserWindowsCtr.ts
export default class BrowserWindowsCtr extends ControllerModule {
  /**
   * 处理路由拦截请求
   */
  @ipcClientEvent('interceptRoute')
  async interceptRoute(params: InterceptRouteParams) {
    const { path, source } = params;
    
    // 查找匹配的路由配置
    const matchedRoute = findMatchingRoute(path);
    if (!matchedRoute) {
      return { intercepted: false, path, source };
    }
    
    // 处理拦截逻辑
    try {
      if (matchedRoute.targetWindow === BrowsersIdentifiers.settings) {
        const subPath = extractSubPath(path, matchedRoute.pathPrefix);
        await this.app.browserManager.showSettingsWindowWithTab(subPath);
        
        return {
          intercepted: true,
          path,
          source,
          subPath,
          targetWindow: matchedRoute.targetWindow,
        };
      } else {
        await this.openTargetWindow(matchedRoute.targetWindow as AppBrowsersIdentifiers);
        
        return {
          intercepted: true,
          path,
          source,
          targetWindow: matchedRoute.targetWindow,
        };
      }
    } catch (error) {
      console.error('[BrowserWindowsCtr] Error while processing route interception:', error);
      return {
        error: error.message,
        intercepted: false,
        path,
        source,
      };
    }
  }
}

工作流程

1. 用户触发导航

   • 用户点击链接、调用路由方法或直接修改URL

2. Preload脚本拦截

   • routeInterceptor.ts中的拦截器捕获导航尝试
   • 调用findMatchingRoute检查是否需要拦截

3. 发送IPC消息

   • 如需拦截，通过invoke('interceptRoute', ...)向主进程发送请求

4. 主进程处理

   • BrowserWindowsCtr.interceptRoute接收请求
   • 再次验证路径是否需要拦截
   • 提取子路径信息

5. 窗口管理

   • 通过browserManager打开对应窗口
   • 对于设置窗口，使用showSettingsWindowWithTab导航到子路径
   • 对于其他窗口，使用openTargetWindow打开并显示窗口

6. 返回结果

   • 向渲染进程返回处理结果

组件关系图

+------------------+       +------------------+       +------------------+
|                  |       |                  |       |                  |
|  渲染进程 (浏览器) |       |   Preload脚本    |       | 主进程 (Electron) |
|                  |       |                  |       |                  |
+--------+---------+       +--------+---------+       +--------+---------+
         |                          |                          |
         | 导航请求                  |                          |
         v                          |                          |
+------------------+                |                          |
|                  |                |                          |
|  DOM事件/History API |              |                          |
|                  |                |                          |
+--------+---------+                |                          |
         |                          |                          |
         | 触发                     |                          |
         v                          |                          |
+------------------+                |                          |
|                  |                |                          |
| setupRouteInterceptors|           |                          |
|                  |                |                          |
+--------+---------+                |                          |
         |                          |                          |
         | 拦截检查                  |                          |
         v                          |                          |
+------------------+                |                          |
|                  |                |                          |
| findMatchingRoute |               |                          |
|                  |                |                          |
+--------+---------+                |                          |
         |                          |                          |
         | 需要拦截                  |                          |
         v                          |                          |
+------------------+                |                          |
|                  +----------------+                          |
| interceptRoute   |  IPC调用                                  |
|                  +----------------+------------------------->|
+------------------+                |                          |
                                    |             +------------v-----------+
                                    |             |                        |
                                    |             | BrowserWindowsCtr      |
                                    |             | .interceptRoute        |
                                    |             |                        |
                                    |             +------------+-----------+
                                    |                          |
                                    |                          | 处理请求
                                    |                          v
                                    |             +------------+-----------+
                                    |             |                        |
                                    |             | BrowserManager         |
                                    |             | .showSettingsWindowWithTab|
                                    |             |                        |
                                    |             +------------+-----------+
                                    |                          |
                                    |                          | 窗口管理
                                    |                          v
                                    |             +------------+-----------+
                                    |             |                        |
                                    |             | Browser                |
                                    |             | .loadUrl/.show         |
                                    |             |                        |
                                    |             +------------+-----------+
                                    |                          |
                                    |                          | 返回结果
                                    |             +------------v-----------+
                                    |             |                        |
                                    |<------------+ IPC响应                |
                                    |             |                        |
                                    |             +------------------------+

拓展与配置

添加新的拦截路径

要添加新的拦截路径，只需在interceptRoutes配置中添加新项：

export const interceptRoutes: RouteInterceptConfig[] = [
  // 现有配置...
  
  // 新增拦截配置
  {
    description: '帮助中心',
    enabled: true,
    pathPrefix: '/help',
    targetWindow: 'help',
  },
];

新窗口定义

同时，需要在appBrowsers中定义新窗口的配置：

export const appBrowsers = {
  // 现有窗口...
  
  // 新增窗口配置
  help: {
    autoHideMenuBar: true,
    height: 700,
    identifier: 'help',
    minWidth: 500,
    path: '/help',
    titleBarStyle: 'hidden',
    vibrancy: 'under-window',
    width: 900,
  },
} satisfies Record<string, BrowserWindowOpts>;

总结

该路由拦截机制通过渲染进程拦截、共享配置和主进程处理的三层架构，实现了无缝的路由导航和窗口管理。该设计不仅能满足设置窗口的拦截需求，还为未来添加新的拦截规则和窗口类型提供了可扩展的框架。

通过这种方式，我们就能够为用户提供一个更像原生应用的体验，同时保持基于网页的界面灵活性和功能丰富性。这种混合模式可以作为现代桌面应用开发的最佳实践，在用户体验和开发效率之间取得良好的平衡。