# @equinor/echo-core 中文文档 规范地址：https://npmcn.com/package/%40equinor/echo-core/ 版本：7\.0\.0 npm 元数据更新时间：2026-10-30T09:44:49.568Z 中文译文更新时间：2026-11-14T00:49:26.051Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40equinor/echo-core 原文对照：https://npmcn.com/package/%40equinor/echo-core/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：229 kB，132 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：react \>= 19\.2\.4，zustand \>= 4\.4\.7 \< 5，react-router-dom \>= 6\.30\.3 \< 7，@equinor/echo-base \>= 7\.0\.0 \< 8\.0\.0，@tanstack/react-query \>= 5\.24\.1 \< 6，@microsoft/microsoft-graph-types 2\.43\.1，@microsoft/microsoft-graph-types-beta 0\.44\.0-preview - 首次发布：2020-12-04T23:52:04.284Z - 最新版本发布：2026-10-27T14:03:39.477Z - 近 30 天下载量：2678（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：245（近 12 个月 36 个） ## 中文简介 ![logo](https://raw.githubusercontent.com/equinor/EchoCore/main/doc/ee.png) ## 安装 ```sh npm install @equinor/echo-core ``` 也可以使用：`pnpm add @equinor/echo-core`、`yarn add @equinor/echo-core`、`bun add @equinor/echo-core` ## README ![logo](https://raw.githubusercontent.com/equinor/EchoCore/main/doc/ee.png) # 回声中心 Echo的应用程序需要和核心通讯. 这个可出版的图书馆是用 [无](https://nx.dev/)。 。 。 . ## 扶养规则 **真相来源: `/eslint.config.js`** - 那个 `@nx/enforce-module-boundaries` 规则定义所有允许的依赖. **回声分数只能从 :** - `echo-base` ✅ **回声核心 CANNO 导入自 :** - `echo-framework` ❌ - `echo-search` ❌ - `echo-components` ❌ - `echopedia-web` (应用) 见 `libs/README.md` 用于完整依赖性流程图. * * * - [回声中心](https://npmcn.com/package/%40equinor/echo-core/#readme-echocore) - [如何开发并发布 EchoCore](https://npmcn.com/package/%40equinor/echo-core/#readme-how-to-develop-and-release-echocore) - [可用的国家预防机制脚本](https://npmcn.com/package/%40equinor/echo-core/#readme-available-npm-scripts) - [回声模块](https://npmcn.com/package/%40equinor/echo-core/#readme-echo-modules) - [包含设置的注册应用程序组件](https://npmcn.com/package/%40equinor/echo-core/#readme-register-application-components-with-setup) - [注册 App](https://npmcn.com/package/%40equinor/echo-core/#readme-register-app) - [用密钥注册](https://npmcn.com/package/%40equinor/echo-core/#readme-register-with-key) - [小组讨论会](https://npmcn.com/package/%40equinor/echo-core/#readme-panels) - [扩展](https://npmcn.com/package/%40equinor/echo-core/#readme-extensions) - [注册页/ 路由](https://npmcn.com/package/%40equinor/echo-core/#readme-register-page--route) - [声明](https://npmcn.com/package/%40equinor/echo-core/#readme-manifest) - [全球状态](https://npmcn.com/package/%40equinor/echo-core/#readme-global-state) - [模块状态/上下文](https://npmcn.com/package/%40equinor/echo-core/#readme-module-state--context) - [模块背景和状态](https://npmcn.com/package/%40equinor/echo-core/#readme-module-context-and-state) - [注册国](https://npmcn.com/package/%40equinor/echo-core/#readme-registrystate) - [分析](https://npmcn.com/package/%40equinor/echo-core/#readme-analytics) - [处理错误](https://npmcn.com/package/%40equinor/echo-core/#readme-error-handling) - [旧的回声库](https://npmcn.com/package/%40equinor/echo-core/#readme-old-repository-of-echocore) ## 如何开发并发布 EchoCore 检查 [读取我](https://npmcn.com/libs/README.md) 在 NX 库文件夹中. ## 可用的国家预防机制脚本 - `lint-core` - `build-core` - `test-core` # 回声模块 ## 包含设置的注册应用程序组件 Echo是围绕模块来构建的,一个模块可以由几个应用程序组成,建议模块尽量小,防止应用程序/客户端(Echo)启动时长时间的加载. 所有模块都使用模块切入点输出的设置函数进行注册. 此函数在 Echo 启动时称为 。 该函数与 `EchoModuleApi`。 。 。 . ### 注册 App Api 允许使用 `registerApp` 如下所示。 应用注册用于模块中主要应用程序的注册,基于从模块显示的元数据,可选参数可以帮助配置应用程序. ### 用密钥注册 如果一个模块包含几个应用软件,第二个应用软件可以注册到 `registerAppWithKey` 函数. 允许您手动注册一个应用程序, 所以请记住这里需要一些配置 . ### 小组讨论会 `registerPanels` 用于用提供的钥匙登记小组。 此密钥必须对应已注册的路径 。 路径用于自动触发装入面板。 如果不是需要由 `setActiveModulePanels` 行动 在使用时也可以添加应用程序面板 `registerApp`,这可以通过 App 选项实现. ### 扩展 扩展旨在扩展或扩充EchopediaWeb核心应用程序或EchoFramework中不同而现有的组件——这使系统具有灵活性. 如何处理给定的扩展总是以可扩展组件为限. EchoCore只是为此提供架构. _示例_ EchopediaWeb的 Tag 搜索结果中有一份应用程序链接列表(包括内部链接和外部链接) a `TagItem`'header - 有了这个, 我们可以打开一个不同的应用程序的标签 . 此组件被构建为可扩展:它将连接 EchoCore 状态,并根据 EchoCore 中此组件已注册的扩展名提供额外的链接. 以下是一个EchoMudule如何注册它自己的链接 在这个特定的组件中,在一个专用的帮助下 `registerContextualAppLink()` 函数 : ```ts // Register a simple, icon button component. // It will handle simple linking to your app with the given tag. export function setup(api: EchoModuleApi): void { api.registerPage('/myEchoModule', MyEchoModule); api.registerContextualAppLink({ label: 'Open in Awesome Echo App', iconName: 'rotate_3d' // accepts EDS icon names }); } // For more complex scenarios: Register a custom button component, which uses it's own logic to navigate to your app. import { MyCustomLinkButton } from './MyCustomLinkButton'; export function setup(api: EchoModuleApi): void { api.registerPage('/myEchoModule', MyEchoModule); api.registerContextualAppLink({ component: MyCustomLinkButton }); } ``` 以上延伸部分用于: `ContextualAppLinks` 组件,可在 [回声框架](https://github.com/equinor/EchoFramework)检查出来 了解更多它! 通过使用 `registerApp` 结束 `AppOptions` 或使用 `setup` 函数, `EchoModuleApi`数字 : ```ts export function setup(api: EchoModuleApi): void { api.registerPage('/myEchoModule', MyEchoModule); api.registerExtension({ key: 'unique-key', extends: 'PredifenedComponentName', component: MyCustomExtensionComponent, options: { // custom options used by the extendable component listOfUsers: [ 'Mary Sue', 'John Doe' ] isApproved: false, ... } }) } ``` 每个可扩展组件都以独特的方式使用它: 如果您想要使用 `registerExtension()` 函数,确保您熟悉所需的 `options` 用于特定可扩展组件. 一个组件可以拥有任意数量的扩展. 这个 `useExtensions()` 钩子可以帮助您获取特定组件的所有注册扩展名 . 扩展存储于 `GlobalState.registry.extensions`· ; ### 注册页/ 路由 在车盖下 `registerRoute` 这是什么 `registerApp`, (中文(简体) ), `registerAppWithKey`,以及 `registerPage`,用于. app只是一条附加组件的路由. `registerPag` 可用于注册不需要直接连接的页面. ```Typescript import { EchoModuleApi, PanelType } from "@equinor/echo-core" import { Icon, themeConst } from '@equinor/echo-components'; import TestModule from "./testModule"; import Panel from "./panel"; export function setup(api: EchoModuleApi): void { const icon = (): JSX.Element => ; api.registerApp(TestModule, { homeScreen: true, panels: { component: Panel, key: 'test', icon, label: 'test', panelType: PanelType.left } }); } ``` ## 声明 上面的代码样本显示, `TestModule` 模块注册为应用程序。 该应用程序将注册一条路由,并使用模块 appManifest 链接此程序. 这里就是这种明显的例子. ```Typescript { name: 'Test', requireRef: '', key: 'test', shortName: 'test', path: '/test', fileUri: 'echo-test-module.js', version: '0.0.1', } ``` # 全球状态 全球状态用于应用相关数据. `Large data sets will slow down the performance of the application / client so keeping this to the minimum is key.` 让我们看看当前的全球状况. ```TS interface GlobalState { app: EchoAppState; modules: Array; coreComponents: EchoCoreComponents; registry: RegistryState; ui: Dict; userProfile?: User; userPhotoUrl?: string; legendOptions: LegendOptions; settings: Settings; plantsData: PlantsData; procosysProjectsData: ProcosysProjectsData; moduleState: EchoCustomState; moduleContext: ModuleContext; } ``` 有三节特别有趣 登记处, `moduleState` 财务报告和审定财务报表 `moduleContext`首先让我们看看模块状态和上下文. ## 模块状态/上下文 Echo核心提供了两种使用模块状态的方法. 第一种只使用模块状态的方法. 状态可以初始化并用 `useAppModuleState`。 。 。 . ```TS interface State { data: string name: string; lastName: string } const state = { data: "This is a module state", name: "Tom", lastName: "Jones" } // This will register the module state useAppModuleState(state); // To retrieve the module state with types one can write. const { name, lastName } = useAppModuleState(); ``` 有几种方法可以更新模块状态. ```TS const newState = { data: "using the updateModuleState will replace the current state"; name: "Tom", lastName: "Jones", } updateModuleState(newState); // This will update just the name property of the module State. updateSpecificModuleState("name", "John"); ``` ### 模块背景和状态 状态可以与上下文结合使用,上下文将整个应用程序包裹在一起 `EchoContent.tsx` 文件输入 `EchoFramework`编辑 `ModuleContextProvider` 提供 EchoCore 表格,将始终提供当前 `moduleState`。这将允许您使用正则反应上下文. `Use to communicate with panels and header!` ```TS import { ModuleContextProvider } from '@equinor/echo-core'; import React from 'react'; import { LayoutProps } from '../components'; import CorePanelLeft from '../components/panel/corePanelLeft'; import CorePanelRight from '../components/panel/corePanelRight'; interface CorePanelsProps { children: React.ReactNode; Legend?: React.FC; } export const EchoContent: React.FC = ({ children, Legend }: CorePanelsProps): JSX.Element => { return ( {children} {Legend && } ); }; ``` 可以通过使用 `registerModuleContext` echoCore 提供的函数. ## 注册国 这是用于注册应用组件的 Echo 全球应用子状态容器 。 这个状态是整个应用中最重要的状态,包含所有路线,面板和appLinks. 由于EchoCore的责任主要是为开发者提供登记和取回构成全球状态的信息的工具,即使用 `RegistryState` 可在 EchoFramework 文档中找到 [这里](https://github.com/equinor/EchoFramework) ## 分析 登录到应用程序 Insights . 运行本中的一般信息分析 [这里](https://github.com/equinor/Echo/blob/master/docs/client-analytics.md) 创建日志模块 : ```TS const analyticsLog = analytics.createAnalyticsModule("ep"); ``` 可选的静态事件或出错属性也可以被附加在所有事件或出错上,使用: ```TS const analyticsLog = analytics.createAnalyticsModule("ep", { staticEventProperties: {ver: 1.01}, staticErrorProperties: {ver: 1.01} }); ``` 日志事件 : ```TS analyticsLog.trackEvent(event: AnalyticsEvent) analyticsLog.trackEventBy(objectName: string, actionName: string, properties: AnalyticsPropertyTypes) analyticsLog.trackEventBy("Document", "Opened", {docNo: "abc123", fileId: 12345 }) ``` 应用程序 Insights 中的格式为: - 开口 目标 行动 - appId subMudule. (原始内容存档于2017-09-29). 对象. 行动 - (原始内容存档于2017-03-27). Ep.Pdf. 已打开 - eP. 文件。 已打开 - 页:1 查看器。 点击 Tag 错误记录通常不应直接调用 。 而不是使用 handleError(TODO - 当我们有 handleError in core) 来更新此文档, 它会报告错误以应用 Insight . ```TS analyticsLog.logError(error) ``` Echo-in Field 还应做一些配置,如设置用户、内置码和公司,每个事件都将提供这些配置. ```TS analyticsConfiguration ``` ## 处理错误 报告到应用程序的深入性 . 注册帮助函数 `errorHandler` 像这样: ```TS export const errorHandler = (exception: Error | BaseError): void => { EchoCore.handleErrors(exception, myModuleAnalyticsModule); }; ``` `BaseError` 扩展 `Error`,并建议使用 `Error` - 它能确保错误只记录一次以应用 Insights - 所有属性 `BaseError` 被登录到 AppInsights , 即使它们是私人的 - 它支持 `innerError`类型 `Error` 或者说 `Record` 使用 `toError` 将未知被捕获对象转换成正则错误对象的帮助器函数 . 建议延期 `BaseError`,并用额外的属性来装饰,如下例所见. 自定义错误和典型错误流的例子. ```TS export class PdfError extends BaseError { docNo: string; constructor(args: { message: string; docNo: string; innerError?: Error }) { super({ name: 'PdfError', message: args.message, innerError: args.innerError }); this.docNo = args.docNo; } } ... try { loadPdf(); } catch(error) { throw new PdfError({ message:"load pdf failed", docNo: "a-73", innerError: toError(error) }); } } ``` ## 旧的回声库 以历史原因保存. [https://github.com/equinor/ EchoCore (英语)](https://github.com/equinor/EchoCore) 在此之前, [https://github.com/equinor/ EchoFramework 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/equinor/EchoFramework) ## 常见问题 ### 如何安装 @equinor/echo-core？ 在项目目录运行 npm install @equinor/echo-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>= 19\.2\.4）、zustand（\>= 4\.4\.7 \< 5）、react-router-dom（\>= 6\.30\.3 \< 7）、@equinor/echo-base（\>= 7\.0\.0 \< 8\.0\.0）、@tanstack/react-query（\>= 5\.24\.1 \< 6）、@microsoft/microsoft-graph-types（2\.43\.1）、@microsoft/microsoft-graph-types-beta（0\.44\.0-preview）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @equinor/echo-core 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @equinor/echo-core 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @equinor/echo-core 可以商用吗？ @equinor/echo-core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @equinor/echo-core 的下载量有多少？ 根据 npm 官方下载统计，@equinor/echo-core 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,678 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @equinor/echo-core 还在维护吗？ 最新版本 7\.0\.0 发布于 2026/10/27（17 天前）；至今共发布 245 个版本，其中过去 12 个月发布了 36 个；首次发布于 2020/12/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。