[RFC] 045 - App Layout 重构

[canisminor1990]

目标与背景

目标

• 解决当前内容和布局文件过于分散的问题，利用 NextJS 平行路由，将 Layout 按功能区划分为 Slot， 增加目录结构可读性与组织清晰度
• 提升 Layout RSC 利用率，将 use client 尽可能原子化
• 桌面度自适应过程中取消降级为移动端，避免造成交互模态变化过大

Note

平行路由介绍: https://nextjs.org/docs/app/building-your-application/routing/parallel-routes

背景

目前 LobeChat 文件夹目录架构如下：

market
├── (desktop)
│   ├──features                    # Market Mobile Features  
│   │  └── detail                  # Mobile Detail Features
│   └── index.tsx                  # Market Desktop Page           
├── (mobile)   
│   ├──features                    # Market Mobile Features
│   │  └── detail                  # Desktop Detail Features
│   └── index.tsx                  # Market Mobile Page   
├── _layout
│   ├── Mobile                     # Market Mobile Layout
│   │   └── detail.tsx             # Detail Sidebar Mobile Layout
│   └── Desktop                    # Market Desktop Layout
│       └── detail.tsx             # Detail Sidebar Desktop Layout         
├── features                
│   └── index.tsx                  # ShareContant
├── layout.tsx                     # Market Layout
└── page.tsx                       # Market Page

可以发现如果我想改动助手详情侧边栏，从文件目录上其实很难直观发现我需要去改哪些关联的地方

重构后：

market
├── @detail
│   ├── _layout
│   │   ├── Mobile          # Detail Sidebar Mobile Layout
│   │   └── Desktop         # Detail Sidebar Desktop Layout
│   ├── features            
│   │   └── index.tsx       # Detail Sidebar ShareContant
│   └── page.tsx            # Detail Sidebar
│ 
├── _layout
│   ├── Mobile              # Market Mobile Layout
│   └── Desktop             # Market Desktop Layout
├── features                
│   └── index.tsx           # Market ShareContant
├── layout.tsx              # Market Layout
└── page.tsx                # Market Page

布局示意

例如目前 LobeChat Market 页面的文件夹目录架构如下：

重构前	重构后

进展

• 将 chat / market / setting 等具有统一导航栏页面移动到虚拟路由 (main)
  • ♻️ refactor: move app page to the (main) layout group #2297
• 增加 Error 和 404 页面
  • 💄 style: add 404 and Error page #2299
• 一级布局
  • @nav ♻️ refactor: Move NavBar to @nav slot route #2306
• 二级布局重构
  • Chat ⚡️ perf: Refactor Chat Layout to improve performance #2339
  • Market ♻️ refactor: Refactor Market Layout #2320
  • Welcome ♻️ refactor: Refactor Welcome Layout #2314
  • Settings 💄 style: refactor setting Layout and improve setting design #2344
    • 弹窗拦截路由 ✨ feat: Add Settings Intercepting Routes #2346

[canisminor1990]

设置弹窗拦截路由

• PR: ✨ feat: Add Settings Intercepting Routes #2346

NextJS 文档介绍：https://nextjs.org/docs/app/building-your-application/routing/intercepting-routes

目标

• 桌面端使用 弹窗 开启设置面板全局设置和会话设置 (单页面）
• 移动端使 页面 展示 (多页面)

通用设置	角色设置

背景（目前遗留的社区问题）

• Conditionally intercept route vercel/next.js#49146

拦截路由无法受控，不能自由定义什么情况下开启拦截什么情况下关闭拦截，突破限制的方式只有通过 redirect 硬刷新

https://www.reddit.com/r/nextjs/comments/174m3xf/how_to_stop_intercepting_routes_for_some_specific/

"use server";
import { redirect } from "next/navigation";

export default async function redirectHard(uri: string) {
  redirect(uri);
}

Warning

但测试后发现在 ios 设别上响应很慢，有时候甚至无法响应

设计思路

当前的设计思路是通过路由进行受控，例如想实现 /settings 受控

• 使用弹窗拦截：/settings/modal?tab=common
• 不是用弹窗拦截：/settings/common

会话设置同理

• 使用弹窗拦截：/chat/settings/modal
• 不是用弹窗拦截：/chat/settings

文件结构示意

└── app
    ├── @modal
    │   └── (.)settings
    │       └── modal
    │           └── page.tsx  # 弹窗内容
    └── (main)
        └── settings
            └── modal
                └── page.tsx  # 拦截中如果硬刷新，Fallback 到非拦截路由

Fallback 路由示意: app/(main)/settings/modal/page.tsx

'use client';

import { useLayoutEffect } from 'react';
import urlJoin from 'url-join';

import { useQuery } from '@/hooks/useQuery';
import { useQueryRoute } from '@/hooks/useQueryRoute';
import { SettingsTabs } from '@/store/global/initialState';

/**
 * @description: Settings Modal (intercepting routes fallback when hard refresh)
 * @example: /settings/modal?tab=common => /settings/common
 */

const SettingsModalFallback = () => {
  const { tab = SettingsTabs.Common } = useQuery();
  const router = useQueryRoute();

  useLayoutEffect(() => {
    router.replace(urlJoin('/settings', tab as string), { query: { tab: '' } });
  }, []);

  return null;
};

export default SettingsModalFallback;

工具 hook

由于拦截判断条件比较复杂，包装为两个 hook 方法方便使用

打开设置面板：useOpenSettings

import { useOpenSettings } from '@/hooks/useInterceptingRoutes';

export const useOpenSettings = (tab: SettingsTabs = SettingsTabs.Common) => {
  const router = useQueryRoute();
  const mobile = useIsMobile();

  return useMemo(() => {
    if (mobile) {
      return () => router.push(urlJoin('/settings', tab));
    } else {
      // use Intercepting Routes on Desktop
      return () => router.push('/settings/modal', { query: { tab } });
    }
  }, [mobile, tab]);
};

打开角色设置面板：useOpenChatSettings

import { useOpenChatSettings} from '@/hooks/useInterceptingRoutes';

export const useOpenChatSettings = (
  isInbox?: boolean,
  tab: ChatSettingsTabs = ChatSettingsTabs.Meta,
) => {
  const globalSettings = useOpenSettings(SettingsTabs.Agent);
  const router = useQueryRoute();
  const mobile = useIsMobile();

  return useMemo(() => {
    if (isInbox) {
      useGlobalStore.setState({
        sidebarKey: SidebarTabKey.Setting,
      });
      return globalSettings;
    }
    if (mobile) {
      return () => router.push('/chat/settings');
    } else {
      // use Intercepting Routes on Desktop
      return () => router.push('/chat/settings/modal', { query: { tab } });
    }
  }, [globalSettings, mobile, isInbox, tab]);
};

Q&A

Q: 为什么不用 Modal 而用现在的方案，优点是什么，缺点是什么？

优点：

• 当唤起场景分散时，不需要每次都注入/全局注入组件，使用 Link 或者 router.push 就是唤起弹窗，比如设置的唤起目前横跨多个不同的路由页面，同时在 conversation 中也大量分散存在。
• 可以像正常路由一样使用 server 方法，如果用封装 Modal 实现，则每次都要把需要用的服务端参数进行传递。另一个角度就是和目前非拦截状态的设置页面兼容度高，几乎不需要改造。
• 不需要手动 dynamic 加载的问题，因为本来就是一个单独的路由

缺点

• 当多设备使用，或者有特殊场景需要选择性关闭/或者受控劫持时，目前没有特别良好的处理手段，如上文所示，一是需要隔离被劫持的路由，二是需要处理硬刷新的 Fallback
• 目前还是一种比较新的方案，不了解的开发者可能需要查阅官方文档才了解具体的命名规范和路由劫持规范

---

Q: 现在这个方案的缺点是否可以在未来基础设施迭代过程中优化掉？（是否等 next 升级或者支持特性，就可以把缺点干掉）

增加拦截受控的社区呼声目前也挺高，比如在 Link 或者 router.push 上增加开关控制是否劫持，或者通过 query 判断是否被劫持

• App Dir: Avoid intercepted route for hard navigated page vercel/next.js#51648
• Conditionally intercept route vercel/next.js#49146
• Parallel and intercepting routes: render any route within a modal? vercel/next.js#60354

如果相关特性能够被支持，整体项目结构会干净很多，不需要用子路由 xxx/modal 包裹也不需要手动处理硬刷新降级逻辑

└── app
    ├── @modal
    │   └── (.)settings
    │       └── page.tsx  # 弹窗内容
    └── (main)
        └── settings

---

Q: 对旧路由的影响？

没有任何影响，目前的拦截模式是 xxx/modal 老路由不会被拦截

---

Q: 如果这个方案在后续过程中存在问题，相应的迁移方案是什么？（改成 Modal 要做什么）

因为整体收拾的比较干净，所以几乎可以热插拔

• 删除 @modal >> 此时所有拦截都会失效
• 修改 useOpenSettings / useOpenChatSettings 中的逻辑，用 Modal 的话相当于做一个全局的 state 开关
• 把弹窗用正常 Modal 封装，全局 dynamic 注入，可能要检查下之前的 server 方法要替换为 client 方法
• 迁移完毕

[arvinxx]

目前遇到的一个问题： #2823

[arvinxx]

2025.01.21 callback:

1. 根据用户的普遍反馈，Intercepting Route 的响应很慢，因此于 ⚡️ perf: remove Intercepting Route to improve setting page performance #5218 移除设置页面的 Intercepting Route；
2. 之前跳转 Setting 页面慢的很重要的原因是没有用 Suspense 抢跑，导致 /settings 路由需要走完完整的 SSR 后才能返回响应（对应的好处就是打开就是完整 html）。通过在 /settings 目录下添加 loading.tsx 后即解决。