如何实现带有动画效果的DOM元素交换？

问题背景 #

在实现跨父节点的DOM元素交换时，我尝试了两种常见方案：

方案1：使用占位符节点交换 #

swap1(a,b) 
{
    const aParent = a.parentNode;
    const bParent = b.parentNode;

    var aHolder = document.createElement("div");
    var bHolder = document.createElement("div");

    aParent.replaceChild(aHolder,a);
    bParent.replaceChild(bHolder,b);
    aParent.replaceChild(b,aHolder);
    bParent.replaceChild(a,bHolder);
}

方案2：直接插入调整位置 #

swap2(a,b) 
{
    const parent1 = a.parentNode;
    const parent2 = b.parentNode;
    var next2 = b.nextSibling;
    // special case for a is the next sibling of b
    if (next2 === a) {
        // just put a before b
        parent2.insertBefore(a, b);
        Draggable.log('next sibling');
    } else {
        // insert b right before a
        parent1.insertBefore(b, a);
        // now insert obj1 where obj2 was
        if (next2) {
         // if there was an element after b, then insert a right before that
            parent2.insertBefore(a, next2);
        } else {
            // otherwise, just append as last child
            parent2.appendChild(a);
        }
    }
}

这两种方法在无动画场景下正常，但为元素添加动画后，频繁出现"Node.replaceChild: Child to be replaced is not a child of this node"这类DOM操作错误。尝试用多层setTimeout(0)延迟操作效果不佳，设置长超时又会导致DOM长时间处于混乱状态，且作为库代码无法预知动画时长。

解决方案 #

错误根源 #

动画（尤其是拖拽、过渡类动画）会异步修改元素的DOM状态，比如临时改变父节点、克隆元素或修改布局，导致执行交换时元素的实际父节点与预先获取的不一致，触发DOM操作错误。setTimeout(0)仅能延迟宏任务，无法等待动画的渲染周期或微任务完成，因此无效。

方案1：等待动画结束后执行DOM交换 #

通过监听transitionend/animationend事件，确保元素动画完全结束后再执行交换操作，同时兼容无动画的场景：

function waitForAnimationEnd(element) {
  return new Promise((resolve) => {
    const handleEnd = (event) => {
      if (event.target === element) {
        element.removeEventListener('transitionend', handleEnd);
        element.removeEventListener('animationend', handleEnd);
        resolve();
      }
    };
    element.addEventListener('transitionend', handleEnd);
    element.addEventListener('animationend', handleEnd);
    
    // 无动画时直接resolve
    const computedStyle = getComputedStyle(element);
    if ((!computedStyle.transitionDuration || computedStyle.transitionDuration === '0s') &&
        (!computedStyle.animationDuration || computedStyle.animationDuration === '0s')) {
      resolve();
    }
  });
}

async function swapAfterAnimation(a, b) {
  // 等待两个元素的所有动画结束
  await Promise.all([waitForAnimationEnd(a), waitForAnimationEnd(b)]);
  
  // 执行安全的交换逻辑（复用swap2的优化版）
  const parent1 = a.parentNode;
  const parent2 = b.parentNode;
  const next2 = b.nextSibling;

  if (!parent1 || !parent2) return;

  if (next2 === a) {
    parent2.insertBefore(a, b);
  } else {
    parent1.insertBefore(b, a);
    next2 ? parent2.insertBefore(a, next2) : parent2.appendChild(a);
  }
}

方案2：视觉模拟交换，延迟DOM操作 #

如果需要在动画过程中呈现交换效果，先通过CSS transform模拟位移动画，等视觉动画结束后再真正交换DOM结构，避免中间DOM操作冲突：

function swapSmoothly(a, b) {
  // 获取元素当前位置与尺寸
  const rectA = a.getBoundingClientRect();
  const rectB = b.getBoundingClientRect();
  
  // 计算位移差值
  const deltaX = rectB.left - rectA.left;
  const deltaY = rectB.top - rectA.top;
  
  // 临时固定元素位置，开启过渡动画
  [a, b].forEach(el => {
    const rect = el.getBoundingClientRect();
    el.style.position = 'fixed';
    el.style.left = `${rect.left}px`;
    el.style.top = `${rect.top}px`;
    el.style.width = `${rect.width}px`;
    el.style.height = `${rect.height}px`;
    el.style.transition = 'transform 0.3s ease';
    el.style.zIndex = '9999';
  });
  
  // 触发重绘，确保过渡生效
  void a.offsetWidth;
  
  // 应用位移，模拟交换视觉效果
  a.style.transform = `translate(${deltaX}px, ${deltaY}px)`;
  b.style.transform = `translate(${-deltaX}px, ${-deltaY}px)`;
  
  // 动画结束后执行真正的DOM交换
  const handleAnimationEnd = async () => {
    a.removeEventListener('transitionend', handleAnimationEnd);
    b.removeEventListener('transitionend', handleAnimationEnd);
    
    await Promise.all([waitForAnimationEnd(a), waitForAnimationEnd(b)]);
    
    // 执行DOM交换
    const parent1 = a.parentNode;
    const parent2 = b.parentNode;
    const next2 = b.nextSibling;

    if (!parent1 || !parent2) return;

    if (next2 === a) {
      parent2.insertBefore(a, b);
    } else {
      parent1.insertBefore(b, a);
      next2 ? parent2.insertBefore(a, next2) : parent2.appendChild(a);
    }
    
    // 恢复元素原有样式
    ['position', 'left', 'top', 'width', 'height', 'transition', 'transform', 'zIndex'].forEach(prop => {
      a.style.removeProperty(prop);
      b.style.removeProperty(prop);
    });
  };
  
  a.addEventListener('transitionend', handleAnimationEnd);
  b.addEventListener('transitionend', handleAnimationEnd);
  
  // 复用waitForAnimationEnd函数
  function waitForAnimationEnd(element) {
    return new Promise((resolve) => {
      const handleEnd = (event) => {
        if (event.target === element) {
          element.removeEventListener('transitionend', handleEnd);
          element.removeEventListener('animationend', handleEnd);
          resolve();
        }
      };
      element.addEventListener('transitionend', handleEnd);
      element.addEventListener('animationend', handleEnd);
      const computedStyle = getComputedStyle(element);
      if ((!computedStyle.transitionDuration || computedStyle.transitionDuration === '0s') &&
          (!computedStyle.animationDuration || computedStyle.animationDuration === '0s')) {
        resolve();
      }
    });
  }
}

方案3：操作前校验DOM状态 #

作为兜底方案，在执行交换前再次校验元素的父节点归属，避免因动画导致的DOM状态异常：

function swapSafe(a, b) {
  const parent1 = a.parentNode;
  const parent2 = b.parentNode;
  
  // 校验元素是否仍在预期的父节点中
  if (!parent1 || !parent2 || !parent1.contains(a) || !parent2.contains(b)) {
    console.warn('DOM状态已变更，无法执行交换');
    return;
  }
  
  const next2 = b.nextSibling;
  
  if (next2 === a) {
    parent2.insertBefore(a, b);
  } else {
    parent1.insertBefore(b, a);
    next2 ? parent2.insertBefore(a, next2) : parent2.appendChild(a);
  }
}

选择建议 #

• 如果不需要实时视觉过渡，方案1最简单可靠，确保DOM操作在动画完成后执行；
• 如果需要平滑的视觉交换效果，方案2是最优选择，分离视觉动画与DOM操作，避免冲突；
• 方案3可作为前两种方案的补充，增加操作的安全性。

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