[JS] 웹 컴포넌트

bananackck 2025. 3. 30. 02:21

커뮤니티 프로젝트에서 모달, 헤더, 드롭다운 같은 요소들을 재사용할 수 있게 분리하였다. 그러다가 예기치 못한 오류를 발견했다...

uncaught SyntaxError: Failed to execute 'define' on 'CustomElementRegistry': "my-profileImg" is not a valid custom element name

찾아보니 커스텀 엘리먼트의 네임 규칙에 관한 내용이었다. 허거덩거덩스

내가 사용하고 있던 게 커스텀 엘리먼트였구나! 정확히는 웹 컴포넌트를 작성하고 있었다...

정말 많은 것을 알아가고 있는 것 같다.....

웹 컴포넌트

기능을 나머지 코드로부터 캡슐화하여 재사용 가능한 커스텀 엘리먼트를 생성하고 웹 앱에서 활용할 수 있도록 해주는 다양한 기술들의 모음

즉, 자주 쓰이거나 너무 긴 코드를 가진 기능을 따로 분리해서 관리하겠다! 라는 취지이다. 이를 사용하면 코드 재사용성이 높아지고 코드 충돌에 걱정이 없다.

예를 들어 아래 같이 정말 긴 코드가 있다고 하자... 헤더는 모든 페이지에서 사용될 테니까 계속해서 저 긴 코드를 작성해야 한다...

...
<body>
    <header>
        <div class="header-contents">    
            <div class="nav-btn left">
                 <img id="nav-back-img" src="../assets/img/navigate-back.png" alt="뒤로가기">
            </div>
            <div class="project-name">서비스 타이틀</div>
            <div class="nav-btn right">
                <img id="nav-back-img" src="../assets/img/navigate-forward.png" alt="앞으로가기">
            </div>
        </div>
    </header>
    <main>
        ...
    </main>
</body>
...

이걸 custom element로 작성해서 바꾸면?

...
<body>
    <my-header></my-header>
    <main>
        ...
    </main>
    <script type="module" src="../components/header.js"></script>
</body>
...

이렇게나 짧아진다!!! 가독성도 좋아지고 굿굿

< 구성 요소 >

1. Custom elements: 사용자 맞춤형 HTML element를 만들 수 있게 해주는 JS API 세트

2. Shadow DOM: 메인 DOM과 독립적으로 렌더링되는 DOM 트리를 제어하기 위한 JS API 세트

3. HTML 템플릿: <template>, <slot>과 같이 렌더링 시 나타나지 않는 템플릿

element가 뭔지 모른다면...

HTML element(요소)

시작 태그로 시작해서 종료 태그로 이루어진 모든 명령어들

태그 이름

- element의 역할 지정 & 기능을 포함하고 있음.

속성명

- element에 적용될 스타일 등등...

속성 값

- 소문자로! ⇨ HTML5 표준에서는 속성명에 대문자를 구분 X

- ""('') 사용하기

내용

- 화면에 표시될 내용

시작 태그와 종료 태그

- element의 시작과 끝 지정

- 종료 태그가 안 쓰일 때도 있음 ex. <img>, <br> ...

이제 하나씩 알아가보자.

1️⃣ Custom Elements

사용자가 원하는 기능을 갖춘 HTML element를 만들게 해준다. 자주 사용되고 반복되는 요소들을 모아놓아서 키워드로 대체했다고 생각하면 된다.

class MyComponent extends HTMLElement {...}
customElements.define("my-component", MyComponent)

기본 사용법은 위와 같다.

HTMLElement를 extends한 클래스 컴포넌트를 생성한다. HTMLElement는 window 브라우저의 내장 객체이다.

위에서 customElements.define()을 사용하고 있다.

customElement 또한 window 브라우저의 내장 객체이며, 호출 시 CustomElementRegistry 객체의 참조를 리턴한다.

여기서 이 커스텀 엘리먼트를 제어하기 위한 라이프 사이클 콜백이 존재한다.

connectedCallback: component가 DOM에 추가 됬을 때 호출
disconnectedCallback: component 내에 element가 제거될 때 마다 호출
observedAttributes: 변경을 감지할 속성들을 모니터링하기 위한 메서드
attributeChangedCallback: observedAttributes에서 모니터링 중인 속성들이 변경되었을 때 호출
adoptedCallback: element가 새로운 document로 이동될 때마다 호출

class MyComponent extends HTMLElement {
  // element 생성시 무조건 작성!!
  constructor() {
    super();
    ...
  }
  connectedCallback() {...}
  disconnectedCallback() {...}
  static get observedAttributes() {return [...];}
  attributeChangedCallback(name, oldValue, newValue) {...}
  adoptedCallback() {...}
}

2️⃣ Shadow DOM

독립적인 DOM 트리를 생성하는 기술. 캡슐화를 통해 마크업 구조, 스타일, 로직을 숨기고 페이지 내 다른 코드로부터 분리되어 코드 충돌이 없게 만들어 준다. 즉, 독립적인 스코프를 가진다.

또한 브라우저가 shadow DOM은 별도로 처리하여 불필요한 리렌더링을 방지할 수 있다.

외부 JS에서의 shadowRoot 접근 가능성에 따라 모드가 나뉜다.

열린 모드: 외부 접근 가능 (mode: "open")
닫힌 모드: 외부 접근 불가능 ⇒ 크롤링 방지 가능. (mode: "closed")

< 구조 >

Shadow Host: Shadow DOM이 부착되는 일반 DOM의 요소
Shadow Root: Shadow 트리의 루트 노드
Shadow Tree: Shadow DOM 내부의 DOM 트리
Shadow boundary: 경계

⇨ 원래 document tree와 shadow tree를 합쳐서 렌더링을 위해 Flattened Tree를 구성한다.

class MyComponent extends HTMLElement {
  constructor() {
    super();
    // Shadow DOM 사용
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
   connectedCallback() {
      const navBtns = this.shadowRoot.querySelector('.nav-btn.left');
      navBtns.classList.add('hidden');
   }
}

위에서 설명한 custom element 구성에서 사용할 수 있다.

this.shadowRoot.appendChild(template.content.cloneNode(true)) 에 대해 설명하자면...

shadowRoot에 자식 노드를 추가하겠다는 거다. template.content.cloneNode(true) 는 아래에서 설명하겠다.

콜백에서 특정 element를 호출할 때는 this.shadowRoot 를 사용하면 된다.

3️⃣ HTML 템플릿

다큐먼트가 처음 로드될 때 렌더링되지 않지만 JavaScript를 사용하는 런타임에 나타나는 HTML 조각을 포함한다.

내부 요소로 content를 가진다.

위에서 shadowRoot에 template.content.cloneNode(true) 를 추가했다.

여기서 template는 template element가 지정된 const 변수이다. 따라서 위 코드는 template element 안에 선언된 내용을 복붙하겠다는 뜻이다.

const template = document.createElement('template');
template.innerHTML = `
    <link rel="stylesheet" type="text/css" href="../assets/style/header.css">
    <header>
        <div class="header-contents">    
            <div class="nav-btn left">
                 <img id="nav-back-img" src="../assets/img/navigate-back.png" alt="뒤로가기">
            </div>
            <div class="project-name">서비스 타이틀</div>
            <div class="nav-btn right">
                <img id="nav-back-img" src="../assets/img/navigate-forward.png" alt="앞으로가기">
            </div>
        </div>
    </header>
`;

맨 위의 예시에서 header를 template 요소로 따로 빼면 위와 같은 코드가 된다.

지금은 style을 stylesheet를 불러오고 있지만, style element를 만들어서 template에 붙여도 된다.

const styleEl = document.createElement('style');
styleEl.textContent = `
  header {
    background-color: #f8f8f8;
  }
  .header-contents {
    padding: 10px;
  }
`;

// template의 content에 style 요소를 추가 (보통 맨 위에 추가)
template.content.prepend(styleEl);

이제 custom element, shadow DOM, HTML 템플릿을 적절하게 조합해서 사용하면 나만의 커스텀 웹 컴포넌트를 만들 수 있다!!

그럼 이제 3개의 파일 말고! 1개의 자바스크립트 파일로 컴포넌트를 관리할 수 있다.

다만 한 가지 아쉬운 점은 HTML과 CSS 코드가 자바스크립트 파일 안에 들어가기 때문에 전부 주황색으로 나온다..... 가독성이 좀 떨어지긴 하다...

이 부분을 해결한 것이 jsx 인 듯하다!