본문으로 건너뛰기

InnerBlocks

내부 블록을 사용하면 블록 안에 블록을 추가할 수 있습니다. 내부적으로 Blockstudio는 InnerBlocks 컴포넌트를 사용합니다. 블록마다 InnerBlocks 컴포넌트는 하나만 사용할 수 있으며, 이는 WordPress 제한 사항입니다.

기본 사용법

InnerBlocks를 사용하려면 블록 템플릿에 <InnerBlocks /> 컴포넌트를 추가하세요.

PHP
<InnerBlocks />

구성은 원하는 대로 할 수 있습니다. InnerBlocks 컴포넌트를 원하는 깊이까지 중첩하거나 단독으로 사용할 수 있습니다.

속성

allowedBlocks

allowedBlocks prop을 사용하면 InnerBlocks 컴포넌트에 삽입할 수 있는 블록을 정의할 수 있습니다.

PHP

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />

Twig

Twig
<InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />

allowedBlocks는 서버에서 확장되는 토큰도 허용합니다. 토큰은 편집기에 템플릿이 전달되기 전에 확장되며, 리터럴 블록 이름은 변경되지 않습니다.

토큰 설명
namespace/* 해당 네임스페이스에 등록된 모든 블록
category:<slug> 해당 WordPress 블록 카테고리에 등록된 모든 블록
@theme 활성 테마에서 등록된 모든 Blockstudio 블록

확장된 항목은 작성자가 지정한 순서대로 중복 제거됩니다.

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

블록으로 확인되지 않는 토큰은 무시됩니다. allowedBlocks는 편집기에서만 사용되므로 프런트엔드 출력은 변경되지 않습니다.

태그

기본적으로 InnerBlocks 컴포넌트는 div 요소로 렌더링됩니다. tag prop을 사용해 이를 변경할 수 있습니다.

PHP
<InnerBlocks tag="section" />

템플릿

template prop을 사용하면 InnerBlocks 컴포넌트의 템플릿을 정의할 수 있습니다.

PHP

PHP
<InnerBlocks template="<?php echo esc_attr(wp_json_encode([
  ['core/heading', ['placeholder' => 'Book Title']],
  ['core/paragraph', ['placeholder' => 'Summary']]
])); ?>" />

Twig

Twig
<InnerBlocks template="{{ [
  ['core/heading', { placeholder: 'Book Title' }],
  ['core/paragraph', { placeholder: 'Summary' }]
]|json_encode|escape('html_attr') }}" />

templateLock

templateLock prop을 사용하면 템플릿 수정 가능 여부를 정의할 수 있습니다.

값 설명
contentOnly 모든 작업을 방지합니다. 콘텐츠가 없는 블록 유형은 목록 보기에서 숨겨집니다. 하위 블록에서 재정의할 수 없습니다.
all 모든 작업을 방지합니다. 블록을 삽입, 이동 또는 삭제할 수 없습니다.
insert 블록 삽입 및 제거를 방지하지만 기존 블록은 이동할 수 있습니다.
false 상위 블록에 잠금이 있어도 잠금 적용을 방지합니다.

renderAppender

renderAppender prop을 사용하면 블록 추가기 유형을 정의할 수 있습니다.

값 설명
default 기본 블록 추가기를 표시합니다(문단 블록이 허용되면 문단 스타일 추가기 표시)
button + 아이콘 버튼을 추가기로 표시합니다

useBlockProps

useBlockProps은 편집기에서 InnerBlocks 구성 요소의 바깥쪽 래퍼를 제거합니다. 자세한 내용은 useBlockProps에서 확인하세요.

컨텍스트

등록

Blockstudio은 InnerBlocks 컴포넌트의 컨텍스트를 지원합니다. 이를 통해 부모 블록의 데이터를 자식 블록에 전달할 수 있습니다. 내부적으로 WordPress코어 컨텍스트 메커니즘을 사용하지만, Blockstudio은 더 편리한 API을 제공합니다.

컨텍스트에 전달할 모든 속성을 각각 정의하는 대신, 부모 블록의 모든 속성을 간단히 구독할 수 있습니다.

각 자식 블록은 편집기의 첫 사전 로드 렌더링에서도 각자의 부모 값을 받습니다. 제공자의 필드를 업데이트하면 이전 렌더링이 아직 로드 중이더라도 편집기에서 자식 블록이 업데이트됩니다. 서로 다른 제공자 아래에 있는 동일한 자식 블록은 컨텍스트를 반영한 렌더링 캐시를 각각 유지합니다.

다음과 같이 컨테이너 블록을 설정했다고 가정해 보겠습니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/container",
  "title": "Container",
  "category": "design",
  "icon": "star-filled",
  "description": "Container block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "full-width",
        "type": "toggle",
        "label": "Makes section full width"
      }
    ]
  }
}

자식 블록 안에서 부모 블록 이름을 사용해 usesContext 속성을 참조하면 블록 템플릿에서 모든 부모 속성에 액세스할 수 있습니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/element",
  "title": "Element",
  "category": "design",
  "icon": "star-filled",
  "description": "Element block.",
  "usesContext": ["blockstudio/container"],
  "parent": ["blockstudio/container"],
  "blockstudio": true
}

템플릿

블록 템플릿 안에서 $context 및 $c 변수를 사용해 모든 부모 속성에 액세스할 수 있습니다. 부모 데이터가 변경되면 편집기에서 자식 블록이 자동으로 다시 로드됩니다.

PHP

PHP
<?php $container = $context['blockstudio/container']; ?>

<h1>
  <?php echo $container['full-width']
      ? 'is full width'
      : 'no full width'; ?>
</h1>

Twig

Twig
{% set container = context['blockstudio/container'] %}

<h1>
  {{ container['full-width']
      ? 'is full width'
      : 'no full width' }}
</h1>

프런트엔드 래퍼

InnerBlocks은 편집기에서 자식 요소를 감싸는 래퍼 요소를 렌더링해야 하지만, blockstudio/blocks/components/inner_blocks/frontend/wrap 필터를 사용하면 프런트엔드에서 제거할 수 있습니다.

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

조기 반환

블록의 render 메서드에서 조기에 반환하려면 $innerBlocks 변수가 비어 있는지 확인하세요. 내부 블록이 없을 때 아무것도 렌더링하지 않으려는 경우에 유용합니다.

PHP
<?php if (strip_tags($innerBlocks) === '') {
  return;
} ?>
<InnerBlocks tag="section" />

<InnerBlocks/>은 항상 빈 문단 태그를 렌더링하므로 strip_tags 함수를 사용해 콘텐츠가 비어 있는지 확인할 수 있습니다.

동적 템플릿

선택 및 라디오 필드 유형은 필드 값에 따라 InnerBlocks 템플릿을 동적으로 생성할 수 있습니다. 이를 통해 사용자가 InnerBlocks 컴포넌트의 다른 템플릿을 선택하도록 할 수 있습니다.

이를 위해 옵션 배열에 템플릿을 지정하는 innerBlocks 키를 추가하면 됩니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/dynamic-layout",
  "title": "Dynamic Layout",
  "blockstudio": {
    "attributes": [
      {
        "id": "layout",
        "type": "select",
        "label": "Layout",
        "options": [
          {
            "value": "1",
            "label": "Two Columns",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Left Heading",
                          "level": 1
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Right Heading",
                          "level": 1
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "value": "2",
            "label": "Single Column",
            "innerBlocks": [
              {
                "name": "core/heading",
                "attributes": {
                  "content": "Main Heading",
                  "level": 1
                }
              },
              {
                "name": "core/paragraph",
                "attributes": {
                  "content": "Main content goes here."
                }
              }
            ]
          }
        ],
        "allowNull": "Select a layout"
      }
    ]
  }
}

블록 컨텍스트와 통신

컨텍스트를 사용해 부모 블록과 자식 블록이 데이터를 공유하는 방법을 알아보세요.