# @equinor/fusion-framework-module-ag-grid 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-module-ag-grid/

版本：37\.2\.0
npm 元数据更新时间：2026-11-12T09:54:56.771Z
中文译文更新时间：2026-11-13T20:46:19.777Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-module-ag-grid
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-module-ag-grid/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：636 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：ag-grid-community \>=36\.0\.0，ag-grid-enterprise \>=36\.0\.0，@equinor/eds-tokens ^2\.0\.0，@equinor/fusion-framework-module ^6\.2\.0，@equinor/fusion-framework-module-telemetry ^8\.0\.0
- 首次发布：2022-06-23T08:52:55.345Z
- 最新版本发布：2026-11-12T09:54:56.398Z
- 近 30 天下载量：5065（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：133（近 12 个月 27 个）

## 中文简介

使用 AG 网格的聚合模块

## 安装

```sh
npm install @equinor/fusion-framework-module-ag-grid
```

也可以使用：`pnpm add @equinor/fusion-framework-module-ag-grid`、`yarn add @equinor/fusion-framework-module-ag-grid`、`bun add @equinor/fusion-framework-module-ag-grid`

## README

# AG 融合框架网格模块

`@equinor/fusion-framework-module-ag-grid` 提供包围 [AG 网格](https://www.ag-grid.com/) 拥有集中式许可证钥匙管理、单元和模块登记. 它确保每个Fusion门户网站和应用程序使用一致的AG Grid设置.

## 何时使用此软件包

-   **门户主机** ——一旦配置 AG Grid 许可证密钥和默认主题, 所有的孩子应用程序都会继承它们 .
-   **应用程序** ——注册每个应用程序所需的AG Grid特性模块(row models,工具板,导出等),以便通过树摇来保持小捆绑.

> \[TIP\] 这是 **基础** 软件包。 两者 `ag-grid-community` 财务报告和审定财务报表 `ag-grid-enterprise` 需要同伴依赖关系. 特定反应钩和组件见 [`@equinor/fusion-framework-react-ag-grid`](https://www.npmjs.com/package/@equinor/fusion-framework-react-ag-grid)。 。 。 .

## 安装

```sh
pnpm add @equinor/fusion-framework-module-ag-grid
```

> \[尖叫声\] Fusion将尝试保持语义学主要版本和小版本与AG Grid同步,但可能存在无法实现的情况. 这么说吧 `@equinor/fusion-framework-module-ag-grid` 财务报告和审定财务报表 `ag-grid` 可能不一样 **补丁** 各个版本.

> \[大 **v35 突破变化**: AG 图表已移动到单独的软件包 `@equinor/fusion-framework-react-ag-charts`。如果需要集成图表,则同时安装软件包和使用 `IntegratedChartsModule.with(AgChartsEnterpriseModule)`。 。 。 .
> 
> 在升级到 AG Grid 33 之前, 删除所有先前的引用 `@equinor/fusion-react-ag-grid-styles`, (中文(简体) ), `@ag-grid-community/*` 财务报告和审定财务报表 `@ag-grid-enterprise/*` 从您的项目依赖关系.

## 快开始

在门户或应用程序配置中注册模块 `enableAgGrid`数字 :

```ts
import { type FrameworkConfigurator } from '@equinor/fusion-framework';
import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';

export async function configure(config: FrameworkConfigurator) {
    enableAgGrid(config, (builder) => {
        builder.setLicenseKey('your-license-key');
    });
}
```

这个 `enableAgGrid` 帮助者接受可选的回调,接收 `IAgGridConfigurator` 建会者. 用它来设置许可证密钥,主题和特性模块.

## 他们

此模块使用 `alpine` 主题作为基础 [aG 网格主题](https://www.ag-grid.com/react-data-grid/theming/)。 。 。 . 主题可以通过在应用程序中提供自定义主题来定制.

> \[TIP\] AG网格有一个 [主题构建器](https://www.ag-grid.com/theme-builder/) 用于预览和生成自定义主题.

```ts
enableAgGrid(configurator, (builder) => {
    builder.setTheme((theme) => {
        return theme.withParams({
            backgroundColor: "#1f2836",
            browserColorScheme: "dark",
            chromeBackgroundColor: {
                ref: "foregroundColor",
                mix: 0.07,
                onto: "backgroundColor"
            },
            foregroundColor: "#FFF",
            headerFontSize: 14
        });
    });
});
```

> \[大 主题默认继承自母范围(aka porters). 这意味着门户中设定的主题会被应用程序所继承.
> 
> **注:** 配置的主题是全局的,将影响应用程序中AG Grid的所有实例.

### 自定义网格实例

该模块提供了一个自定义网格实例的钩子.

```tsx
import { useTheme } from '@equinor/fusion-framework-react-ag-grid';

const MyComponent = () => {
    const baseTheme = useTheme();
    const [hasError, setHasError] = useState(false);
    const theme = useMemo(() => baseTheme.withParams({
        // add red text color if error
        cellTextColor: hasError ? "#FF0000" : baseTheme.cellTextColor,
    }), [baseTheme, hasError]);

    return (
        <AgGridReact
            theme={theme}
            ...
        />
    );
};
```

## 注册 AG Grid 特性模块

由于AG Grid 33,功能模块必须明确注册,因此树摇可以去除未使用的代码. 使用 `builder.addModule()` 或者说 `builder.setModules()` 内部 `enableAgGrid` 回调 :

```ts
import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';
import { ClientSideRowModelModule } from 'ag-grid-community';
import {
    ClipboardModule,
    ColumnsToolPanelModule,
    ExcelExportModule,
    FiltersToolPanelModule,
    MenuModule,
} from 'ag-grid-enterprise';

export const configure: AppModuleInitiator = (configurator, { env }) => {
    enableAgGrid(configurator, (builder) => {
        builder.setModules([
            ClientSideRowModelModule,
            ClipboardModule,
            ColumnsToolPanelModule,
            ExcelExportModule,
            FiltersToolPanelModule,
            MenuModule,
        ]);
    });
};
```

> \[大 模块 **必须** 注册在配置中,以便进行适当的树摇动。 只导入你需要的东西.

## 主要出口

| 导出 | 目的 |
| --- | --- |
| `enableAgGrid` | 用聚合配置器注册 AG 网格模块 |
| `AgGridConfigurator` | 配置构建器( 许可证密钥、 主题、 模块) |
| `AgGridProvider` | 显示解析配置的运行时间提供者 |
| `fusionTheme` | 默认 Equinor- Branded AG 网格主题(来自 `./themes`(中文(简体) ) |
| `createThemeFromTheme` | 切换主题以避免交叉文字 `instanceof` 问题 `./themes`(中文(简体) ) |

## API 参考

### `enableAgGrid(configurator, callback?)`

注册 AG 网格模块。 可选回调收到 `IAgGridConfigurator`数字 :

-   `setLicenseKey(key)` 确定企业许可证钥匙
-   `setTheme(theme | callback | null)` 设置、定制或清除全球主题
-   `setModules(modules)` - 替换所有已注册的 AG 网格模块
-   `addModule(module)` - 附加单个模块
-   `removeModule(module | name)` ——通过引用或名称删除模块

### 主题继承

在父范围(portal)中配置的主题由子范围(应用程序)自动继承. 模块克隆通过 `createThemeFromTheme` 为避免 `instanceof` 跨模块组合边界不匹配 .

### 遗产 `add()` 相容遥测

`IAgGridProvider` 扩展 `TelemetryConnectable`。供应商获得其共享的手柄 结束 `telemetry.scope('ag-grid')`随着一个懒惰的工厂倒置 旧的定制供应商, 和断开 被撕成两半 shim及其一通知观察预算不变.

提供者补丁了遗产 `Set`\- 风格 `add()` 输入 AG 网格共享 `Map`\- 形状 `agStyleInjectionState.grids` 当它不见了, 所以为旧的 AG Grid 所建的捆绑 工作时 当主机有遥测模块时,第一个呼叫补丁 `add()` 内 每个主机的寿命周期都发出一个 `fusion.ag-grid.legacy-add` 活动 `Warning` 职等,与 标准业务 `diagnostic` 信封上写着 仅安装补丁没有记录 .

该事件没有网格密钥、 DOM 引用或主题数据, 且补丁 `add()` 保留 它的行为: 它设置关键 `true` 并返回地图,即使遥测失败。 无 遥测,或者在模块被处理后,没有任何记录. 使用事件查找主机 仍然依赖遗产的形状 在清除shim之前。 补丁的一页 无法观察到由更古老的 Fusion AG Grid 版本所安装.

## 测试

没有许可证密钥, AG Grid Entertainment 登录一个"License Key Not found" 横幅通过 `console.error` 每个网格挂载,在测试中预计会出现这种情况,但在记者产出中却掩盖了真正的断言失败. 打电话 `suppressAgGridLicenseBanner` 一次从测试设置文件中过滤到这个横幅:

```ts
// src/test/setupTests.ts
import { suppressAgGridLicenseBanner } from '@equinor/fusion-framework-module-ag-grid/testing';

suppressAgGridLicenseBanner();
```

> \[TIP\] 这只把旗帜藏在测试中. 要从运行中的应用程序中删除它, 请通过 `enableAgGrid`编号 :`setLicenseKey` 换句话说.

## 从AG Grid 32 迁移到33

AG Grid 33 将所有特性模块合并为单一 `ag-grid-community` 财务报告和审定财务报表 `ag-grid-enterprise` 软件包。 关键更改 :

-   删除全部 `@ag-grid-community/*` 财务报告和审定财务报表 `@ag-grid-enterprise/*` 依赖关系
-   删除 `@equinor/fusion-react-ag-grid-styles` ——样式被捆绑于v33+
-   明确通过 `builder.setModules()` 为正确的树摇摆

> \[大 读取 [AG 网格 v33 更改日志](https://www.ag-grid.com/changelog/) 升级前. 此外,开发人员还应参考AG Grid 官方升级指南 [升级到AG Grid 33](https://www.ag-grid.com/react-data-grid/upgrading-to-ag-grid-33/) 详细情况和最佳做法.

### 进口

**删除以下导入:**

-   `@ag-grid-community/*`
-   `@ag-grid-enterprise/*`

**替换为:**

-   `@equinor/fusion-framework-module-ag-grid`

### 模块

自AG Grid 33起,所有模块都被集成到一个单一的软件包中,这意味着模块需要在应用程序配置中被定义.

全部移动 `ModuleRegistry.registerModules` 改为 `builder.setModules` 在应用程序配置中.

```diff
// my-app/src/app.ts
- import { ClientSideRowModelModule } from '@ag-grid-community/client-side-row-model';
- import { ColumnsToolPanelModule } from '@ag-grid-enterprise/column-tool-panel';
- import { FiltersToolPanelModule } from '@ag-grid-enterprise/filter-tool-panel';
- import { MenuModule } from '@ag-grid-enterprise/menu';
- import { ExcelExportModule } from '@ag-grid-enterprise/excel-export';
- import { ClipboardModule } from '@ag-grid-enterprise/clipboard';
- import { RangeSelectionModule } from '@ag-grid-enterprise/range-selection';

- ModuleRegistry.registerModules([
-     ClientSideRowModelModule,
-     ColumnsToolPanelModule,
-     FiltersToolPanelModule,
-     MenuModule,
-     ExcelExportModule,
-     RangeSelectionModule,
-     ClipboardModule,
- ]);
// config.ts
+ import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';
+ import { ClientSideRowModelModule } from '@equinor/fusion-framework-module-ag-grid/community';
+ import {
+     ClipboardModule,
+     ColumnsToolPanelModule,
+     ExcelExportModule,
+     FiltersToolPanelModule,
+     MenuModule,
+ } from '@equinor/fusion-framework-module-ag-grid/enterprise';
  
  export const configure: AppModuleInitiator = (configurator, { env }) => {
+    enableAgGrid(configurator, (builder) => {
+        builder.addModules([
+            ClientSideRowModelModule,
+            ClipboardModule,
+            ColumnsToolPanelModule,
+            ExcelExportModule,
+            FiltersToolPanelModule,
+            MenuModule,
+        ]);
+    });
  };
```

## 常见问题

### @equinor/fusion-framework-module-ag-grid 是什么？

使用 AG 网格的聚合模块

### 如何安装 @equinor/fusion-framework-module-ag-grid？

在项目目录运行 npm install @equinor/fusion-framework-module-ag-grid，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ag-grid-community（\>=36\.0\.0）、ag-grid-enterprise（\>=36\.0\.0）、@equinor/eds-tokens（^2\.0\.0）、@equinor/fusion-framework-module（^6\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @equinor/fusion-framework-module-ag-grid 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @equinor/fusion-framework-module-ag-grid 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/fusion-framework-module-ag-grid 可以商用吗？

@equinor/fusion-framework-module-ag-grid 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @equinor/fusion-framework-module-ag-grid 的下载量有多少？

根据 npm 官方下载统计，@equinor/fusion-framework-module-ag-grid 在 2026/10/14 – 2026/11/12 这 30 天内被下载 5,065 次，日均约 169 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/fusion-framework-module-ag-grid 还在维护吗？

最新版本 37\.2\.0 发布于 2026/11/12（1 天前）；至今共发布 133 个版本，其中过去 12 个月发布了 27 个；首次发布于 2022/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。