@tker-react/layout 0.2.13 → 0.2.15

package/README.md

@@ -3,8 +3,9 @@
 React 后台管理布局框架，提供菜单、面包屑、标签页、侧边栏等布局能力。
 
 - **无内置 adapter**：不依赖特定 UI 库，所有 UI 渲染由使用者通过 adapter 组件控制
-- **React Context 共享状态**：`<Layout>` 内置 Provider，通过 `useLayout()` 管理状态
-- **路由解耦**：不直接依赖路由库，通过 `setNavigateAdapter` 和 `setActivePath` 与路由层对接
+- **React Context 共享状态**：`<Layout>` 内置 Provider
+- **路由解耦**：不直接依赖路由库，通过 `setNavigateAdapter` 和 `<Layout>` 的 `activePath`/`activeFullPath` props 与路由层对接
+- **细粒度重渲染**：`activePath` 通过独立 context 传播，路由变化时仅菜单、面包屑、标签页重渲染，`<Outlet />` 不受影响
 
 ## 安装
 
@@ -26,59 +27,66 @@ import "@tker-react/layout/layout.css";
 
 ```tsx
 // layouts/AppLayout.tsx
-import { Layout, useLayout } from "@tker-react/layout";
-import { Outlet, useRouter, useRouterState } from "@tanstack/react-router";
-import { useLayoutEffect } from "react";
+import {
+    Layout,
+    setMenus,
+    setMenuAdapter,
+    setTabAdapter,
+    setBreadcrumbAdapter,
+    setLogoAdapter,
+    setToolbarAdapter,
+    setUserAvatarAdapter,
+    setHomePath,
+    setNavigateAdapter,
+} from "@tker-react/layout";
+import { Outlet, useRouterState } from "@tanstack/react-router";
+import { useMemo } from "react";
+
+// adapter 组件和菜单数据
+import MenuAdapter from "../adapters/MenuAdapter";
+import TabAdapter from "../adapters/TabAdapter";
+import BreadcrumbAdapter from "../adapters/BreadcrumbAdapter";
+import LogoAdapter from "../adapters/LogoAdapter";
+import ToolbarAdapter from "../adapters/ToolbarAdapter";
+import UserAvatarAdapter from "../adapters/UserAvatarAdapter";
+import { router } from "../router";
+
+// -- 静态配置：模块顶层调用即可 --
+setMenuAdapter(MenuAdapter);
+setTabAdapter(TabAdapter);
+setBreadcrumbAdapter(BreadcrumbAdapter);
+setLogoAdapter(LogoAdapter);
+setToolbarAdapter(ToolbarAdapter);
+setUserAvatarAdapter(UserAvatarAdapter);
+setHomePath("/dashboard");
+setNavigateAdapter((path) => router.navigate({ to: path }));
+setMenus([
+    { path: "/dashboard", title: "仪表盘" },
+    {
+        path: "/users",
+        title: "用户管理",
+        children: [
+            { path: "/users/list", title: "用户列表" },
+            { path: "/users/detail", title: "用户详情" },
+        ],
+    },
+]);
 
 export function AppLayout() {
-    return (
-        <Layout>
-            <SetupLayout />
-            <Outlet />
-        </Layout>
-    );
-}
-
-function SetupLayout() {
-    const layout = useLayout();
-    const router = useRouter();
     const pathname = useRouterState({ select: (s) => s.location.pathname });
     const search = useRouterState({ select: (s) => s.location.searchStr });
 
-    // adapter 注册和菜单设置必须在 useLayoutEffect 中调用
-    useLayoutEffect(() => {
-        layout.setMenuAdapter(MenuAdapter);
-        layout.setBreadcrumbAdapter(BreadcrumbAdapter);
-        layout.setTabAdapter(TabAdapter);
-        layout.setLogoAdapter(LogoAdapter);
-        layout.setToolbarAdapter(ToolbarAdapter);
-        layout.setUserAvatarAdapter(UserAvatarAdapter);
-        layout.setMenus([
-            { path: "/dashboard", title: "仪表盘" },
-            {
-                path: "/users",
-                title: "用户管理",
-                children: [
-                    { path: "/users", title: "用户列表" },
-                    { path: "/users/detail", title: "用户详情" },
-                ],
-            },
-        ]);
-        layout.setHomePath("/dashboard");
-    }, []);
-
-    // setNavigateAdapter 存储 ref，可以直接在 render 中调用
-    layout.setNavigateAdapter((path) => router.navigate({ to: path }));
-
-    useLayoutEffect(() => {
-        layout.setActivePath(pathname, pathname + search);
-    }, [pathname, search]);
-
-    return null;
+    const outlet = useMemo(() => <Outlet />, []);
+
+    return (
+        <Layout activeFullPath={pathname + search} activePath={pathname}>
+            {outlet}
+        </Layout>
+    );
 }
 ```
 
-> **注意**：`setXxxAdapter`、`setMenus` 等方法内部会调用 `setState`，必须在 `useLayoutEffect`（或 `useEffect`）中调用，不能在 render 期间直接调用，否则 React 会报 "Cannot update a component while rendering" 错误。`setNavigateAdapter` 只写 ref，可以在 render 中直接调用。
+> **注意**：adapter、菜单等静态配置在模块顶层调用一次即可（只写 module 变量）。`activePath`/`activeFullPath` 通过 props 传入 `<Layout>`。`<Outlet />` 用 `useMemo` 稳定引用，配合 `LayoutInner` 的 `React.memo` 避免路由变化时 `Outlet` 被 Layout 层牵连重渲染。
 
 ### 2. 定义路由并挂载
 
@@ -429,62 +437,65 @@ function UserAvatarAdapter({ onSettings, onLogout }: UserAvatarAdapterProps) {
 
 ## 使用不同路由库
 
-以下展示 `SetupLayout` 组件中路由同步部分的写法。
+静态配置（adapter、菜单）在模块顶层调用不变。以下展示各路由器 `activePath` 的对接方式。
 
 ### TanStack Router
 
 ```tsx
-// SetupLayout 中的路由同步部分
-const router = useRouter();
+// AppLayout 中的路由同步部分
+setNavigateAdapter((path) => router.navigate({ to: path }));
+
 const pathname = useRouterState({ select: (s) => s.location.pathname });
 const search = useRouterState({ select: (s) => s.location.searchStr });
 
-layout.setNavigateAdapter((path) => router.navigate({ to: path }));
-
-useLayoutEffect(() => {
-    layout.setActivePath(pathname, pathname + search);
-}, [pathname, search]);
+return (
+    <Layout activeFullPath={pathname + search} activePath={pathname}>
+        {outlet}
+    </Layout>
+);
 ```
 
 ### React Router v6+
 
 ```tsx
-// SetupLayout 中的路由同步部分
-const location = useLocation();
-const navigate = useNavigate();
+// AppLayout 中的路由同步部分
+setNavigateAdapter((path) => navigate(path));
 
-layout.setNavigateAdapter((path) => navigate(path));
+const location = useLocation();
 
-useLayoutEffect(() => {
-    layout.setActivePath(location.pathname, location.pathname + location.search);
-}, [location.pathname, location.search]);
+return (
+    <Layout activeFullPath={location.pathname + location.search} activePath={location.pathname}>
+        {outlet}
+    </Layout>
+);
 ```
 
 ### Next.js App Router
 
 ```tsx
-// SetupLayout 中的路由同步部分
+// AppLayout 中的路由同步部分
+setNavigateAdapter((path) => router.push(path));
+
 const pathname = usePathname();
 const searchParams = useSearchParams();
-const router = useRouter();
-
-layout.setNavigateAdapter((path) => router.push(path));
-
 const fullPath = pathname + (searchParams.toString() ? `?${searchParams}` : "");
 
-useLayoutEffect(() => {
-    layout.setActivePath(pathname, fullPath);
-}, [pathname, fullPath]);
+return (
+    <Layout activeFullPath={fullPath} activePath={pathname}>
+        {outlet}
+    </Layout>
+);
 ```
 
 ## API
 
-### `useLayout()`
+### 模块级 setter
+
+所有配置通过模块级 setter 设置，在 import 阶段调用即可（不需要 hook），内部存储为 module 变量。
 
-| 方法 | 说明 |
+| 函数 | 说明 |
 |------|------|
 | `setMenus(data)` | 设置菜单数据 |
-| `setActivePath(path, fullPath?)` | 设置当前激活路径，自动触发面包屑更新和标签页打开 |
 | `setMenuAdapter(component)` | 注册菜单适配器组件 |
 | `setTabAdapter(component)` | 注册标签页适配器组件 |
 | `setBreadcrumbAdapter(component)` | 注册面包屑适配器组件 |
@@ -492,11 +503,23 @@ useLayoutEffect(() => {
 | `setToolbarAdapter(component)` | 注册工具栏适配器组件 |
 | `setUserAvatarAdapter(component)` | 注册用户头像适配器组件 |
 | `setNavigateAdapter(fn)` | 设置导航回调，Layout 内部点击菜单/tab/面包屑时调用 |
-| `toggleCollapse()` | 切换侧边栏折叠 |
-| `setLayoutMode(mode)` | 设置布局模式：`"side-menu"` 或 `"top-menu"` |
+| `setLayoutMode(mode)` | 设置布局模式：`"side-menu"` 或 `"top-menu"`，默认 `"side-menu"` |
 | `setHomePath(path)` | 设置首页路径，首页 tab 固定在最左侧 |
 | `setMaxTabs(n)` | 设置最大标签页数量，超出后关闭最早的 |
-| `getFullPath(path)` | 根据菜单 path 获取存储的完整路径 |
+| `setExpandedWidth(width)` | 侧边栏展开宽度，默认 `"200px"` |
+| `setCollapsedWidth(width)` | 侧边栏折叠宽度，默认 `"64px"` |
+
+### 组件
+
+| 组件 | Props | 说明 |
+|------|-------|------|
+| `<Layout>` | `children`, `activePath?`, `activeFullPath?` | 布局容器，内置所有 Provider。`activePath` 为当前路由路径，`activeFullPath` 为含 query string 的完整路径 |
+
+### Hook
+
+| Hook | 说明 |
+|------|------|
+| `useActivePathContext()` | 获取当前 activePath，通常仅在自定义 adapter 时使用 |
 
 ### Adapter 组件 Props
 

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import * as react from 'react';
-import { ReactNode, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
 
 interface LayoutProps {
     children?: ReactNode;
+    activePath?: string;
+    activeFullPath?: string;
 }
-declare const Layout: react.MemoExoticComponent<({ children }: LayoutProps) => react_jsx_runtime.JSX.Element>;
+declare function Layout({ children, ...props }: LayoutProps): react_jsx_runtime.JSX.Element;
 
 interface BreadcrumbItem {
     path: string;
@@ -73,8 +74,10 @@ interface LayoutAdapters {
 
 interface LayoutProviderProps {
     children?: ReactNode;
+    activePath?: string;
+    activeFullPath?: string;
 }
-declare function LayoutProvider({ children }: LayoutProviderProps): react_jsx_runtime.JSX.Element;
+declare function LayoutProvider({ children, activePath, activeFullPath, }: LayoutProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function setMenus(data: MenuItem[]): void;
 declare function setMenuAdapter(c: ComponentType<MenuAdapterProps>): void;
@@ -89,7 +92,6 @@ declare function setLayoutMode(mode: "side-menu" | "top-menu"): void;
 declare function setExpandedWidth(width: string): void;
 declare function setCollapsedWidth(width: string): void;
 declare function setNavigateAdapter(fn: (path: string) => void): void;
-declare function setActivePath(path: string, fullPath?: string): void;
 
-export { Layout, LayoutProvider, setActivePath, setBreadcrumbAdapter, setCollapsedWidth, setExpandedWidth, setHomePath, setLayoutMode, setLogoAdapter, setMaxTabs, setMenuAdapter, setMenus, setNavigateAdapter, setTabAdapter, setToolbarAdapter, setUserAvatarAdapter };
+export { Layout, LayoutProvider, setBreadcrumbAdapter, setCollapsedWidth, setExpandedWidth, setHomePath, setLayoutMode, setLogoAdapter, setMaxTabs, setMenuAdapter, setMenus, setNavigateAdapter, setTabAdapter, setToolbarAdapter, setUserAvatarAdapter };
 export type { BreadcrumbAdapterProps, BreadcrumbItem, LayoutAdapters, LogoAdapterProps, MenuAdapterProps, MenuItem, TabAdapterProps, TabItem, UserAvatarAdapterProps };

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import * as react from 'react';
-import { ReactNode, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
 
 interface LayoutProps {
     children?: ReactNode;
+    activePath?: string;
+    activeFullPath?: string;
 }
-declare const Layout: react.MemoExoticComponent<({ children }: LayoutProps) => react_jsx_runtime.JSX.Element>;
+declare function Layout({ children, ...props }: LayoutProps): react_jsx_runtime.JSX.Element;
 
 interface BreadcrumbItem {
     path: string;
@@ -73,8 +74,10 @@ interface LayoutAdapters {
 
 interface LayoutProviderProps {
     children?: ReactNode;
+    activePath?: string;
+    activeFullPath?: string;
 }
-declare function LayoutProvider({ children }: LayoutProviderProps): react_jsx_runtime.JSX.Element;
+declare function LayoutProvider({ children, activePath, activeFullPath, }: LayoutProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function setMenus(data: MenuItem[]): void;
 declare function setMenuAdapter(c: ComponentType<MenuAdapterProps>): void;
@@ -89,7 +92,6 @@ declare function setLayoutMode(mode: "side-menu" | "top-menu"): void;
 declare function setExpandedWidth(width: string): void;
 declare function setCollapsedWidth(width: string): void;
 declare function setNavigateAdapter(fn: (path: string) => void): void;
-declare function setActivePath(path: string, fullPath?: string): void;
 
-export { Layout, LayoutProvider, setActivePath, setBreadcrumbAdapter, setCollapsedWidth, setExpandedWidth, setHomePath, setLayoutMode, setLogoAdapter, setMaxTabs, setMenuAdapter, setMenus, setNavigateAdapter, setTabAdapter, setToolbarAdapter, setUserAvatarAdapter };
+export { Layout, LayoutProvider, setBreadcrumbAdapter, setCollapsedWidth, setExpandedWidth, setHomePath, setLayoutMode, setLogoAdapter, setMaxTabs, setMenuAdapter, setMenus, setNavigateAdapter, setTabAdapter, setToolbarAdapter, setUserAvatarAdapter };
 export type { BreadcrumbAdapterProps, BreadcrumbItem, LayoutAdapters, LogoAdapterProps, MenuAdapterProps, MenuItem, TabAdapterProps, TabItem, UserAvatarAdapterProps };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import "./layout.css";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useRef, useCallback, useMemo, useState, useSyncExternalStore, createContext, useContext, memo, useEffect } from 'react';
+import { useRef, useCallback, useMemo, useState, useEffect, createContext, useContext, memo } from 'react';
 
 function findMenuItemByPath(menuData, path) {
   for (const item of menuData) {
@@ -112,28 +112,6 @@ function consumeLayoutConfig() {
     navigateAdapter: _navigateAdapter
   };
 }
-let _activePath = "";
-const _pathParamsMap = /* @__PURE__ */ new Map();
-let _activePathListeners = [];
-function setActivePath(path, fullPath) {
-  _activePath = path;
-  if (fullPath && fullPath !== path) {
-    _pathParamsMap.set(path, fullPath);
-  }
-  _activePathListeners.forEach((l) => l());
-}
-function subscribeActivePath(listener) {
-  _activePathListeners.push(listener);
-  return () => {
-    _activePathListeners = _activePathListeners.filter((l) => l !== listener);
-  };
-}
-function getActivePathSnapshot() {
-  return _activePath;
-}
-function getFullPathByActivePath(path) {
-  return _pathParamsMap.get(path) || path;
-}
 
 const LayoutContext = createContext(null);
 const LayoutInteractionContext = createContext(null);
@@ -157,7 +135,11 @@ const ActivePathContext = createContext("");
 function useActivePathContext() {
   return useContext(ActivePathContext);
 }
-function LayoutProvider({ children }) {
+function LayoutProvider({
+  children,
+  activePath = "",
+  activeFullPath
+}) {
   const config = consumeLayoutConfig();
   const navigateRef = useRef(null);
   navigateRef.current = config.navigateAdapter;
@@ -196,7 +178,12 @@ function LayoutProvider({ children }) {
   menuDataRef.current = config.menus;
   const layoutModeRef = useRef(config.layoutMode);
   layoutModeRef.current = config.layoutMode;
-  const activePath = useSyncExternalStore(subscribeActivePath, getActivePathSnapshot);
+  const pathParamsMap = useRef(/* @__PURE__ */ new Map());
+  useEffect(() => {
+    if (activeFullPath && activeFullPath !== activePath) {
+      pathParamsMap.current.set(activePath, activeFullPath);
+    }
+  }, [activePath, activeFullPath]);
   const toggleMenuOpen = useCallback((path, forceOpen) => {
     setOpenKeys((prev) => {
       const next = new Set(prev);
@@ -227,7 +214,7 @@ function LayoutProvider({ children }) {
         toggleMenuOpen(path);
       }
     } else {
-      const fullPath = getFullPathByActivePath(path);
+      const fullPath = pathParamsMap.current.get(path) || path;
       if (window.location.pathname + window.location.search !== fullPath) {
         navigateRef.current?.(fullPath);
       }
@@ -244,7 +231,7 @@ function LayoutProvider({ children }) {
     setCollapsedState(nextCollapsed);
   }, []);
   const getFullPath = useCallback(
-    (path) => getFullPathByActivePath(path),
+    (path) => pathParamsMap.current.get(path) || path,
     []
   );
   const isConcretePage = useCallback(
@@ -622,8 +609,8 @@ const LayoutInner = memo(function LayoutInner2({ children }) {
     ] })
   ] });
 });
-const Layout = memo(function Layout2({ children }) {
-  return /* @__PURE__ */ jsx(LayoutProvider, { children: /* @__PURE__ */ jsx(LayoutInner, { children }) });
-});
+function Layout({ children, ...props }) {
+  return /* @__PURE__ */ jsx(LayoutProvider, { ...props, children: /* @__PURE__ */ jsx(LayoutInner, { children }) });
+}
 
-export { Layout, LayoutProvider, setActivePath, setBreadcrumbAdapter, setCollapsedWidth, setExpandedWidth, setHomePath, setLayoutMode, setLogoAdapter, setMaxTabs, setMenuAdapter, setMenus, setNavigateAdapter, setTabAdapter, setToolbarAdapter, setUserAvatarAdapter };
+export { Layout, LayoutProvider, setBreadcrumbAdapter, setCollapsedWidth, setExpandedWidth, setHomePath, setLayoutMode, setLogoAdapter, setMaxTabs, setMenuAdapter, setMenus, setNavigateAdapter, setTabAdapter, setToolbarAdapter, setUserAvatarAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tker-react/layout",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "private": false,
   "license": "MIT",
   "type": "module",