jQuery中添加DOMContentLoaded监听后jqGrid无法正常加载

架构老林

2026-8-28

问题现象

jQuery前端开发场景下，jqGrid初始化逻辑不放入DOMContentLoaded事件回调时可正常加载，将初始化逻辑包裹在DOMContentLoaded事件监听回调中执行时，jqGrid加载失败，相关实现代码如下：

document.addEventListener("DOMContentLoaded", function() {
  $("#table").jqGrid({
    url: ROOT + 'PCM/DataToDisplayPCM',
    datatype: "JSON",
    height: 'auto',
    rowNum: 10,
    rowList: [10, 20, 30],
    colModel: [{
      name: 'ProdPriority',
      label: 'Priority',
      index: 'ProdPriority',
      width: 50
    }, {
      name: 'ProductCode',
      label: 'Product Code',
      index: 'ProductCode',
      width: 80
    }, {
      name: 'ProductName',
      label: 'Product Name',
      index: 'ProductName',
      width: 200
    }, {
      name: 'DIV',
      label: 'Division',
      index: 'Division',
      width: 60
    }, {
      name: 'Category',
      label: 'Categary',
      index: 'Category',
      width: 150
    }, {
      name: 'SubCategory',
      label: 'SubCategary',
      index: 'SubCategory',
      width: 150
    }, {
      name: 'Priority_1',
      label: 'Priority_1',
      index: 'Priority_1',
      width: 80
    }, {
      name: 'Priority1per',
      label: 'Priority_1%',
      index: 'Priority1per',
      width: 80
    }, {
      name: 'Priority_2',
      label: 'Priority_2',
      index: 'Priority_2',
      width: 80
    }, {
      name: 'Priority2per',
      label: 'Priority_2%',
      index: 'Priority2per',
      width: 80
    }, {
      name: 'Priority_3',
      label: 'Priority_3',
      index: 'Priority_3',
      width: 80
    }, {
      name: 'Priority3per',
      label: 'Priority_3%',
      index: 'Priority3per',
      width: 80
    }, ],
    pager: "#prowed1",
    sortname: 'P_CODE',
    viewrecords: true,
    sortorder: "desc"
  });
  
  jQuery("#table").jqGrid('navGrid', "#prowed1", {
    edit: false,
    add: false,
    del: false
  });
});

故障原因

时序冲突：老版本jqGrid内部已经封装了DOM就绪检测逻辑，会在自身检测到DOM加载完成后触发容器渲染、尺寸计算、pager绑定等流程。外层手动绑定原生DOMContentLoaded监听时，会和jqGrid内部的就绪队列产生时序错位：jqGrid内部回调先执行时，目标表格、分页容器的关联属性还没完成事件队列的前置校验，导致初始化拿不到正确DOM参数，直接渲染失败。
语法问题：贴出的代码里colModel配置数组最后一项多了冗余的末尾逗号，低版本IE环境下会直接抛出语法错误，阻断整个初始化脚本执行。
依赖加载问题：如果全局变量ROOT是在其他DOM就绪回调中才完成赋值，或者jQuery、jqGrid的脚本加载顺序排在初始化代码之后，也会触发初始化失败。

修复方案

替换就绪监听写法：直接用jQuery自带的DOM就绪回调包裹初始化逻辑，jqGrid作为jQuery生态插件，和jQuery内部的就绪队列时序完全兼容，是最稳定的写法，同时删掉colModel末尾的冗余逗号：

// 替换原生DOMContentLoaded监听
$(function() {
  $("#table").jqGrid({
    url: ROOT + 'PCM/DataToDisplayPCM',
    datatype: "JSON",
    height: 'auto',
    rowNum: 10,
    rowList: [10, 20, 30],
    colModel: [{
      name: 'ProdPriority',
      label: 'Priority',
      index: 'ProdPriority',
      width: 50
    }, {
      name: 'ProductCode',
      label: 'Product Code',
      index: 'ProductCode',
      width: 80
    }, {
      name: 'ProductName',
      label: 'Product Name',
      index: 'ProductName',
      width: 200
    }, {
      name: 'DIV',
      label: 'Division',
      index: 'Division',
      width: 60
    }, {
      name: 'Category',
      label: 'Categary',
      index: 'Category',
      width: 150
    }, {
      name: 'SubCategory',
      label: 'SubCategary',
      index: 'SubCategory',
      width: 150
    }, {
      name: 'Priority_1',
      label: 'Priority_1',
      index: 'Priority_1',
      width: 80
    }, {
      name: 'Priority1per',
      label: 'Priority_1%',
      index: 'Priority1per',
      width: 80
    }, {
      name: 'Priority_2',
      label: 'Priority_2',
      index: 'Priority_2',
      width: 80
    }, {
      name: 'Priority2per',
      label: 'Priority_2%',
      index: 'Priority2per',
      width: 80
    }, {
      name: 'Priority_3',
      label: 'Priority_3',
      index: 'Priority_3',
      width: 80
    }, {
      name: 'Priority3per',
      label: 'Priority_3%',
      index: 'Priority3per',
      width: 80
    }],
    pager: "#prowed1",
    sortname: 'P_CODE',
    viewrecords: true,
    sortorder: "desc"
  });
  
  $("#table").jqGrid('navGrid', "#prowed1", {
    edit: false,
    add: false,
    del: false
  });
});

检查依赖顺序：确保jQuery、jqGrid的JS和CSS文件在初始化脚本之前加载，ROOT全局变量在初始化逻辑执行前已完成赋值，不要出现依赖文件后置的情况。
不推荐的兼容写法：如果一定要使用原生DOMContentLoaded，可以在初始化逻辑前加100ms左右的延迟，错开jqGrid内部的就绪检测时机，但这种方式稳定性差，优先使用jQuery自带的就绪回调。

内容的提问来源于stack exchange，提问作者Baba Ranjith