ag-grid-react v32中替代废弃showLoadingOverlay的实现问题

ag-grid-react v32彻底废弃了showLoadingOverlay旧方法，同时移除了api.setGridOption接口，官方推荐的loading属性或API直接调用是正确方向，但需要避开几个常见坑：

1. 排查gridOptions的覆盖问题 #

如果你的gridOptions对象中手动设置了loading: false，会直接覆盖组件上的loading属性，导致配置不生效。请删除gridOptions中的loading字段：

// 错误示例：gridOptions会覆盖组件属性
const gridOptions = {
  loading: false, // 必须删除此行
  // 其他配置...
};

2. 用Grid API直接控制（替代已移除的setGridOption） #

v32中需通过api.showLoadingOverlay()和api.hideOverlay()直接控制遮罩，无需再调用已移除的setGridOption。修正你的useEffect逻辑：

useEffect(() => {
  const gridApi = gridRef.current?.api;
  if (!gridApi) return;

  if (loading) {
    gridApi.showLoadingOverlay();
  } else {
    gridData.length ? gridApi.hideOverlay() : gridApi.showNoRowsOverlay();
  }
}, [loading, gridData.length]);

3. 移除不必要的setTimeout #

你的代码中加入的延迟会导致状态不同步，ag-grid的API可直接在useEffect中调用。若需确保Grid完全初始化，可通过onGridReady事件绑定API：

const onGridReady = (params) => {
  // 可选：将API保存到state，避免重复从ref获取
  setGridApi(params.api);
};

// 组件中绑定事件
<AgGridReact
  ref={gridRef}
  rowData={gridData}
  columnDefs={customColumnDef}
  onGridReady={onGridReady}
  // 若用属性绑定loading，确保gridOptions无冲突配置
  loading={loading}
/>

4. 无需额外配置默认Overlay #

ag-grid默认启用了加载和无数据遮罩组件，若未自定义Overlay，无需额外注册。

完整修正代码示例 #

import { useEffect, useRef, useState } from 'react';
import { AgGridReact } from 'ag-grid-react';
import 'ag-grid-community/styles/ag-grid.css';
import 'ag-grid-community/styles/ag-theme-alpine.css';

const MyGrid = ({ loading, gridData, customColumnDef }) => {
  const gridRef = useRef(null);
  const [gridApi, setGridApi] = useState(null);

  const onGridReady = (params) => {
    setGridApi(params.api);
  };

  useEffect(() => {
    if (!gridApi) return;

    if (loading) {
      gridApi.showLoadingOverlay();
    } else {
      gridData.length ? gridApi.hideOverlay() : gridApi.showNoRowsOverlay();
    }
  }, [loading, gridData.length, gridApi]);

  return (
    <div className="ag-theme-alpine" style={{ height: 400 }}>
      <AgGridReact
        ref={gridRef}
        rowData={gridData}
        columnDefs={customColumnDef}
        onGridReady={onGridReady}
        loading={loading}
      />
    </div>
  );
};

export default MyGrid;

核心注意事项 #

• v32中不存在setGridOption方法，直接使用showLoadingOverlay/hideOverlayAPI
• 组件loading属性与API调用二选一即可，避免混用导致状态冲突
• 禁止在gridOptions中设置loading字段，否则会覆盖组件配置

内容的提问来源于stack exchange，提问作者k-wasilewski