.wrapAll()

jQuery Reference

.wrapAll()은 선택한 모든 요소를 하나의 공통 HTML 구조로 묶습니다. 서로 떨어져 있는 요소도 한곳으로 이동하므로, 원래 문서 순서와 배치가 달라질 수 있습니다.

문법과 적용 범위

$(".item").wrapAll("<div class='group'></div>");

감싸는 구조는 첫 번째 선택 요소 앞에 만들어지고 나머지 선택 요소들이 그 안으로 이동합니다. 중간에 있던 선택되지 않은 형제 요소는 함께 들어가지 않습니다. .wrap()은 각각에 부모를 만들고, .wrapAll()은 전체에 부모 하나를 만듭니다. 함수 형태는 jQuery 3.0 이상에서 한 번 호출되며, 감싸는 구조를 반환합니다. 반환값은 원래 선택 집합입니다.

jQuery 공식 문서의 .wrapAll() 정의와 인수에서 다른 호출 형태도 확인할 수 있습니다.

전체 실행 예제

아래 코드를 UTF-8 형식의 example.html 파일로 저장한 뒤 브라우저로 여세요. 예제는 jQuery 4.0.0 일반 빌드를 외부 주소에서 불러오므로 인터넷 연결이 필요합니다. 문서가 준비된 뒤 실행하도록 $(function () { ... }) 안에 코드를 작성했습니다.

<!doctype html>
<html lang="ko">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>jQuery wrapAll 예제</title>
  <style>
    body { margin: 24px; font-family: sans-serif; line-height: 1.6; }
    .marked { background: #fff0b3; border: 2px solid #835b00; }
    .active { color: #a00000; font-weight: bold; }
    button, input, select { font: inherit; }
    #output { white-space: pre-wrap; overflow-wrap: anywhere; }
  </style>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
</head>
<body>
<div id="container">
  <p class="item">첫 문단</p>
  <p id="note">중간 안내</p>
  <p class="item">둘째 문단</p>
</div>
  <p id="output" aria-live="polite"></p>
  <script>
    $(function () {
      $(".item").wrapAll("<div class='group marked'></div>");
      $("#output").text("그룹 안: " + $(".group").children().map(function () { return $(this).text(); }).get().join(" / ") +
        " | 안내의 부모: " + $("#note").parent().attr("id"));
    });
  </script>
</body>
</html>

실행 결과 확인

테두리 하나 안에 첫 문단과 둘째 문단이 모입니다. 중간 안내는 그룹 밖에 남고, 그룹 전체 뒤로 보이게 됩니다. 결과는 그룹 안: 첫 문단 / 둘째 문단 | 안내의 부모: container입니다.

사용할 때 주의할 점

서로 다른 부모의 요소를 선택해도 한곳에 모일 수 있습니다. 레이아웃이나 읽기 순서를 유지해야 한다면 부모별로 범위를 나누거나 .wrap()을 사용하세요.
감싸는 구조의 가장 안쪽에 삽입 지점이 여러 개 있으면 의도가 불명확해집니다. 가장 안쪽 요소는 하나로 구성하세요.
기존 요소를 이동하는 것이므로 복제본을 만드는 기능과 구분하세요. 이벤트 위임이 원래 조상에 걸려 있었다면 이동 후에도 이벤트가 그 조상까지 올라가는지 확인해야 합니다.
.unwrap()으로 부모를 제거해도 떨어져 있던 원래 위치까지 복원되지는 않습니다. 위치 복원이 필요하면 이동 전 위치를 별도로 기억해야 합니다.

용도를 비교하려면 .wrap()과 부모 개수 비교, .unwrap()으로 감싸기 해제하기을 참고하세요.

jQuery Reference