@oj-module/cli 0.1.20 → 0.1.21

package/devkit/manual.md

@@ -1071,22 +1071,30 @@ t("menu.books")         // ❌ 会去 common namespace 找
 **运行期数据**，在页面里把数据拿到后覆盖：
 
 ```tsx
-import { useTabsStore } from "@oj-module/runtime";
+import { useTabKey, useTabsStore } from "@oj-module/runtime";
 
 const setTableTitle = useTabsStore(s => s.setTableTitle);
-const { pathname } = useLocation();
+const tabKey = useTabKey(); // 本页自己的页签 key（见下方陷阱说明，**不要**用 useLocation 现取值）
 
 useEffect(() => {
-	if (doc?.name) setTableTitle(pathname, doc.name);
-}, [doc?.name, pathname, setTableTitle]);
+	if (doc?.name) setTableTitle(tabKey, doc.name);
+}, [doc?.name, tabKey, setTableTitle]);
 ```
 
+> 陷阱（keepAlive）：开启多页签后，keepalive-for-react 把页面缓存在隐藏容器里，而
+> LocationContext 在 KeepAlive **之上**——切页签时缓存树随**激活页**位置重渲染，缓存页里的
+> `useLocation()` 返回的是别家页签的路径。用它当 key 会把本页标题写到当前激活页签上
+> （典型症状：最后打开的文档页把之后切换到的每个页签都改成自己的标题）。`useTabKey()`
+> 首渲染捕获本页真实 key，存活期内稳定，是 `setTableTitle` / `resetTableTitle` / `addTab`
+> 定位页签的**唯一**正确取口。runtime < 0.1.21 无此 hook 时，本地等价实现：首渲染
+> `useRef(removeTrailingSlash(useLocation().pathname))` 捕获一次。
+
 三点约束：
 
-1. 路径必须与导航路径**逐字一致**——页签 key 是 `removeTrailingSlash(location.pathname)` 归一后的值；
+1. 页签 key 一律经 `useTabKey()` 取（= `removeTrailingSlash(location.pathname)` 归一后的值）；
 2. `setTableTitle` 只改**已打开**的页签，故要在页面渲染后（数据就绪时）调用，不能提前于路由挂载；
 3. 只在页签 key 与内容**一一对应**时这样用（如 `/doc/:id`——一个 id 一个页签）。若同一路径会被
-   复用展示不同内容（列表页/`index` 路由），离开时必须 `resetTableTitle(pathname)`，否则再进来看到
+   复用展示不同内容（列表页/`index` 路由），离开时必须 `resetTableTitle(tabKey)`，否则再进来看到
    上一个内容的标题。
 
 推荐形态（照 `web/src/home/pages/`、`web/src/personal-center/pages/my-profile/` 抄）：

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "React Antd Admin 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.1.20",
+    "@oj-module/runtime": "0.1.21",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "esbuild": "^0.28.2",

package/shell-dist/assets/runtime.js

@@ -255,10 +255,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.1.20",
+			"version": "0.1.21",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-15 16:50:57"
+		"lastBuildTime": "2026-10-15 18:45:29"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -9372,6 +9372,28 @@ function getBooleanOptions(t) {
 	}];
 }
 //#endregion
+//#region src/hooks/use-tab-key/index.ts
+init_remove_trailing_slash();
+/**
+* 本页自己的页签 key（`removeTrailingSlash(pathname)`），供 `setTableTitle` /
+* `resetTableTitle` / `addTab` 定位页签。
+*
+* keepAlive 陷阱：keepalive-for-react 把页面缓存在隐藏 portal 里，而 LocationContext
+* 在 KeepAlive **之上**——切 tab 时缓存树随**激活页**位置重渲染，缓存页里的
+* `useLocation()` 返回的是别家页签的路径。若拿它当页签 key，`setTableTitle` 会把
+* 本页标题写到当前激活页签上（最后打开的文档页把之后切换到的每个页签都改成自己的标题）。
+*
+* 页签存活期内 key 不变（宿主 cacheKey = pathname+search，一页一路径），故首渲染
+* （此时本页必是激活页）捕获一次即可；缓存树后续多少次重渲染都不会漂移。
+* 需要跟随导航的位置信息请直接用 `useLocation`，不要用本 hook。
+*/
+function useTabKey() {
+	const { pathname } = useLocation();
+	const keyRef = useRef(void 0);
+	if (keyRef.current === void 0) keyRef.current = removeTrailingSlash(pathname);
+	return keyRef.current;
+}
+//#endregion
 //#region src/module-loader/define-module.ts
 /**
 * 声明一个模块。
@@ -27441,4 +27463,4 @@ init_ri();
 init_menu_icons();
 init_tree();
 //#endregion
-export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLogin, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useTabsStore, useUserStore, external_exports as z };
+export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLogin, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useTabKey, useTabsStore, useUserStore, external_exports as z };

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-aMxR7a5yEi7eE8DlhFuiNg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-tZIZWgEHDhCICXVOR+DUzQ=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="aMxR7a5yEi7eE8DlhFuiNg==">{
+		<script type="importmap" nonce="tZIZWgEHDhCICXVOR+DUzQ==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.1.20",
-  "@oj-module/runtime/contract": "0.1.20",
-  "@oj-module/runtime/contract/errors": "0.1.20",
+  "@oj-module/runtime": "0.1.21",
+  "@oj-module/runtime/contract": "0.1.21",
+  "@oj-module/runtime/contract/errors": "0.1.21",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/build.ts

@@ -74,6 +74,8 @@ export const permissionPrefix = "permission:button";
 export const useAuthStore = _fn;
 export const useUserStore = _fn;
 export const useTabsStore = _fn;
+// 页签 key 唯一正确取口（keepAlive 下 useLocation 是激活页位置，0.1.21）
+export const useTabKey = _fn;
 // 图标
 export const menuIcons = _obj;
 export const EmbeddedIcon = _fn;

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.1.20",
-		"@oj-module/runtime/contract": "0.1.20",
-		"@oj-module/runtime/contract/errors": "0.1.20",
+		"@oj-module/runtime": "0.1.21",
+		"@oj-module/runtime/contract": "0.1.21",
+		"@oj-module/runtime/contract/errors": "0.1.21",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",