본문으로 건너뛰기

useBlockProps

기본적으로 Gutenberg은 편집기에서 블록을 대화형으로 만들기 위해 블록을 래퍼로 감싸야 합니다. 컨테이너나 열과 같은 일부 블록 유형에서는 이로 인해 편집기와 프런트엔드의 마크업이 달라질 수 있습니다. useBlockProps 훅을 사용하면 블록 템플릿 안의 요소를 루트 요소로 지정하여 편집기와 프런트엔드의 마크업을 일치시킬 수 있습니다.

사용법

블록의 루트 요소에 useBlockProps 속성을 추가하면 됩니다.

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

Blockstudio은 편집기의 클래스와 속성(정렬 클래스 등)을 블록 템플릿에 정의된 항목과 자동으로 결합합니다. 내부적으로 get_block_wrapper_attributes를 사용합니다.

blockstudio/blocks/components/use_block_props/render 필터는 프런트엔드와 편집기 렌더링 경로 모두에서 래퍼에 적용됩니다. 따라서 테마 또는 개별 인스턴스 통합에서 추가한 클래스는 편집기 캔버스와 저장된 프런트엔드 마크업 모두에 표시됩니다.

출력:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

고려 사항

Blockstudio은 블록 편집기 내에서 링크 이동을 막습니다. 여기에는 target="_blank", 수정 키를 누른 채 클릭하기, 가운데 버튼으로 클릭하기, 키보드로 활성화하기가 포함됩니다. 클릭 이벤트는 여전히 Gutenberg에 전달되므로 일반 클릭으로 블록을 선택할 수 있습니다. RichText는 계속 편집할 수 있습니다. 이는 useBlockProps 유무와 관계없이 적용되며, 블록의 루트 요소로 사용되는 앵커에도 적용됩니다.

프런트엔드 링크와 브라우저의 컨텍스트 메뉴 명령은 그대로 작동합니다. 템플릿에서 링크를 제거하거나 $isEditor에 따라 분기할 필요가 없습니다.

루트 요소

블록 템플릿에는 루트 요소가 하나만 있을 수 있으므로 useBlockProps을 사용할 때는 템플릿에 루트 요소를 하나만 두어야 합니다. 예를 들어 다음 코드는 작동하지 않으며 Gutenberg이 템플릿을 래퍼로 감쌉니다.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

마찬가지로 useBlockProps은 블록 템플릿마다 한 번만 사용할 수 있습니다.

@ 기호

Blockstudio은 Gutenberg 안에서 html-react-parser를 사용해 블록 템플릿을 유효한 React 코드로 변환합니다. 이때 @ 문자를 HTML 속성 이름 안에서 사용할 수 없다는 제한이 있습니다.

Alpine.js 같은 라이브러리는 HTML 요소에 지시문을 정의할 때 @ 문자를 사용합니다.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

Gutenberg 안에서는 이 @click 속성이 요소에서 제거됩니다. (물론 프런트엔드에서는 계속 작동합니다.)

이 문제를 해결하려면 Alpine.js에서 제공하는 대체 구문을 사용할 수 있습니다.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

위 구문은 Gutenberg 안과 프런트엔드에서 모두 작동합니다.

캔버스 본문 클래스

assets.reset.enabled이 활성화되면 Blockstudio은 WordPress의 body_class 필터가 반환하는 정제된 클래스도 블록 편집기 캔버스에 복사합니다. 따라서 .brand-a .site-card와 같은 테마 선택자가 두 곳 모두에서 작동합니다.

편집기에서 더 좁은 범위의 클래스가 필요하면 최종 클래스 목록을 필터링하세요:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

이 필터는 편집기 캔버스에 복사되는 클래스만 제어합니다. 프런트엔드 본문 클래스는 변경하지 않습니다.