# @caspeco/navigation-core 中文文档 规范地址：https://npmcn.com/package/%40caspeco/navigation-core/ 版本：3\.21\.0 npm 元数据更新时间：2026-10-29T14:49:06.078Z 中文译文更新时间：2026-11-09T14:14:43.626Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40caspeco/navigation-core 原文对照：https://npmcn.com/package/%40caspeco/navigation-core/?lang=original 项目主页：https://github.com/Caspeco/WebComponents#readme 源码仓库：https://github.com/Caspeco/WebComponents ## 关键信息（来自 npm 元数据） - 包体积（解压后）：35 kB，40 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2025-03-10T10:52:24.317Z - 最新版本发布：2026-10-29T14:49:05.764Z - 近 30 天下载量：2474（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：42（近 12 个月 12 个） ## 中文简介 [![NPM Version](https://img.shields.io/npm/v/%40caspeco%2Fnavigation-core?logo=npm&label=%40caspeco%2Fnavigation-core)](https://www.npmjs.com/package/@caspeco/navigation-core) ## 安装 ```sh npm install @caspeco/navigation-core ``` 也可以使用：`pnpm add @caspeco/navigation-core`、`yarn add @caspeco/navigation-core`、`bun add @caspeco/navigation-core` ## README # @caspeco/导航-核心 [![NPM Version](https://img.shields.io/npm/v/%40caspeco%2Fnavigation-core?logo=npm&label=%40caspeco%2Fnavigation-core)](https://www.npmjs.com/package/@caspeco/navigation-core) 此软件包将安装 TypeScript 类型定义 `` [网络组件](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) 以及一些公用事业功能. ## 额外资源 - [发展文件(捐款.md)](https://npmcn.com/package/%40caspeco/navigation-core/CONTRIBUTING.md) - [文件类型网站](https://caspeco.github.io/WebComponents/) - [样本应用( Dev)](https://cap-dev-webcomponent-ne-main.core.dev.caspeco.net/) - [组合页面](https://caspeco.atlassian.net/wiki/spaces/C360/pages/4170842113/Navigationsmenyn) ## 安装 从 npm 安装软件包. ```sh npm i @caspeco/navigation-core ``` ## 使用量 ### 正确打入道具 为了保证你通过正确的道具,你可以使用 `NavigationMenuProps` 类型 : ```tsx import type { NavigationMenuProps } from "@caspeco/navigation-core"; export const NavigationMenu = () => { const navProps: NavigationMenuProps = { currentLocation: window.location.href, itemGroup: "Staff", // etc ... }; return ; }; ``` ### 倾听事件 导航有您可能想要听的自定义事件 。 导航事件总是在身体元素上发出,并且会发泡. ```tsx import type { MobileMenuClosedEventName } from "@caspeco/navigation-core"; useEffect(() => { const eventName: MobileMenuClosedEventName = "mobile-menu-closed"; function handleMobileMenuClosed() { doSomething(); } window.addEventListener(eventName, handleMobileMenuClosed); return () => { window.removeEventListener(eventName, handleMobileMenuClosed); }; }, []); ``` ### 语言选择 导航菜单支持语言选择,允许用户更改界面语言. #### 从饼干读语言 使用 `getLocale` 函数从 `rms.locale` 页面负荷上的 cookie : ```ts import { getLocale } from "@caspeco/navigation-core"; // e.g. "en-GB", "sv-SE", "da-DK" const currentLocale = getLocale(); ``` #### 听语言变化 当用户更改导航菜单中的语言时, a `rms-locale-change` 自定义事件在文档正文( bubling) 上发送 . 新地块包含在活动的细节中. 消费者应该聆听这一事件,并相应更新他们的语言: ```tsx import type { LocaleChangeEventName } from "@caspeco/navigation-core"; useEffect(() => { const eventName: LocaleChangeEventName = "rms-locale-change"; function handleLocaleChanged(event: Event) { if (!(event instanceof CustomEvent)) { return; } const newLocale = event.detail.locale as string; // e.g., "en-GB", "sv-SE", "da-DK", etc. // Update your application's language updateApplicationLanguage(newLocale); } window.addEventListener(eventName, handleLocaleChanged); return () => { window.removeEventListener(eventName, handleLocaleChanged); }; }, []); ``` #### 设置语言 在大多数情况下,语言应该由用户通过导航菜单来改变. 如果你有很好的理由在程序上更改语言,你可以使用 `setLocale` 函数 : ```ts import { setLocale } from "@caspeco/navigation-core"; // Sends a POST to the SSO API in dev to set the locale cookie, and dispatches the "rms-locale-change" event. setLocale({ locale: "en-GB", environment: "dev" }); ``` ### A. 背景情况 上下文包含了用户在上下文选择器中选择的公司(或系统!)的信息. #### 阅读上下文 要正确阅读 RMS 上下文, 您可以使用 `getRmsContext()` 函数 : ```ts import { getRmsContext } from "@caspeco/navigation-core"; function getContextId(): string { const { companyId, systemName } = getRmsContext(); return companyId ?? systemName; } ``` #### 设置背景 如果你需要的话,你也可以 `setRmsContext()`,但使用这个案例应该是罕见的。 确保设置上下文后触发页面导航(要么重新装入页面,要么重定向用户). #### 防止上下文变化 默认情况下,当一个用户在上下文选择器中改变上下文时,他们的选择被保存在浏览器存储中并被重定向到概览页面. 在某些情况下,你可能想把他们送到别的地方(例如Cloud App想把人送到/cloud/home),在这种情况下,你可以拦截并取消 `context-selected` 自定义事件 : ```tsx import { setRmsContext, type RmsContext, type ContextSelectedEventName } from "@caspeco/navigation-core"; useEffect(() => { const eventName: ContextSelectedEventName = "context-selected"; function handleContextChanged(event: Event) { if (!(event instanceof CustomEvent)) { return; } // Cancel default behavior event.preventDefault(); // Set the context const newContext = event.detail as RmsContext; setRmsContext(newContext); // Redirect somewhere other than the Overview page window.location.href = "rms.caspeco.se/cloud/home"; } window.addEventListener(eventName, handleContextChanged); return () => { window.removeEventListener(eventName, handleContextChanged); }; }, []); ``` ## 安装 `` ### 备选办法1:使用国家预防机制一揽子方案(试行) **参见: >=3.8.0-α.0** #### 获取 URL 和 ID 并手动注入 ```typescript import { getNavigationScriptData } from "@caspeco/navigation-core"; const { src, id } = getNavigationScriptData({ environment: "stage" }); const script = document.createElement("script"); script.id = id; script.src = src; script.type = "module"; document.head.appendChild(script); ``` #### 获取 HTML 脚本元素并手动注入 _如果在 DOM 中已经存在, 将跳过注射 ._ ```typescript import { getNavigationHTMLScriptElement } from "@caspeco/navigation-core"; const { scriptElement, data } = getNavigationHTMLScriptElement({ environment: "stage" }); document.head.appendChild(scriptElement); ``` #### 自动注入 _如果在 DOM 中已经存在, 将跳过注射 ._ ```typescript import { injectHTMLNavigationElement } from "@caspeco/navigation-core"; injectHTMLNavigationElement({ environment: "stage" }); ``` ### 选项2:直接使用 CDN URL( 不使用 npm 包) 通过从我们的 CDN urls 导入已部署的脚本来手动添加, 例如 : ```html ``` - 发展: `https://webcomponents.dev.caspeco.net/v{MAJOR_VERSION}/index.js` - 阶段 : `https://webcomponents.stage.caspeco.net/v{MAJOR_VERSION}/index.js` - 生产: `https://webcomponents.caspeco.net/v{MAJOR_VERSION}/index.js` ### 副作用 #### 移动导航 在小设备上( < 768px),导航被转换为屏幕下方的移动导航栏. 当这种情况发生时 `mobile-nav` 类被添加到根中 `html` 文档. 您可能需要更新您的应用程序以应对此变化, 例如改变您的应用程序的高度 `100%` 改为 `calc(100% - var(--mobile-navigation-height))`编辑 `--mobile-navigation-height` 自动添加到根上 `html` 文档. 这是《概览》页上必须做的一个例子: ```diff main { height: 100%; /* ... */ } + .mobile-nav main { + height: calc(100% - var(--mobile-navigation-height)); + } ``` #### 传真 导航 **将覆盖您现有的外观** 和正确的品牌 favicons 一旦加载. ![dev favicon](https://npmcn.com/package/%40caspeco/navigation-core/src/assets/favicon/dev/icon.svg) ![docker favicon](https://npmcn.com/package/%40caspeco/navigation-core/src/assets/favicon/docker/icon.svg) ![stage favicon](https://npmcn.com/package/%40caspeco/navigation-core/src/assets/favicon/stage/icon.svg) ![prod favicon](https://npmcn.com/package/%40caspeco/navigation-core/src/assets/favicon/prod/icon.svg) #### 文档。 标题 截止2025-04-08,导航不会改变您的文档. 标题,但它很快会根据导航中页名自动修改. ## 常见问题 ### 如何安装 @caspeco/navigation-core？ 在项目目录运行 npm install @caspeco/navigation-core，或使用 pnpm add / yarn add / bun add。 ### @caspeco/navigation-core 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @caspeco/navigation-core 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @caspeco/navigation-core 可以商用吗？ @caspeco/navigation-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @caspeco/navigation-core 的下载量有多少？ 根据 npm 官方下载统计，@caspeco/navigation-core 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,474 次，日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @caspeco/navigation-core 还在维护吗？ 最新版本 3\.21\.0 发布于 2026/10/29（11 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 12 个；首次发布于 2025/03/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。