create-ssnode-cli 0.2.6 → 0.2.7

package/templates/web/src/layouts/components/PageTabs/usePageTabs.ts

@@ -0,0 +1,224 @@
+/*
+ * Author  Murphy.xie
+ * Date  2026-10-29 18:24:37
+ * LastEditors  Murphy.xie
+ * LastEditTime  2026-11-04 09:55:15
+ * Description
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import type { RefObject } from 'react';
+import type { KeepAliveRef } from 'keepalive-for-react';
+import RouterConfig, { getRouteByPathName } from '../../../../config/router.config';
+
+/**
+ * 多页签数据模型(《后台多页签KeepAlive方案》§3.4)
+ */
+export interface PageTabItem {
+  /** 页签唯一键 = pathname,与 KeepAlive 缓存键同源 */
+  key: string;
+  /** 页签标题(路由配置 name) */
+  title: string;
+  /** 切回该页签时要还原的完整地址(search 系页面状态真源,必须带回) */
+  location: { pathname: string; search: string };
+  /**
+   * 最近一次激活时间戳。2026-10-29 排序权下放用户(拖拽调序 + 新签不再置顶)后,
+   * 视觉顺序不再表达访问新旧,超限淘汰改为按本字段取 LRU 最旧,与视觉顺序解耦
+   */
+  lastActiveAt: number;
+}
+
+/** 页签/缓存上限:超出按 lastActiveAt 淘汰 LRU 最旧(KeepAlive max 同值) */
+export const MAX_TABS = 20;
+/**
+ * 不建页签的路径:与 Background 布局 KeepAlive exclude 同源。`/background` 是布局基座路径,
+ * 经其进入会先以 pathname='/background' 渲染一帧 <Navigate to='/background/page-data'>
+ * (菜单树首项 { path:'/', redirect:'/page-data' } 的 fullPath 落点即 /background)。该帧非真实页面,
+ * 不应建页签(否则多出一个「后台管理系统」幽灵签),与旧 TabBar 按菜单树过滤(redirect 子项无 name)
+ * 不建签的口径等价。改 KeepAlive exclude 时此处同步。
+ */
+const NO_TAB_PATHS = ['/background'];
+
+/**
+ * 取路由名做页签标题:路由链末节点 name,兜底「未命名」。
+ * hideInMenu 页(智能助手/消息中心)也有 name,天然覆盖。
+ * getRouteByPathName 只做字面量全等,参数路由(./:id 等)须按段通配回退匹配,
+ * 否则详情类深链(/background/assessment/3)全落「未命名」。
+ */
+const resolveTabTitle = (pathname: string): string => {
+  const { routes } = getRouteByPathName(pathname);
+  if (routes.length > 0) return routes[routes.length - 1]?.name || '未命名';
+  // 段数一致 + :param 段当通配符,命中末节点即取其 name
+  const segments = pathname.split('/').filter(Boolean);
+  const matchParamRoute = (routeList: typeof RouterConfig): string | null =>
+    routeList.reduce((found, route) => {
+      if (found) return found;
+      const routeSegments = (route.fullPath || '').split('/').filter(Boolean);
+      const hit =
+        routeSegments.length === segments.length &&
+        routeSegments.every(
+          (seg, i) => (seg.startsWith(':') && segments[i]) || seg === segments[i]
+        );
+      if (hit && route.name) return route.name;
+      return route.children ? matchParamRoute(route.children) : null;
+    }, null);
+  return matchParamRoute(RouterConfig) || '未命名';
+};
+
+const makeTab = (pathname: string, search: string): PageTabItem => ({
+  key: pathname,
+  title: resolveTabTitle(pathname),
+  location: { pathname, search },
+  lastActiveAt: Date.now()
+});
+
+/**
+ * LRU 淘汰:剔除 lastActiveAt 最小且非当前激活的页签(当前签恒为最新,不会被误伤)。
+ * 只动页签数组(UI 数据),缓存仍交 KeepAlive max 自管 —— 与原「删最右」等价,
+ * 但不再要求「最右 = 最久未访问」这一已退役的前置假设。
+ */
+const evictLeastRecent = (list: PageTabItem[], activeKey: string): PageTabItem[] => {
+  let victimIdx = -1;
+  let minAt = Infinity;
+  list.forEach((t, i) => {
+    if (t.key !== activeKey && t.lastActiveAt < minAt) {
+      minAt = t.lastActiveAt;
+      victimIdx = i;
+    }
+  });
+  if (victimIdx === -1) return list;
+  const copy = [...list];
+  copy.splice(victimIdx, 1);
+  return copy;
+};
+
+/**
+ * 多页签状态与操作(《后台多页签KeepAlive方案》)
+ *
+ * 关键口径:
+ * 1. **activeKey 不落 state,恒由 location.pathname 派生** —— 页签关闭(destroy 缓存)与
+ *    navigate(激活邻页)若分两个 commit,KeepAlive 会对已销毁的 pathname 新建幽灵缓存节点
+ *    (挂一份邻页组件实例泄内存);闭包内同步 navigate + destroy 由 URL 派生键原子兜死。
+ * 2. **页签数组只是 UI 数据**,允许滞后一个 commit,不参与缓存键计算。
+ *    2026-10-29 起**顺序由用户掌控**:新签 append 最右、激活不挪位(原 activeToFront 置顶退役),
+ *    顺序只在拖拽调序(moveTab)与超限淘汰时变化;溢出视口的新签可见性由 PageTabs 滚入兜底。
+ * 3. **关闭/刷新等缓存操作全部走 aliveRef**(destroy / refresh),不自研缓存管理。
+ *
+ * @param aliveRef KeepAlive 的命令通道(useKeepAliveRef() 产物,由调用方持有)
+ * @param homePath 关闭最后一个页签 / 全部关闭时的回落主页,默认 /background/page-data
+ *   (本模板后台首个菜单叶「页面管理」,即 Background 索引路由 redirect:'/page-data' 的落点)。
+ *   回落式兜底,不预置常驻首页签;首个签 = 落地页,全关完回 homePath 由上方 effect 重建其签。
+ */
+export default function usePageTabs(
+  aliveRef: RefObject<KeepAliveRef>,
+  homePath = '/background/page-data'
+) {
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  // 页签条初始:仅当前页(不预置常驻首页签);/background 基座帧不建签(NO_TAB_PATHS)
+  const [tabs, setTabs] = useState<PageTabItem[]>(() =>
+    NO_TAB_PATHS.includes(location.pathname) ? [] : [makeTab(location.pathname, location.search)]
+  );
+
+  // 激活键:URL 唯一真源派生,不用独立 state(见头部口径 1)
+  const activeKey = location.pathname;
+
+  // 路由变化 → 开新签(append 最右)/ 激活已开签并同步最新 search(search 变化不另开签);
+  // 激活只刷新 lastActiveAt(超限 LRU 淘汰依据),不挪位 —— 点页签/菜单/深链三入口口径一致
+  useEffect(() => {
+    const { pathname, search } = location;
+    if (NO_TAB_PATHS.includes(pathname)) return;
+    setTabs((prev) => {
+      const idx = prev.findIndex((t) => t.key === pathname);
+      if (idx === -1) {
+        const next = [...prev, makeTab(pathname, search)];
+        // 超上限淘汰:lastActiveAt 最旧者(新签即当前签,恒不被淘汰)
+        return next.length > MAX_TABS ? evictLeastRecent(next, pathname) : next;
+      }
+      const hit = prev[idx];
+      const copy = [...prev];
+      copy[idx] = { ...hit, location: { pathname, search }, lastActiveAt: Date.now() };
+      return copy;
+    });
+  }, [location.pathname, location.search]);
+
+  /** 点击页签:还原完整地址(pathname+search) */
+  const activeTab = useCallback(
+    (tab: PageTabItem) => {
+      if (tab.key === activeKey && tab.location.search === location.search) return;
+      navigate({ pathname: tab.location.pathname, search: tab.location.search });
+    },
+    [navigate, activeKey, location.search]
+  );
+
+  /**
+   * 关闭页签:删签 + 销毁缓存;关的是当前页签则跳相邻(顺序由用户掌控后,
+   * 数组相邻位即视觉相邻,不再按「次新访问」挑选);无相邻(关最后一个)回落 homePath。
+   * 页签条允许瞬时空(回落导航触发上方 effect 重建 homePath 签),与旧 TabBar 行为一致。
+   */
+  const closeTab = useCallback(
+    (tab: PageTabItem) => {
+      const idx = tabs.findIndex((t) => t.key === tab.key);
+      if (idx === -1) return;
+      const neighbor = tabs[idx - 1] || tabs[idx + 1];
+      setTabs((prev) => prev.filter((t) => t.key !== tab.key));
+      aliveRef.current?.destroy(tab.key);
+      if (tab.key === activeKey) {
+        navigate(
+          neighbor
+            ? { pathname: neighbor.location.pathname, search: neighbor.location.search }
+            : homePath
+        );
+      }
+    },
+    [tabs, activeKey, navigate, aliveRef, homePath]
+  );
+
+  /** 关闭其他:只留当前签,其余连缓存一起销毁 */
+  const closeOthers = useCallback(() => {
+    const victims = tabs.filter((t) => t.key !== activeKey).map((t) => t.key);
+    aliveRef.current?.destroy(victims);
+    setTabs((prev) => prev.filter((t) => t.key === activeKey));
+  }, [tabs, activeKey, aliveRef]);
+
+  /** 全部关闭:清光其他签连缓存,回 homePath 兜底主页(homePath 签/缓存保留,未开则由 effect 重建) */
+  const closeAll = useCallback(() => {
+    const victims = tabs.filter((t) => t.key !== homePath).map((t) => t.key);
+    aliveRef.current?.destroy(victims);
+    setTabs([makeTab(homePath, '')]);
+    if (activeKey !== homePath) navigate(homePath);
+  }, [tabs, activeKey, navigate, aliveRef, homePath]);
+
+  /** 刷新当前页签:renderCount+1 强制重建组件(仅当前签可刷) */
+  const refreshTab = useCallback(() => {
+    aliveRef.current?.refresh(activeKey);
+  }, [activeKey, aliveRef]);
+
+  /**
+   * 拖拽调序(PageTabs onTabReorder 载荷):把 fromKey 页签挪到 overKey 页签当前所在位。
+   * 顺序是纯 UI 数据(口径 2),不触发任何缓存操作;lastActiveAt 不动,淘汰依据不受拖拽影响
+   */
+  const moveTab = useCallback((fromKey: string, overKey: string) => {
+    setTabs((prev) => {
+      const fromIdx = prev.findIndex((t) => t.key === fromKey);
+      const overIdx = prev.findIndex((t) => t.key === overKey);
+      if (fromIdx === -1 || overIdx === -1 || fromIdx === overIdx) return prev;
+      const copy = [...prev];
+      const [moved] = copy.splice(fromIdx, 1);
+      copy.splice(overIdx, 0, moved);
+      return copy;
+    });
+  }, []);
+
+  return {
+    tabs,
+    activeKey,
+    activeTab,
+    closeTab,
+    closeOthers,
+    closeAll,
+    refreshTab,
+    moveTab
+  };
+}