在企业级数据表格里，Ag-Grid凭借虚拟滚动和复杂列模型被广泛使用，但有时产品需求会要求行拖拽排序，而团队又希望沿用jQuery UI Sortable的交互习惯。直接把Sortable初始化到Ag-Grid的行容器上，往往会出现拖拽助手样式残缺、占位符高度塌陷、排序后网格视图不更新甚至行元素错位等问题。下面从现象出发，拆解Ag-Grid的行渲染机制与Sortable假设之间的冲突，并给出可落地的自定义渲染方案。

一、问题的典型表现与直接诱因

在Ag-Grid中嵌入jQuery UI Sortable后，最常见的异常是拖拽时克隆出来的行宽度只有内容宽度，高度丢失，背景变成透明，或者拖拽助手与鼠标位置出现较大偏移。占位符有时完全不显示，有时高度为0，导致拖拽过程中其他行没有让位，整个布局看起来非常奇怪。更严重的情况是拖拽结束后Ag-Grid没有按新的DOM顺序更新数据，页面刷新后又回到原顺序。

直接诱因并不复杂。Ag-Grid为了提高大数据量下的渲染性能，采用了行虚拟化和CSS transform定位。行元素并不是简单地按照文档流从上到下排列，而是通过<div>容器配合translateY偏移来绘制可视区域内的行。jQuery UI Sortable默认的helper克隆逻辑只会复制原始DOM节点，很多依赖Ag-Grid内部类名和行内样式的视觉效果在这个过程中会丢失。同时Sortable默认的占位符使用绝对定位，而Ag-Grid的行容器高度由内部行撑起，绝对定位的占位符不参与布局计算，自然无法让后续行正确让位。

还有一个容易忽略的点：Ag-Grid虚拟滚动只渲染可视区域附近的行，DOM中并不存在所有数据行。Sortable计算索引时依赖容器内的DOM顺序，这导致排序结束后得到的索引只在当前渲染窗口中有效，不能直接作为整个数据集的全局索引使用。若不做数据映射，就会造成数据错位或丢失。

二、理解Ag-Grid的行渲染机制与Sortable假设冲突

Ag-Grid的表格主体结构通常包含bodyViewport、bodyContainer以及内部的行组件。滚动时Ag-Grid会复用已有行元素，通过改变transform值模拟行在列表中的位置。也就是说，你在DOM里看到的行节点，其物理顺序并不一定代表数据顺序。而jQuery UI Sortable从设计上就假设排序项全部存在于一个连续的容器中，拖拽过程通过交换DOM位置来反映新顺序。这是两层机制的根本矛盾。

当用户拖拽某一行经过其他行时，Sortable的placeholder会尝试插入到某个DOM位置，但Ag-Grid行元素的定位并不依赖于普通流式布局。如果placeholder没有高度，或者helper没有正确设置position属性，Sortable就难以计算出正确的插入点。此外，Ag-Grid行在拖拽过程中如果发生滚动，被拖拽的行节点可能被Ag-Grid回收或替换，导致Sortable持有的item引用失效，最终引发各种怪异行为。

所以要解决自定义渲染问题，不能仅仅依靠几个CSS补丁，而是要同时处理三个层面：拖拽过程中的视觉呈现、占位符的布局占位，以及拖拽结束后从DOM顺序到数据源顺序的可靠映射。

三、自定义helper与占位符，解决渲染错位

拖拽过程中的视觉呈现可以通过重写Sortable的helper函数来修复。在helper函数中克隆原始行节点后，需要重新设置宽度、高度、背景色、边框和阴影，确保助手看起来像一条完整的表格行，而不是一段被压缩的文本。下面这段代码展示了如何恢复基础视觉样式：

helper: function(event, item) {
  var original = $(item);
  var helper = original.clone();
  helper.css({
    width: original.width(),
    height: original.height(),
    background: '#ffffff',
    border: '1px solid #1890ff',
    'z-index': 9999,
    'box-shadow': '0 4px 12px rgba(0,0,0,0.15)',
    'box-sizing': 'border-box'
  });
  return helper;
}

占位符的样式则通过Sortable的placeholder选项结合自定义CSS类实现。关键是要使用forcePlaceholderSize强制占位符参与布局，并给它设置一个与Ag-Grid行高一致的固定高度。例如行高为35像素时，CSS可以写成：

.ag-row-sortable-placeholder {
  background: #e6f7ff;
  border: 1px dashed #1890ff;
  height: 35px;
  box-sizing: border-box;
}

在初始化Sortable时，将placeholder设置为这个类名，并开启forcePlaceholderSize。这样拖拽经过其他行时，占位符会撑开真实空间，后续行会自然下移，视觉上符合预期。另一个细节是拖拽开始时给原行添加一个半透明类，避免原始位置和helper同时显示造成重叠感。

四、实现排序数据更新：从DOM顺序回到数据源

拖拽结束后，必须把新的顺序同步到Ag-Grid的数据模型中。如果直接使用ui.item.index()作为全局目标索引，在虚拟滚动下会出错。更稳妥的做法是维护一个完整的数据数组，拖拽开始时记录被拖拽行对应的数据对象唯一ID，在update事件里根据目标位置相邻行的数据定位插入点。

下面是一个基于外部数据数组的更新示例。gridOptions初始化时传入rowData，Sortable的update回调中先获取所有当前数据，再根据DOM中目标位置找到相邻数据对象，计算全局索引，最后调用setRowData刷新网格：

var allData = [
  { id: 1, name: 'Row 1', value: 10 },
  { id: 2, name: 'Row 2', value: 20 },
  { id: 3, name: 'Row 3', value: 30 }
];
$('#myGrid .ag-body-container').sortable({
  items: '.ag-row',
  handle: '.drag-handle',
  helper: function(event, item) {
    var original = $(item);
    var helper = original.clone();
    helper.css({
      width: original.width(),
      height: original.height(),
      background: '#fff',
      border: '1px solid #1890ff',
      'z-index': 9999,
      'box-shadow': '0 4px 12px rgba(0,0,0,0.15)',
      'box-sizing': 'border-box'
    });
    return helper;
  },
  placeholder: 'ag-row-sortable-placeholder',
  forcePlaceholderSize: true,
  start: function(event, ui) {
    var rowId = ui.item.attr('row-id');
    ui.item.data('dragRowId', rowId);
    ui.item.addClass('ag-row-dragging');
  },
  update: function(event, ui) {
    var dragRowId = ui.item.data('dragRowId');
    var targetRow = ui.item.next();
    var targetRowId = targetRow.attr('row-id');
    var dragIndex = -1;
    var targetIndex = -1;
    for (var i = 0; i < allData.length; i++) {
      if (allData[i].id == dragRowId) {
        dragIndex = i;
      }
      if (targetRowId && allData[i].id == targetRowId) {
        targetIndex = i;
      }
    }
    if (dragIndex !== -1) {
      var movedData = allData.splice(dragIndex, 1)[0];
      if (targetIndex === -1) {
        allData.push(movedData);
      } else {
        allData.splice(targetIndex, 0, movedData);
      }
      gridOptions.api.setRowData(allData);
    }
  }
});

这个示例中，行元素上需要挂载row-id属性，可以在Ag-Grid的rowData映射时通过cellRenderer或rowClassRules添加，也可以在gridOptions的onRowDataUpdated里统一设置。对于复杂表格，建议使用数据的业务主键而不是数组索引来做定位，这样可以避免虚拟滚动下索引漂移的问题。

除了setRowData，也可以使用applyTransaction进行更精细的更新，但顺序调整并不是简单的单元格更新，直接替换整个rowData数组通常更清晰。数据量很大时，可以维护一个排序后的数据源，拖拽结束后只替换变化的部分，但这样会增加额外复杂度，需要根据实际规模权衡。

五、应对Ag-Grid虚拟滚动与性能优化

当数据量达到数千甚至数万行时，拖拽过程中的性能会很敏感。Sortable的helper克隆如果包含大量DOM子节点，会影响拖拽流畅度。可以在helper函数中对克隆节点做简化，比如去掉不需要的事件监听和隐藏内部组件，只保留必要的行内容。另外，拖拽开始时可以暂时阻止Ag-Grid继续回收或复用行，例如通过标记一个布尔变量，在Ag-Grid的rowRenderer刷新逻辑里做判断，拖拽结束后恢复。

对于自动滚动，jQuery UI Sortable默认支持在容器边缘滚动，但Ag-Grid的滚动容器可能不是Sortable初始化时使用的那个元素。此时需要把Sortable的scroll选项指向正确的滚动容器，或者将appendTo设置为一个靠近body的容器，避免被Ag-Grid的overflow裁剪。如果拖拽到可视区域之外，最好限制拖拽结束位置必须在可视区域内，否则数据映射前后的相邻行无法准确获取。

还需要注意销毁和事件清理。组件卸载或表格重建时，要调用sortable('destroy')移除Sortable实例，同时移除自定义CSS类和相关事件监听，避免内存泄漏和重复绑定。如果页面上存在多个Ag-Grid实例，每个表格的Sortable初始化都应使用独立的选择器，不要复用同一个容器引用。

六、完整集成示例与关键注意事项

下面给出一个整合后的HTML片段，展示如何初始化Ag-Grid并绑定jQuery UI Sortable。为清晰起见，代码中使用了Ag-Grid社区版的类名和基础的列定义：

<div id="myGrid" class="ag-theme-alpine" style="height: 400px; width: 600px;"></div>
<style>
  .ag-row-sortable-placeholder {
    background: #e6f7ff;
    border: 1px dashed #1890ff;
    height: 35px;
    box-sizing: border-box;
  }
  .ag-row-dragging {
    opacity: 0.4;
  }
</style>
<script>
  var gridOptions = {
    columnDefs: [
      { field: 'id', headerName: 'ID', width: 80 },
      { field: 'name', headerName: 'Name', width: 200 },
      { field: 'value', headerName: 'Value', width: 120 }
    ],
    rowData: [
      { id: 1, name: 'Row 1', value: 10 },
      { id: 2, name: 'Row 2', value: 20 },
      { id: 3, name: 'Row 3', value: 30 }
    ],
    rowHeight: 35,
    suppressRowDrag: true
  };
  var eGridDiv = document.querySelector('#myGrid');
  new agGrid.Grid(eGridDiv, gridOptions);
  $('#myGrid .ag-body-container').sortable({
    items: '.ag-row',
    handle: '.drag-handle',
    helper: function(event, item) {
      var original = $(item);
      var helper = original.clone();
      helper.css({
        width: original.width(),
        height: original.height(),
        background: '#fff',
        border: '1px solid #1890ff',
        'z-index': 9999,
        'box-shadow': '0 4px 12px rgba(0,0,0,0.15)',
        'box-sizing': 'border-box'
      });
      return helper;
    },
    placeholder: 'ag-row-sortable-placeholder',
    forcePlaceholderSize: true,
    start: function(event, ui) {
      var rowId = ui.item.attr('row-id');
      ui.item.data('dragRowId', rowId);
      ui.item.addClass('ag-row-dragging');
    },
    update: function(event, ui) {
      // 此处实现数据源顺序调整，具体逻辑参考上一节示例
    }
  });
</script>

实际落地时还要注意几个点。首先，Ag-Grid不同版本的内部DOM类名可能存在差异，例如旧版本使用ag-body-container，新版本可能仍然沿用，但企业版或主题不同时结构会有调整，需要根据实际调试确认。其次，不要同时启用Ag-Grid原生的rowDragManaged和jQuery UI Sortable，否则两个拖拽系统会互相干扰，导致事件冲突。最后，如果表格列可横向滚动，自定义helper的宽度最好取原始行宽度并固定，避免拖拽时宽度随滚动容器变化。

通过重写helper与placeholder、在拖拽结束后基于数据唯一ID做映射、并针对虚拟滚动做索引矫正，可以稳定解决jQuery UI Sortable在Ag-Grid里的行拖拽自定义渲染问题。这个方案兼顾了交互习惯和Ag-Grid的高性能渲染，适合需要在复杂表格中快速实现行排序的场景。