본문으로 건너뛰기

인터랙티비티

Blockstudio은 블록에 반응형 클라이언트 측 동작을 추가하는 표준 방법을 제공하는 인터랙티비티 WordPressAPI를 지원합니다. block.json에서 interactivity를 설정하면 Blockstudio이 프런트엔드와 편집기 모두에서 API을 로드합니다.

구성

block.json의 blockstudio 키에 interactivity을 추가해 인터랙티비티 API를 활성화하세요:

JSON
{
  "name": "my-theme/interactive-block",
  "title": "Interactive Block",
  "category": "text",
  "icon": "star-filled",
  "description": "A block with interactive behavior.",
  "blockstudio": {
    "interactivity": true
  }
}

객체 형식을 사용할 수도 있습니다:

JSON
{
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

두 형식은 동일합니다.

템플릿

블록 템플릿에 인터랙티비티 API 지시문을 추가하세요. data-wp-interactive 속성은 스토어 네임스페이스를 정의하며, 다른 data-wp-* 속성은 반응형 동작을 제어합니다.

PHP
<div useBlockProps
     data-wp-interactive="myBlock"
     data-wp-context='{ "isOpen": false }'>
  <button data-wp-on--click="actions.toggle"
          data-wp-bind--aria-expanded="context.isOpen">
    Toggle
  </button>
  <div data-wp-bind--hidden="!context.isOpen">
    This content is toggled by the button.
  </div>
</div>

스크립트

블록 폴더에 script.js 파일을 만들고 @wordpress/interactivity에서 가져온 항목을 사용해 스토어를 초기화하세요. 모듈 최상위에서 store()를 호출합니다:

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

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

Blockstudio은 script.js을 ES 모듈로 로드하고 @wordpress/interactivity를 해석하는 데 필요한 importmap을 자동으로 생성합니다.

블록에 사용자 지정 작업이나 콜백이 정의된 경우에만 script.js가 필요합니다. data-wp-context를 사용하는 선언형 지시문만 있는 블록(예: data-wp-bind--hidden 또는 data-wp-text)은 JavaScript 없이도 작동합니다.

서버 측 상태

템플릿에서 PHP로 상태를 초기화하려면 wp_interactivity_state()를 사용할 수 있습니다.

PHP
<?php
wp_interactivity_state( 'myBlock', array(
    'message' => 'Hello from the server',
    'count'   => get_comments_number(),
) );
?>
<div useBlockProps
     data-wp-interactive="myBlock">
  <p data-wp-text="state.message">loading...</p>
  <p data-wp-text="state.count">0</p>
</div>

서버 측 상태는 프런트엔드에서만 사용할 수 있습니다. WordPress는 페이지 출력의 JSON 스크립트 태그에 상태를 직렬화하고, Interactivity API가 하이드레이션 중에 이를 읽습니다. 편집기에서는 블록이 REST API를 통해 렌더링되므로 응답에 상태 데이터가 포함되지 않습니다. 편집기와 프런트엔드 양쪽에서 작동해야 하는 상태에는 data-wp-context를 사용하세요.

콜백과 액션 비교

액션은 사용자 상호작용(예: data-wp-on--click)으로 실행됩니다. 콜백은 data-wp-watch 지시문을 사용해 상태나 컨텍스트가 변경될 때 반응형으로 실행됩니다. 콜백 안에서는 getElement()를 호출해 기본 DOM 요소에 접근할 수 있습니다.

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

store('myBlock', {
  callbacks: {
    updateWidth: () => {
      const { ref } = getElement();
      const { isOpen } = getContext();
      ref.style.width = isOpen ? '100%' : '0';
    },
  },
});

편집기 지원

Interactivity API는 블록 편집기 iframe 안에서 로드되므로 편집기 미리보기에서 대화형 지시문이 작동합니다. 여기에는 data-wp-context, data-wp-bind--*, data-wp-on--*, data-wp-text 및 script.js에 정의된 사용자 지정 스토어 액션이 포함됩니다.

대화형 컴포넌트 만들기

아코디언, 탭, 모달, 좋아요 버튼을 포함한 완전한 예제입니다.