@hsu-react/ui 2.0.2 → 2.2.0

package/es/layout/Header/index.d.ts

@@ -34,6 +34,14 @@ export interface HeaderProps {
     title?: React.ReactNode;
     /** 侧栏收起时用的短标题；不传则回落到 title */
     smallTitle?: React.ReactNode;
+    /**
+     * 是否显示语言切换。
+     *
+     * 只有中文一种文案的项目把它关掉——留着会给用户一个切了之后只有 antd 内建文案变化、
+     * 业务文案纹丝不动的开关，比没有更糟。关掉后 `Layout.I18n` 仍可照常用（日期、分页
+     * 这些 antd 内建文案还是要它）。
+     */
+    showLocale?: boolean;
 }
 declare const Header: React.FC<HeaderProps>;
 export default Header;

package/es/layout/Header/index.js

@@ -40,7 +40,9 @@ var Header = observer(function (props) {
     menu = props.menu,
     user = props.user,
     title = props.title,
-    smallTitle = props.smallTitle;
+    smallTitle = props.smallTitle,
+    _props$showLocale = props.showLocale,
+    showLocale = _props$showLocale === void 0 ? true : _props$showLocale;
   var layout = ThemeStore.layout,
     headerTheme = ThemeStore.headerTheme,
     appearance = ThemeStore.appearance,
@@ -118,7 +120,7 @@ var Header = observer(function (props) {
                 return setAppearance(v);
               }
             })]
-          }), /*#__PURE__*/_jsxs("div", {
+          }), showLocale && /*#__PURE__*/_jsxs("div", {
             className: styles.settingRow,
             children: [/*#__PURE__*/_jsx("span", {
               className: styles.settingLabel,

package/es/layout/NavTabBar/_hooks/useKeepTabs.d.ts

@@ -0,0 +1,18 @@
+import { TabType } from "..";
+/**
+ * 按业务规则在地址变化时收掉一批页签。
+ *
+ * 起因是消费方（writer-assistant）的一条规则：进出某部作品时，把上一部作品的所有页签
+ * 一起清掉——「一次只专注一部书」。这种规则依赖业务对 URL 的解读（哪一段是作品 id），
+ * 组件库不可能内建，但**收页签这件事本身**必须留在库里做：光从 openKeys 里删掉不够，
+ * 还要 `drop` 掉 react-activation 的缓存，否则组件树留在内存里，下次同名路由回来还会
+ * 复用旧实例。
+ *
+ * 所以对外只暴露一个判定函数，删除与丢缓存由这里统一执行。
+ *
+ * 判定按**当前地址**做，不需要消费方自己记「上一个是什么」：每次地址变化重新评估每个
+ * 页签「在现在这个位置还该不该留着」，语义更直白，也不会因为漏更新 ref 而出错。
+ */
+export declare const useKeepTabs: (shouldKeepTab: ((tab: TabType, info: {
+    pathname: string;
+}) => boolean) | undefined, setOpenkeys: React.Dispatch<React.SetStateAction<TabType[]>>) => void;

package/es/layout/NavTabBar/_hooks/useKeepTabs.js

@@ -0,0 +1,45 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+import { useAliveController } from "react-activation";
+/**
+ * 按业务规则在地址变化时收掉一批页签。
+ *
+ * 起因是消费方（writer-assistant）的一条规则：进出某部作品时，把上一部作品的所有页签
+ * 一起清掉——「一次只专注一部书」。这种规则依赖业务对 URL 的解读（哪一段是作品 id），
+ * 组件库不可能内建，但**收页签这件事本身**必须留在库里做：光从 openKeys 里删掉不够，
+ * 还要 `drop` 掉 react-activation 的缓存，否则组件树留在内存里，下次同名路由回来还会
+ * 复用旧实例。
+ *
+ * 所以对外只暴露一个判定函数，删除与丢缓存由这里统一执行。
+ *
+ * 判定按**当前地址**做，不需要消费方自己记「上一个是什么」：每次地址变化重新评估每个
+ * 页签「在现在这个位置还该不该留着」，语义更直白，也不会因为漏更新 ref 而出错。
+ */
+export var useKeepTabs = function useKeepTabs(shouldKeepTab, setOpenkeys) {
+  var _useLocation = useLocation(),
+    pathname = _useLocation.pathname;
+  var _useAliveController = useAliveController(),
+    drop = _useAliveController.drop;
+  useEffect(function () {
+    if (!shouldKeepTab) return;
+    setOpenkeys(function (prev) {
+      var kept = prev.filter(function (tab) {
+        return shouldKeepTab(tab, {
+          pathname: pathname
+        });
+      });
+      if (kept.length === prev.length) return prev;
+      prev.filter(function (tab) {
+        return !kept.includes(tab);
+      })
+      // 缓存是按不带 query 的路径存的
+      .forEach(function (tab) {
+        return drop(tab.key.split("?")[0] || "");
+      });
+      return kept;
+    });
+    // shouldKeepTab 多半是行内箭头函数，放进依赖会每次渲染都重跑。
+    // 这个 effect 的触发时机就是「地址变了」，按 pathname 走即可。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname]);
+};

package/es/layout/NavTabBar/index.d.ts

@@ -16,6 +16,27 @@ export interface NavTabBarProps {
     basePath?: string;
     /** 页签栏最前面的「刷新当前页」按钮 */
     showReload?: boolean;
+    /**
+     * 地址变化时决定每个页签还留不留。返回 false 的会被关掉，并连同 react-activation 的
+     * 缓存一起丢弃。
+     *
+     * 给的是「在当前地址下这个页签还该不该在」这种判定，不需要自己记上一个位置是什么。
+     *
+     * @example 一次只专注一部作品：进入另一部书时，把上一部的页签全收掉
+     * ```ts
+     * const workId = (p: string) => p.match(/\/work\/([0-9a-f-]{36})/)?.[1] ?? null;
+     *
+     * <Layout.NavTabBar
+     *   shouldKeepTab={(tab, { pathname }) => {
+     *     const tabWork = workId(tab.key);
+     *     return !tabWork || tabWork === workId(pathname);
+     *   }}
+     * />
+     * ```
+     */
+    shouldKeepTab?: (tab: TabType, info: {
+        pathname: string;
+    }) => boolean;
 }
 declare const NavTabBar: React.FC<NavTabBarProps>;
 export default NavTabBar;

package/es/layout/NavTabBar/index.js

@@ -24,6 +24,7 @@ import { useTabPath } from "./_hooks/useTabPath";
 import { useTabContextMenu } from "./_hooks/useTabContextMenu";
 import { useDropTabKey } from "./_hooks/useDropTabKey";
 import { useTabTitle } from "./_hooks/useTabTitle";
+import { useKeepTabs } from "./_hooks/useKeepTabs";
 import TabLabel from "./_components/TabLabel";
 import DraggableTabNode from "./_components/SortableTab";
 import TabDragOverlay from "./_components/TabDragOverlay";
@@ -40,7 +41,8 @@ var NavTabBar = function NavTabBar(props) {
     _props$basePath = props.basePath,
     basePath = _props$basePath === void 0 ? "/" : _props$basePath,
     _props$showReload = props.showReload,
-    showReload = _props$showReload === void 0 ? true : _props$showReload;
+    showReload = _props$showReload === void 0 ? true : _props$showReload,
+    shouldKeepTab = props.shouldKeepTab;
   var navigate = useNavigate();
   var _useAliveController = useAliveController(),
     drop = _useAliveController.drop,
@@ -62,6 +64,7 @@ var NavTabBar = function NavTabBar(props) {
     setOpen = _useTabContextMenu.setOpen;
   useDropTabKey(setOpenkeys);
   useTabTitle(setOpenkeys);
+  useKeepTabs(shouldKeepTab, setOpenkeys);
 
   // ID of the tab currently being dragged
   var _useState = useState(null),

package/es/layout/index.d.ts

@@ -26,6 +26,13 @@ export type { RouteType, MetaType } from "./types";
  */
 export type { AccountAction, HeaderProps } from "./Header";
 export type { MenuType, MenuProps } from "./Menu";
+/**
+ * 次级菜单的默认头部。`Menu` 在切到次级菜单时会自己渲染它，一般不用管；
+ * 需要在返回入口下面塞点东西（详情内检索框之类）时，把它的 `extra` 用起来、
+ * 整块作为 `secondaryHeader` 传给 `Menu`。
+ */
+export { default as SecondaryHeader } from "./Menu/_components/SecondaryHeader";
+export type { SecondaryHeaderProps } from "./Menu/_components/SecondaryHeader";
 export type { TabType, NavTabBarProps } from "./NavTabBar";
 export type { BreadcrumbType, BreadcrumbProps } from "./Breadcrumb";
 export type { InternationalizationProps } from "./I18n";

package/es/layout/index.js

@@ -25,6 +25,12 @@ import ThemeStore from "./Theme/ThemeStore";
  * 目录结构变成公开契约。统一从这里出。
  */
 
+/**
+ * 次级菜单的默认头部。`Menu` 在切到次级菜单时会自己渲染它，一般不用管；
+ * 需要在返回入口下面塞点东西（详情内检索框之类）时，把它的 `extra` 用起来、
+ * 整块作为 `secondaryHeader` 传给 `Menu`。
+ */
+export { default as SecondaryHeader } from "./Menu/_components/SecondaryHeader";
 export { default as useSetTabTitle, NavTabBarTitleContent } from "./_hooks/useSetTabTitle";
 export { default as useReload, ReloadContent } from "./_hooks/useReload";
 export { default as useDropTab, NavTabBarContent } from "./_hooks/useDropTab";

package/lib/layout/Header/index.d.ts

@@ -34,6 +34,14 @@ export interface HeaderProps {
     title?: React.ReactNode;
     /** 侧栏收起时用的短标题；不传则回落到 title */
     smallTitle?: React.ReactNode;
+    /**
+     * 是否显示语言切换。
+     *
+     * 只有中文一种文案的项目把它关掉——留着会给用户一个切了之后只有 antd 内建文案变化、
+     * 业务文案纹丝不动的开关，比没有更糟。关掉后 `Layout.I18n` 仍可照常用（日期、分页
+     * 这些 antd 内建文案还是要它）。
+     */
+    showLocale?: boolean;
 }
 declare const Header: React.FC<HeaderProps>;
 export default Header;

package/lib/layout/Header/index.js

@@ -43,7 +43,8 @@ const Header = (0, _mobxReactLite.observer)(props => {
     menu,
     user,
     title,
-    smallTitle
+    smallTitle,
+    showLocale = true
   } = props;
   const {
     layout,
@@ -126,7 +127,7 @@ const Header = (0, _mobxReactLite.observer)(props => {
               options: appearanceOptions,
               onChange: v => setAppearance(v)
             })]
-          }), /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+          }), showLocale && /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
             className: _indexModule.default.settingRow,
             children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
               className: _indexModule.default.settingLabel,

package/lib/layout/NavTabBar/_hooks/useKeepTabs.d.ts

@@ -0,0 +1,18 @@
+import { TabType } from "..";
+/**
+ * 按业务规则在地址变化时收掉一批页签。
+ *
+ * 起因是消费方（writer-assistant）的一条规则：进出某部作品时，把上一部作品的所有页签
+ * 一起清掉——「一次只专注一部书」。这种规则依赖业务对 URL 的解读（哪一段是作品 id），
+ * 组件库不可能内建，但**收页签这件事本身**必须留在库里做：光从 openKeys 里删掉不够，
+ * 还要 `drop` 掉 react-activation 的缓存，否则组件树留在内存里，下次同名路由回来还会
+ * 复用旧实例。
+ *
+ * 所以对外只暴露一个判定函数，删除与丢缓存由这里统一执行。
+ *
+ * 判定按**当前地址**做，不需要消费方自己记「上一个是什么」：每次地址变化重新评估每个
+ * 页签「在现在这个位置还该不该留着」，语义更直白，也不会因为漏更新 ref 而出错。
+ */
+export declare const useKeepTabs: (shouldKeepTab: ((tab: TabType, info: {
+    pathname: string;
+}) => boolean) | undefined, setOpenkeys: React.Dispatch<React.SetStateAction<TabType[]>>) => void;

package/lib/layout/NavTabBar/_hooks/useKeepTabs.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useKeepTabs = void 0;
+var _react = require("react");
+var _reactRouter = require("react-router");
+var _reactActivation = require("react-activation");
+/**
+ * 按业务规则在地址变化时收掉一批页签。
+ *
+ * 起因是消费方（writer-assistant）的一条规则：进出某部作品时，把上一部作品的所有页签
+ * 一起清掉——「一次只专注一部书」。这种规则依赖业务对 URL 的解读（哪一段是作品 id），
+ * 组件库不可能内建，但**收页签这件事本身**必须留在库里做：光从 openKeys 里删掉不够，
+ * 还要 `drop` 掉 react-activation 的缓存，否则组件树留在内存里，下次同名路由回来还会
+ * 复用旧实例。
+ *
+ * 所以对外只暴露一个判定函数，删除与丢缓存由这里统一执行。
+ *
+ * 判定按**当前地址**做，不需要消费方自己记「上一个是什么」：每次地址变化重新评估每个
+ * 页签「在现在这个位置还该不该留着」，语义更直白，也不会因为漏更新 ref 而出错。
+ */
+const useKeepTabs = (shouldKeepTab, setOpenkeys) => {
+  const {
+    pathname
+  } = (0, _reactRouter.useLocation)();
+  const {
+    drop
+  } = (0, _reactActivation.useAliveController)();
+  (0, _react.useEffect)(() => {
+    if (!shouldKeepTab) return;
+    setOpenkeys(prev => {
+      const kept = prev.filter(tab => shouldKeepTab(tab, {
+        pathname
+      }));
+      if (kept.length === prev.length) return prev;
+      prev.filter(tab => !kept.includes(tab))
+      // 缓存是按不带 query 的路径存的
+      .forEach(tab => drop(tab.key.split("?")[0] || ""));
+      return kept;
+    });
+    // shouldKeepTab 多半是行内箭头函数，放进依赖会每次渲染都重跑。
+    // 这个 effect 的触发时机就是「地址变了」，按 pathname 走即可。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname]);
+};
+exports.useKeepTabs = useKeepTabs;

package/lib/layout/NavTabBar/index.d.ts

@@ -16,6 +16,27 @@ export interface NavTabBarProps {
     basePath?: string;
     /** 页签栏最前面的「刷新当前页」按钮 */
     showReload?: boolean;
+    /**
+     * 地址变化时决定每个页签还留不留。返回 false 的会被关掉，并连同 react-activation 的
+     * 缓存一起丢弃。
+     *
+     * 给的是「在当前地址下这个页签还该不该在」这种判定，不需要自己记上一个位置是什么。
+     *
+     * @example 一次只专注一部作品：进入另一部书时，把上一部的页签全收掉
+     * ```ts
+     * const workId = (p: string) => p.match(/\/work\/([0-9a-f-]{36})/)?.[1] ?? null;
+     *
+     * <Layout.NavTabBar
+     *   shouldKeepTab={(tab, { pathname }) => {
+     *     const tabWork = workId(tab.key);
+     *     return !tabWork || tabWork === workId(pathname);
+     *   }}
+     * />
+     * ```
+     */
+    shouldKeepTab?: (tab: TabType, info: {
+        pathname: string;
+    }) => boolean;
 }
 declare const NavTabBar: React.FC<NavTabBarProps>;
 export default NavTabBar;

package/lib/layout/NavTabBar/index.js

@@ -18,6 +18,7 @@ var _useTabPath = require("./_hooks/useTabPath");
 var _useTabContextMenu = require("./_hooks/useTabContextMenu");
 var _useDropTabKey = require("./_hooks/useDropTabKey");
 var _useTabTitle = require("./_hooks/useTabTitle");
+var _useKeepTabs = require("./_hooks/useKeepTabs");
 var _TabLabel = _interopRequireDefault(require("./_components/TabLabel"));
 var _SortableTab = _interopRequireDefault(require("./_components/SortableTab"));
 var _TabDragOverlay = _interopRequireDefault(require("./_components/TabDragOverlay"));
@@ -33,7 +34,8 @@ const NavTabBar = props => {
     router,
     affixRouter = [],
     basePath = "/",
-    showReload = true
+    showReload = true,
+    shouldKeepTab
   } = props;
   const navigate = (0, _reactRouter.useNavigate)();
   const {
@@ -59,6 +61,7 @@ const NavTabBar = props => {
   } = (0, _useTabContextMenu.useTabContextMenu)();
   (0, _useDropTabKey.useDropTabKey)(setOpenkeys);
   (0, _useTabTitle.useTabTitle)(setOpenkeys);
+  (0, _useKeepTabs.useKeepTabs)(shouldKeepTab, setOpenkeys);
 
   // ID of the tab currently being dragged
   const [activeId, setActiveId] = (0, _react.useState)(null);

package/lib/layout/index.d.ts

@@ -26,6 +26,13 @@ export type { RouteType, MetaType } from "./types";
  */
 export type { AccountAction, HeaderProps } from "./Header";
 export type { MenuType, MenuProps } from "./Menu";
+/**
+ * 次级菜单的默认头部。`Menu` 在切到次级菜单时会自己渲染它，一般不用管；
+ * 需要在返回入口下面塞点东西（详情内检索框之类）时，把它的 `extra` 用起来、
+ * 整块作为 `secondaryHeader` 传给 `Menu`。
+ */
+export { default as SecondaryHeader } from "./Menu/_components/SecondaryHeader";
+export type { SecondaryHeaderProps } from "./Menu/_components/SecondaryHeader";
 export type { TabType, NavTabBarProps } from "./NavTabBar";
 export type { BreadcrumbType, BreadcrumbProps } from "./Breadcrumb";
 export type { InternationalizationProps } from "./I18n";

package/lib/layout/index.js

@@ -21,6 +21,12 @@ Object.defineProperty(exports, "ReloadContent", {
     return _useReload.ReloadContent;
   }
 });
+Object.defineProperty(exports, "SecondaryHeader", {
+  enumerable: true,
+  get: function () {
+    return _SecondaryHeader.default;
+  }
+});
 exports.default = void 0;
 Object.defineProperty(exports, "useDropTab", {
   enumerable: true,
@@ -48,6 +54,7 @@ var _NavTabBar = _interopRequireDefault(require("./NavTabBar"));
 var _Theme = _interopRequireDefault(require("./Theme"));
 var _I18nStore = _interopRequireDefault(require("./I18n/I18nStore"));
 var _ThemeStore = _interopRequireDefault(require("./Theme/ThemeStore"));
+var _SecondaryHeader = _interopRequireDefault(require("./Menu/_components/SecondaryHeader"));
 var _useSetTabTitle = _interopRequireWildcard(require("./_hooks/useSetTabTitle"));
 var _useReload = _interopRequireWildcard(require("./_hooks/useReload"));
 var _useDropTab = _interopRequireWildcard(require("./_hooks/useDropTab"));
@@ -73,6 +80,12 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * 目录结构变成公开契约。统一从这里出。
  */
 
+/**
+ * 次级菜单的默认头部。`Menu` 在切到次级菜单时会自己渲染它，一般不用管；
+ * 需要在返回入口下面塞点东西（详情内检索框之类）时，把它的 `extra` 用起来、
+ * 整块作为 `secondaryHeader` 传给 `Menu`。
+ */
+
 /**
  * 显式标注这个命名空间的类型，而不是让 TS 去推断。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",

package/src/layout/Header/index.md

@@ -116,5 +116,10 @@ import type {
 | onToggleCollapsed | 点击收起按钮 | `() => void` | - |
 | onChildItems | mixed 布局下把顶部菜单的子项回传给左侧栏 | `(items: MenuType[]) => void` | - |
 | menu | 账号下拉里的动作项（改密、退出等） | `AccountAction[]` | - |
+| showLocale | 是否显示语言切换 | `boolean` | `true` |
+
+只有中文一种文案的项目请把 `showLocale` 关掉：留着会给用户一个「切了之后只有 antd 内建
+文案变化、业务文案纹丝不动」的开关，比没有更糟。关掉后 [`Layout.I18n`](/layouts/i18n) 仍
+可照常用 —— 日期选择器、分页这些 antd 内建文案还是要它。
 
 > `user` 与 `title` 原本分别读应用的鉴权模块与全局 `Config`，移入库时改成了属性 —— 组件不该认识消费方的这两样东西。

package/src/layout/Header/index.tsx

@@ -53,6 +53,14 @@ export interface HeaderProps {
   title?: React.ReactNode;
   /** 侧栏收起时用的短标题；不传则回落到 title */
   smallTitle?: React.ReactNode;
+  /**
+   * 是否显示语言切换。
+   *
+   * 只有中文一种文案的项目把它关掉——留着会给用户一个切了之后只有 antd 内建文案变化、
+   * 业务文案纹丝不动的开关，比没有更糟。关掉后 `Layout.I18n` 仍可照常用（日期、分页
+   * 这些 antd 内建文案还是要它）。
+   */
+  showLocale?: boolean;
 }
 
 const Header: React.FC<HeaderProps> = observer((props) => {
@@ -65,6 +73,7 @@ const Header: React.FC<HeaderProps> = observer((props) => {
     user,
     title,
     smallTitle,
+    showLocale = true,
   } = props;
   const { layout, headerTheme, appearance, setAppearance } = ThemeStore;
   const { locale, setLocale } = I18nStore;
@@ -148,17 +157,19 @@ const Header: React.FC<HeaderProps> = observer((props) => {
                   onChange={(v) => setAppearance(v as typeof appearance)}
                 />
               </div>
-              <div className={styles.settingRow}>
-                <span className={styles.settingLabel}>
-                  {isEn ? "Language" : "语言"}
-                </span>
-                <Segmented
-                  size="small"
-                  value={locale}
-                  options={languageOptions}
-                  onChange={(v) => setLocale(v as string)}
-                />
-              </div>
+              {showLocale && (
+                <div className={styles.settingRow}>
+                  <span className={styles.settingLabel}>
+                    {isEn ? "Language" : "语言"}
+                  </span>
+                  <Segmented
+                    size="small"
+                    value={locale}
+                    options={languageOptions}
+                    onChange={(v) => setLocale(v as string)}
+                  />
+                </div>
+              )}
 
               <div className={styles.settingDivider} />
 

package/src/layout/Menu/index.md

@@ -41,3 +41,33 @@ import Layout from "@hsu-react/ui/es/layout";
 | secondaryItemFilter | 次级菜单项的额外过滤，按 key（绝对路径）判断 | `(key: string) => boolean` | - |
 
 > 其余属性透传给 antd 的 [Menu](https://ant.design/components/menu-cn)。
+
+### 自定义次级菜单头部
+
+不传 `secondaryHeader` 时组件会渲染一个默认头部（返回入口 ＋ 当前实体名）。要在它上面加东西
+——比如详情内检索框——不用整块重写，把 `SecondaryHeader` 拿出来用它的 `extra` 插槽：
+
+```tsx | pure
+import Layout, { SecondaryHeader } from "@hsu-react/ui/es/layout";
+
+<Layout.Menu
+  router={router}
+  secondaryHeader={
+    <SecondaryHeader
+      collapsed={collapsed}
+      theme="dark"
+      title={work.name}
+      extra={<SearchInWork workId={work.id} />}
+    />
+  }
+/>;
+```
+
+| SecondaryHeader 属性 | 说明 | 类型 |
+| --- | --- | --- |
+| collapsed | 侧栏是否收起，收起时只剩箭头 | `boolean` |
+| theme | 明暗，跟随侧栏 | `"light" \| "dark"` |
+| backText | 返回入口文案 | `string` |
+| onBack | 自定义返回行为，不给则退回上一页 | `() => void` |
+| title | 当前实体名 | `string` |
+| extra | 返回入口与标题之间的插槽 | `ReactNode` |

package/src/layout/NavTabBar/_hooks/useKeepTabs.ts

@@ -0,0 +1,46 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+import { useAliveController } from "react-activation";
+
+import { TabType } from "..";
+
+/**
+ * 按业务规则在地址变化时收掉一批页签。
+ *
+ * 起因是消费方（writer-assistant）的一条规则：进出某部作品时，把上一部作品的所有页签
+ * 一起清掉——「一次只专注一部书」。这种规则依赖业务对 URL 的解读（哪一段是作品 id），
+ * 组件库不可能内建，但**收页签这件事本身**必须留在库里做：光从 openKeys 里删掉不够，
+ * 还要 `drop` 掉 react-activation 的缓存，否则组件树留在内存里，下次同名路由回来还会
+ * 复用旧实例。
+ *
+ * 所以对外只暴露一个判定函数，删除与丢缓存由这里统一执行。
+ *
+ * 判定按**当前地址**做，不需要消费方自己记「上一个是什么」：每次地址变化重新评估每个
+ * 页签「在现在这个位置还该不该留着」，语义更直白，也不会因为漏更新 ref 而出错。
+ */
+export const useKeepTabs = (
+  shouldKeepTab: ((tab: TabType, info: { pathname: string }) => boolean) | undefined,
+  setOpenkeys: React.Dispatch<React.SetStateAction<TabType[]>>
+) => {
+  const { pathname } = useLocation();
+  const { drop } = useAliveController();
+
+  useEffect(() => {
+    if (!shouldKeepTab) return;
+
+    setOpenkeys((prev) => {
+      const kept = prev.filter((tab) => shouldKeepTab(tab, { pathname }));
+      if (kept.length === prev.length) return prev;
+
+      prev
+        .filter((tab) => !kept.includes(tab))
+        // 缓存是按不带 query 的路径存的
+        .forEach((tab) => drop(tab.key.split("?")[0] || ""));
+
+      return kept;
+    });
+    // shouldKeepTab 多半是行内箭头函数，放进依赖会每次渲染都重跑。
+    // 这个 effect 的触发时机就是「地址变了」，按 pathname 走即可。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname]);
+};

package/src/layout/NavTabBar/index.md

@@ -62,6 +62,32 @@ export default () => (
 | affixRouter | 额外固定的路由路径（等价于给这些路由加 `meta.affix`） | `string[]` | `[]` |
 | basePath | 关掉最后一个页签后回退到的路径 | `string` | `"/"` |
 | showReload | 页签栏最前面的「刷新当前页」按钮 | `boolean` | `true` |
+| shouldKeepTab | 地址变化时决定每个页签留不留，返回 `false` 的会被关掉并丢弃缓存 | `(tab, { pathname }) => boolean` | - |
+
+## 按业务规则批量收页签
+
+`shouldKeepTab` 用来表达「在当前这个位置，这个页签还该不该留着」。典型场景是同一时间只
+围绕一个对象工作，切到另一个对象时把上一个的页签一起收掉：
+
+```tsx | pure
+const workId = (p: string) => p.match(/\/work\/([0-9a-f-]{36})/)?.[1] ?? null;
+
+<Layout.NavTabBar
+  router={router}
+  shouldKeepTab={(tab, { pathname }) => {
+    const tabWork = workId(tab.key);
+    // 不属于任何作品的页签（总览、设置…）一律留着；属于某部作品的，只在还在那部作品里时留
+    return !tabWork || tabWork === workId(pathname);
+  }}
+/>;
+```
+
+判定按**当前地址**做，不用自己记「上一个位置是什么」—— 每次地址变化重新评估一遍，语义更
+直白，也不会因为漏更新而残留。
+
+> 关页签这件事必须由组件来做：光把它从列表里去掉不够，还要丢掉 react-activation 的缓存，
+> 否则那棵组件树留在内存里，下次同名路由回来会复用旧实例。所以这里只让你给判定，删除与
+> 丢缓存由组件统一执行。
 
 ## 配套 Hook
 

package/src/layout/NavTabBar/index.tsx

@@ -27,6 +27,7 @@ import { useTabPath } from "./_hooks/useTabPath";
 import { useTabContextMenu } from "./_hooks/useTabContextMenu";
 import { useDropTabKey } from "./_hooks/useDropTabKey";
 import { useTabTitle } from "./_hooks/useTabTitle";
+import { useKeepTabs } from "./_hooks/useKeepTabs";
 import TabLabel from "./_components/TabLabel";
 import DraggableTabNode from "./_components/SortableTab";
 import TabDragOverlay from "./_components/TabDragOverlay";
@@ -51,6 +52,25 @@ export interface NavTabBarProps {
   basePath?: string;
   /** 页签栏最前面的「刷新当前页」按钮 */
   showReload?: boolean;
+  /**
+   * 地址变化时决定每个页签还留不留。返回 false 的会被关掉，并连同 react-activation 的
+   * 缓存一起丢弃。
+   *
+   * 给的是「在当前地址下这个页签还该不该在」这种判定，不需要自己记上一个位置是什么。
+   *
+   * @example 一次只专注一部作品：进入另一部书时，把上一部的页签全收掉
+   * ```ts
+   * const workId = (p: string) => p.match(/\/work\/([0-9a-f-]{36})/)?.[1] ?? null;
+   *
+   * <Layout.NavTabBar
+   *   shouldKeepTab={(tab, { pathname }) => {
+   *     const tabWork = workId(tab.key);
+   *     return !tabWork || tabWork === workId(pathname);
+   *   }}
+   * />
+   * ```
+   */
+  shouldKeepTab?: (tab: TabType, info: { pathname: string }) => boolean;
 }
 
 const NavTabBar: React.FC<NavTabBarProps> = (props) => {
@@ -59,6 +79,7 @@ const NavTabBar: React.FC<NavTabBarProps> = (props) => {
     affixRouter = [],
     basePath = "/",
     showReload = true,
+    shouldKeepTab,
   } = props;
   const navigate = useNavigate();
   const { drop, refresh } = useAliveController();
@@ -78,6 +99,7 @@ const NavTabBar: React.FC<NavTabBarProps> = (props) => {
 
   useDropTabKey(setOpenkeys);
   useTabTitle(setOpenkeys);
+  useKeepTabs(shouldKeepTab, setOpenkeys);
 
   // ID of the tab currently being dragged
   const [activeId, setActiveId] = useState<string | null>(null);

package/src/layout/index.ts

@@ -29,6 +29,13 @@ export type { RouteType, MetaType } from "./types";
  */
 export type { AccountAction, HeaderProps } from "./Header";
 export type { MenuType, MenuProps } from "./Menu";
+/**
+ * 次级菜单的默认头部。`Menu` 在切到次级菜单时会自己渲染它，一般不用管；
+ * 需要在返回入口下面塞点东西（详情内检索框之类）时，把它的 `extra` 用起来、
+ * 整块作为 `secondaryHeader` 传给 `Menu`。
+ */
+export { default as SecondaryHeader } from "./Menu/_components/SecondaryHeader";
+export type { SecondaryHeaderProps } from "./Menu/_components/SecondaryHeader";
 export type { TabType, NavTabBarProps } from "./NavTabBar";
 export type { BreadcrumbType, BreadcrumbProps } from "./Breadcrumb";
 export type { InternationalizationProps } from "./I18n";