인터랙티브 컴포넌트 만들기
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()을 호출하여 생성합니다.
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 몇 줄만 필요합니다.
{
"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." }
]
}
}
<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>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
작동 방식:
data-wp-context='{ "isOpen": false }'가 이 인스턴스의 로컬 불리언 값을 생성합니다.- 버튼을 클릭하면
actions.toggle이 호출되어context.isOpen값을 반전합니다. data-wp-bind--hidden="!context.isOpen"가 패널을 숨기거나 표시합니다.data-wp-bind--aria-expanded와data-wp-text가 접근성과 시각적 표시를 위해 버튼 상태를 업데이트합니다.
각 블록 인스턴스에 자체 컨텍스트가 있으므로 페이지에 아코디언을 여러 개 배치해도 별도 설정 없이 작동합니다. 각 항목은 독립적으로 전환됩니다.
탭
탭에서는 새로운 개념 두 가지를 소개합니다. data-wp-class--*는 CSS 클래스를 전환하고, getElement()는 액션을 트리거한 요소의 데이터 속성을 읽습니다.
이 예제에서는 반복 필드를 사용하므로 편집자가 필요한 만큼 탭을 추가할 수 있습니다.
{
"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." }
]
}
]
}
}
<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>
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);
},
},
});
.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 키를 누르면 닫히도록 문서 수준의 이벤트를 처리하고, 배경 클릭으로 닫는 기능을 구현합니다. 또한 적절한 대화상자 접근성 속성도 보여 줍니다.
{
"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." }
]
}
}
<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>
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()을 사용해 초기화되며, 버튼을 클릭하면 값이 업데이트됩니다.
{
"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
$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>
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++;
}
},
},
});
.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 콜백을 추가하세요.
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<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 참고 문서.