萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery replaceAll() 方法詳解:以匹配元素替換目標的實戰指南

方法定位

.replaceAll() 使用 匹配集合中的元素 去 替換選擇器指定的目標元素。它是 .replaceWith() 的「反向操作」姊妹方法,功能完全等價,只是語法主賓倒置。

語法結構

$(newContent).replaceAll(targetSelector)
// newContent: 用於替換的內容(HTML 字串、DOM 元素、jQuery 物件)
// targetSelector: 被替換目標的選擇器

核心特性

  • 目標元素被移除:原目標元素及其所有後代從 DOM 樹中移除。
  • 新內容被複製:若 newContent 是現有元素,會被移動而非複製(同 .appendTo() 行為)。
  • 返回值:返回插入的新元素 jQuery 集合(非原目標)。
  • 事件處理器:目標元素的事件隨元素銷毀;新元素若為現有元素移動,其事件保留。

完整可運行範例

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>replaceAll 示例</title>
  <style>
    .box { width: 100px; height: 100px; margin: 10px; display: inline-block; text-align: center; line-height: 100px; font-weight: bold; color: #fff; }
    .old { background: #e74c3c; }  /* 紅 - 被替換目標 */
    .new { background: #27ae60; }  /* 綠 - 替換者 */
  </style>
  <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
</head>
<body>
  <p class="box old">舊段落 1</p>
  <p class="box old">舊段落 2</p>
  <p class="box old">舊段落 3</p>
  <br>
  <button id="btn-replace">用 div 替換所有 p.old</button>

  <script>
    $('#btn-replace').click(function() {
      // 用新建的 div 替換所有 class="old" 的 p
      $('<div class="box new">新 div 元素</div>').replaceAll('p.old');
    });
  </script>
</body>
</html>

replaceAll vs replaceWith 對照

維度.replaceAll(target).replaceWith(newContent)
調用主體 新內容 $(newContent) 被替換目標 $(target)
參數 目標選擇器 新內容
語義 「拿新的去換舊的」 「把舊的換成新的」
鏈式調用 返回新元素,可繼續操作新元素 返回原目標集合(已脫離 DOM),通常鏈式結束
適用場景 批量替換多個目標為同一新結構 單個目標替換為不同新內容

進階用法:克隆替換而非移動

// 若希望保留原 newContent 元素,需先 .clone()
var $template = $('#template-row'); // 頁面隱藏的模板行
$template.clone().replaceAll('.dynamic-row');
// 每次點擊都用克隆副本替換,模板保留原位

實際應用場景

  1. 列表行模板化渲染:AJAX 取數據後,用模板行 .clone() 替換佔位行。
  2. 載入狀態切換:$('<div class="loaded">內容</div>').replaceAll('.loading-placeholder');
  3. A/B 測試動態切換:根據實驗分組替換整個區塊組件。
  4. 舊版組件升級:不改 HTML 結構,直接用新組件替換舊組件掛載點。

注意事項

  • 若 targetSelector 匹配多個元素,同一個新內容實例會被依次移動到每個目標位置,最終只留在最後一個目標位置(因為元素不能同時存在多處)。批量替換請配合 .clone()。
  • 替換 <script> 標籤不會執行腳本,需手動 .eval() 或使用 .html() 重新注入。
  • 替換表單元素會丟失用戶輸入,若需保留請先序列化數據。

總結

.replaceAll() 提供了「以新換舊」的直觀語義,配合 .clone() 是批量 DOM 替換的標準模式。理解其與 .replaceWith() 的主賓關係差異,能讓你在模板渲染、狀態切換、組件熱替換等場景中寫出更清晰的代碼。

copyright © 萬盛學電腦網 all rights reserved