본문으로 건너뛰기

인터랙티브 컴포넌트 만들기

WordPress 블록은 기본적으로 정적입니다. 편집기는 HTML을 데이터베이스에 저장하고, 프런트엔드가 이를 렌더링하면 끝입니다. 많은 블록에는 이것이 정확히 알맞습니다. 하지만 일부 컴포넌트는 콘텐츠 전환, 탭 전환, 대화상자 열기, 카운터 업데이트와 같은 사용자 상호작용에 반응해야 합니다.

WordPress Interactivity API는 지시문이라는 HTML 속성을 사용해 블록에 반응형 클라이언트 측 동작을 추가합니다. data-wp-on--click 대신 addEventListener을, data-wp-bind--hidden 대신 element.hidden = true을 작성합니다. API가 반응성, 컨텍스트 격리, 하이드레이션을 자동으로 처리합니다.

Blockstudio가 연결 작업을 처리합니다. block.json에서 "interactivity": true을 설정하면 Blockstudio가 임포트 맵을 생성하고, 편집기와 프런트엔드 모두에서 API를 로드하며, ES 모듈 임포트를 확인합니다. 빌드 단계도, 번들러도, webpack 설정도 필요하지 않습니다. 구성 세부 정보는 Interactivity 참고 문서를 확인하세요.

이 가이드에서는 각각 새로운 개념을 소개하는 완전한 컴포넌트 네 가지를 살펴봅니다. 끝까지 따라 하면 가장 흔한 인터랙티브 UI 요소에 사용할 수 있는 패턴을 익히게 됩니다.

작동 방식

지시문

지시문은 data-wp-* 속성으로, HTML에서 반응형 동작을 직접 선언합니다. 가장 자주 사용하는 지시문은 다음과 같습니다.

지시문 용도 예시
data-wp-interactive 스토어 네임스페이스 정의 data-wp-interactive="myBlock"
data-wp-context 인스턴스별 로컬 반응형 상태 data-wp-context='{ "isOpen": false }'
data-wp-on--[event] 이벤트 핸들러 data-wp-on--click="actions.toggle"
data-wp-bind--[attr] HTML 속성 바인딩 data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] CSS 클래스 전환 data-wp-class--is-active="context.isActive"
data-wp-text 텍스트 콘텐츠 설정 data-wp-text="state.count"
data-wp-style--[prop] 인라인 스타일 설정 data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] 전역 문서 이벤트 data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch 상태 변경 시 콜백 실행 data-wp-watch="callbacks.log"
data-wp-each 배열 반복 data-wp-each="state.items"

스토어

모든 인터랙티브 블록에는 스토어가 있으며, 네임스페이스와 actions, callbacks, 선택 사항인 state을 포함한 객체를 사용해 store()을 호출하여 생성합니다.

JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myBlock', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

액션 내부에서 getContext()은 DOM 트리에서 가장 가까운 data-wp-context 객체를 반환합니다. getElement()는 액션을 트리거한 DOM 요소의 참조를 반환하며, data-* 속성을 읽을 때 유용합니다.

컨텍스트와 상태 비교

컨텍스트(data-wp-context)는 각 블록 인스턴스에 국한됩니다. 페이지에 아코디언을 세 개 배치하면 각각 고유한 isOpen 값을 가집니다. 하나를 전환해도 다른 항목에는 영향을 주지 않습니다.

상태(wp_interactivity_state())는 전역이며 블록의 모든 인스턴스가 공유합니다. 댓글 수처럼 서버에서 가져오는 데이터나 모든 곳에서 동일해야 하는 값에 사용하세요.

컨텍스트는 편집기와 프런트엔드 모두에서 작동합니다. 상태는 WordPress가 이를 스크립트 태그로 직렬화하기 때문에 프런트엔드에서만 사용할 수 있습니다. 이 태그는 편집기 REST API 응답에는 포함되지 않습니다.

아코디언

가장 간단한 인터랙티브 패턴입니다. 버튼을 클릭해 콘텐츠를 전환합니다. 이 예제에는 지시문 세 개와 JavaScript 몇 줄만 필요합니다.

JSON
{
  "name": "my-theme/accordion",
  "title": "Accordion",
  "category": "text",
  "icon": "arrow-down-alt2",
  "description": "Expandable content section.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
      { "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
    ]
  }
}
PHP
<div useBlockProps
     data-wp-interactive="myTheme/accordion"
     data-wp-context='{ "isOpen": false }'>
  <button
    data-wp-on--click="actions.toggle"
    data-wp-bind--aria-expanded="context.isOpen"
    aria-controls="accordion-panel"
    style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
    <?php echo esc_html( $a['heading'] ); ?>
    <span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
  </button>
  <div
    id="accordion-panel"
    role="region"
    data-wp-bind--hidden="!context.isOpen"
    style="padding: 0 1rem 1rem;">
    <p><?php echo esc_html( $a['body'] ); ?></p>
  </div>
</div>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

작동 방식:

  1. data-wp-context='{ "isOpen": false }'가 이 인스턴스의 로컬 불리언 값을 생성합니다.
  2. 버튼을 클릭하면 actions.toggle이 호출되어 context.isOpen 값을 반전합니다.
  3. data-wp-bind--hidden="!context.isOpen"가 패널을 숨기거나 표시합니다.
  4. data-wp-bind--aria-expanded와 data-wp-text가 접근성과 시각적 표시를 위해 버튼 상태를 업데이트합니다.

각 블록 인스턴스에 자체 컨텍스트가 있으므로 페이지에 아코디언을 여러 개 배치해도 별도 설정 없이 작동합니다. 각 항목은 독립적으로 전환됩니다.

탭

탭에서는 새로운 개념 두 가지를 소개합니다. data-wp-class--*는 CSS 클래스를 전환하고, getElement()는 액션을 트리거한 요소의 데이터 속성을 읽습니다.

이 예제에서는 반복 필드를 사용하므로 편집자가 필요한 만큼 탭을 추가할 수 있습니다.

JSON
{
  "name": "my-theme/tabs",
  "title": "Tabs",
  "category": "text",
  "icon": "table-row-after",
  "description": "Tabbed content switcher.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      {
        "id": "tabs",
        "type": "repeater",
        "label": "Tabs",
        "min": 1,
        "max": 8,
        "attributes": [
          { "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
          { "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps
     data-wp-interactive="myTheme/tabs"
     data-wp-context='{ "activeTab": 0 }'>
  <div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
    <?php foreach ( $a['tabs'] as $i => $tab ) : ?>
      <button
        role="tab"
        data-index="<?php echo esc_attr( $i ); ?>"
        data-wp-on--click="actions.selectTab"
        data-wp-class--is-active-tab="callbacks.isActiveTab"
        data-wp-bind--aria-selected="callbacks.isActiveTab"
        style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
        <?php echo esc_html( $tab['label'] ); ?>
      </button>
    <?php endforeach; ?>
  </div>
  <?php foreach ( $a['tabs'] as $i => $tab ) : ?>
    <div
      role="tabpanel"
      data-index="<?php echo esc_attr( $i ); ?>"
      data-wp-bind--hidden="!callbacks.isActiveTab"
      style="padding: 1.5rem 0;">
      <p><?php echo esc_html( $tab['content'] ); ?></p>
    </div>
  <?php endforeach; ?>
</div>
JavaScript
import { store, getContext, getElement } from '@wordpress/interactivity';

store('myTheme/tabs', {
  actions: {
    selectTab: () => {
      const context = getContext();
      const { ref } = getElement();
      context.activeTab = parseInt(ref.dataset.index, 10);
    },
  },
  callbacks: {
    isActiveTab: () => {
      const context = getContext();
      const { ref } = getElement();
      return context.activeTab === parseInt(ref.dataset.index, 10);
    },
  },
});
CSS
.is-active-tab {
  border-bottom-color: currentColor !important;
  color: var(--wp--preset--color--primary, #111);
}

새로운 내용:

  • getElement() 은 { ref }을 반환하며, 여기서 ref는 DOM 요소입니다. data-index을 읽어 클릭한 탭을 확인합니다. 탭마다 별도의 액션을 만들 필요가 없습니다.
  • callbacks 는 컨텍스트가 바뀔 때 다시 계산되는 파생 값입니다. 탭 버튼과 패널 모두 callbacks.isActiveTab를 사용해 인덱스가 context.activeTab와 일치하는지 확인합니다.
  • data-wp-class--is-active-tab 은 콜백 반환값에 따라 is-active-tab 클래스를 추가하거나 제거합니다.

모달에서는 data-wp-on-document--keydown를 사용해 Escape 키를 누르면 닫히도록 문서 수준의 이벤트를 처리하고, 배경 클릭으로 닫는 기능을 구현합니다. 또한 적절한 대화상자 접근성 속성도 보여 줍니다.

JSON
{
  "name": "my-theme/modal",
  "title": "Modal",
  "category": "text",
  "icon": "external",
  "description": "Button that opens a modal dialog.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      { "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
      { "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
      { "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
    ]
  }
}
PHP
<div useBlockProps
     data-wp-interactive="myTheme/modal"
     data-wp-context='{ "isOpen": false }'>
  <button
    data-wp-on--click="actions.open"
    style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
    <?php echo esc_html( $a['buttonText'] ); ?>
  </button>

  <div
    data-wp-bind--hidden="!context.isOpen"
    data-wp-on--click="actions.backdropClick"
    data-wp-on-document--keydown="actions.onKeydown"
    style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
    <div
      role="dialog"
      aria-modal="true"
      data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
      data-wp-on--click="actions.stopPropagation"
      style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
      <h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
      <p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
      <button
        data-wp-on--click="actions.close"
        style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
        Close
      </button>
    </div>
  </div>
</div>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/modal', {
  actions: {
    open: () => {
      const context = getContext();
      context.isOpen = true;
    },
    close: () => {
      const context = getContext();
      context.isOpen = false;
    },
    backdropClick: () => {
      const context = getContext();
      context.isOpen = false;
    },
    stopPropagation: (event) => {
      event.stopPropagation();
    },
    onKeydown: (event) => {
      if (event.key === 'Escape') {
        const context = getContext();
        context.isOpen = false;
      }
    },
  },
});

새로운 내용:

  • data-wp-on-document--keydown 는 요소 자체가 아니라 document에서 이벤트를 감지합니다. 포커스가 어느 요소에 있든 핸들러가 실행되므로 어디서나 Escape 키가 작동합니다.
  • 배경 클릭으로 닫기에는 두 계층이 사용됩니다. 오버레이 div는 actions.backdropClick를 호출하고, 내부 대화상자는 actions.stopPropagation를 호출해 대화상자 안쪽을 클릭해도 닫히지 않게 합니다.
  • role="dialog"와 aria-modal="true" 는 스크린 리더에 이 요소가 모달 대화상자임을 알립니다. aria-label는 모달이 표시될 때만 적용되도록 바인딩됩니다.
  • 오버레이의 hidden 속성은 모달을 숨기고, 모달이 닫힌 동안 문서의 keydown 리스너가 실행되지 않도록 합니다. 숨겨진 요소의 지시문은 일시 중지되기 때문입니다.

서버 상태를 사용하는 좋아요 버튼

이 예제에서는 서버 측 상태와 클라이언트 측 액션을 결합합니다. 좋아요 수는 PHP에서 wp_interactivity_state()을 사용해 초기화되며, 버튼을 클릭하면 값이 업데이트됩니다.

JSON
{
  "name": "my-theme/like-button",
  "title": "Like Button",
  "category": "text",
  "icon": "heart",
  "description": "A like button with a count.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      { "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
    ]
  }
}
PHP
<?php
$item_id = $a['itemId'];
$count   = (int) get_option( "likes_{$item_id}", 0 );

wp_interactivity_state( 'myTheme/likeButton', array(
	'count' => $count,
) );
?>
<div useBlockProps
     data-wp-interactive="myTheme/likeButton"
     data-wp-context='{ "liked": false }'>
  <button
    data-wp-on--click="actions.like"
    data-wp-class--is-liked="context.liked"
    style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
    <span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
    <span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
  </button>
</div>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

const { state } = store('myTheme/likeButton', {
  actions: {
    like: () => {
      const context = getContext();
      if (context.liked) {
        context.liked = false;
        state.count--;
      } else {
        context.liked = true;
        state.count++;
      }
    },
  },
});
CSS
.is-liked {
  border-color: #ef4444 !important;
  background: #fef2f2 !important;
}

새로운 내용:

  • wp_interactivity_state() 은 PHP에서 좋아요 수를 초기화합니다. 값은 페이지 HTML에 직렬화되며 지시문과 JavaScript에서 state.count으로 사용할 수 있습니다.
  • state와 context 비교: 좋아요 수는 state(전역, 공유)에 있고 liked은 context(인스턴스별)에 있습니다. 같은 항목에 좋아요 버튼이 여러 개 있으면 좋아요 수는 공유하지만 각 버튼의 좋아요 여부는 따로 추적할 수 있습니다.
  • store()에서 구조 분해: store() 호출은 액션에서 참조할 수 있는 반응형 state 객체를 반환합니다.

중요한 주의 사항: 서버 상태는 프런트엔드 전용입니다. 편집기에서 블록은 REST API을 통해 렌더링되므로 wp_interactivity_state()가 포함되지 않습니다. PHP에서 렌더링하는 대체 텍스트(<?php echo esc_html( $count ); ?>)가 편집기 미리 보기에서 초기값으로 표시됩니다. 편집기에서 상호작용하는 상태가 필요하면 대신 data-wp-context를 사용하세요.

팁과 패턴

네임스페이스 규칙. 테마나 플러그인 이름을 접두사로 사용하세요. myTheme/accordion, myPlugin/tabs처럼 지정하면 같은 페이지의 여러 블록이 Interactivity API를 사용할 때 충돌을 방지할 수 있습니다.

빌드 단계가 필요하지 않습니다. Blockstudio가 script.js을 네이티브 ES 모듈로 로드하고 @wordpress/interactivity의 임포트 맵을 자동으로 생성합니다. 표준 JavaScript에 import 문을 작성하면 바로 작동합니다.

지시문만 사용하는 블록. 블록에서 data-wp-context를 data-wp-bind--hidden 또는 data-wp-text와 함께 사용하기만 한다면 script.js가 전혀 필요하지 않습니다. Interactivity API가 선언적으로 처리합니다. 위 아코디언 예제는 체크박스 기법을 사용하면 JavaScript 없이도 작동하지만, 스크립트를 사용하는 편이 더 깔끔합니다.

data-wp-watch로 디버깅하기. 개발 중 컨텍스트 변경을 기록하려면 watch 콜백을 추가하세요.

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<div data-wp-watch="callbacks.debug" ...>

배포 전에 제거하세요.

컨텍스트를 최소한으로 유지하세요. 실제로 바뀌는 값만 data-wp-context에 넣으세요. 레이블이나 콘텐츠 같은 정적 데이터는 PHP에 두어야 합니다. 컨텍스트 JSON는 블록의 모든 인스턴스에 직렬화되므로 큰 객체는 페이지 용량을 늘립니다.

다음 단계

  • Interactivity 참고 문서: 구성 옵션, 편집기 지원 세부 정보, interactivity 설정의 객체 형식.
  • 에셋: Blockstudio가 script.js, style.css 및 기타 블록 에셋을 로드하는 방법.
  • WordPress Interactivity API 문서: 이 가이드에서 다루지 않은 data-wp-each, data-wp-init, data-wp-run 및 기타 지시문을 포함한 전체 API 참고 문서.