React+TypeScript项目中AgGridReact提示不存在api属性问题排查

问题核心原因 #

你遇到的报错本质是两种情况触发的TypeScript类型校验异常：

1. useRef 初始化时传了null，TS默认会认为gridRef.current可能为null，部分场景下会把空值校验的异常误判为属性不存在
2. 你使用的ag-grid版本的类型导出存在兼容问题，组件对外暴露的api属性没有被TS正确识别

可行解决方法 #

按优先级从高到低排列：

• 方法1：先做空值判断，完全符合TS语法规范，无类型降级风险

// 只有grid实例存在时才调用api
if (gridRef.current) {
  const selectedNodes: RowNode[] = gridRef.current.api.getSelectedNodes();
}

• 方法2：如果你能保证调用这段代码的时机是在grid组件渲染完成之后（比如用户点击事件、onGridReady回调触发后），可以直接用非空断言跳过空值校验

const selectedNodes: RowNode[] = gridRef.current!.api.getSelectedNodes();

• 方法3：如果上述操作还是报错，直接显式声明ref类型，绕开组件导出的类型定义

import type { GridApi, ColumnApi, RowNode } from 'ag-grid-community';

// 直接声明ref包含你需要的api属性即可
const gridRef = useRef<{ api: GridApi; columnApi: ColumnApi } | null>(null);

最佳实践 #

建议优先通过onGridReady事件获取api实例，不需要依赖ref也可以避免空值问题：

const onGridReady = (params: { api: GridApi; columnApi: ColumnApi }) => {
  // 这里的api已经完成初始化，可直接调用
  const selectedNodes = params.api.getSelectedNodes();
}

// 组件绑定事件
<AgGridReact onGridReady={onGridReady} {/* 其他配置项 */} />

内容的提问来源于stack exchange，提问作者Royi Levy