コンテンツへスキップ

InnerBlocks

内部ブロックを使うと、ブロック内に追加のブロックを挿入できます。内部では、BlockstudioがInnerBlocksコンポーネントを使用しています。1つのブロックで使用できるInnerBlocksコンポーネントは1つだけです。これはWordPressの制限です。

基本的な使い方

InnerBlocksを使うには、ブロックテンプレートに<InnerBlocks />コンポーネントを追加します。

PHP
<InnerBlocks />

構成は自由です。InnerBlocksコンポーネントはいくらでも深くネストできます。また、単独で使うこともできます。

プロパティ

allowedBlocks

allowedBlocksプロパティを使うと、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プロパティを使って変更できます。

PHP
<InnerBlocks tag="section" />

テンプレート

templateプロパティを使うと、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プロパティを使うと、テンプレートを変更できるかどうかを指定できます。

値 説明
contentOnly すべての操作を禁止します。コンテンツのないブロックタイプはリストビューに表示されません。子ブロックによる上書きはできません。
all すべての操作を禁止します。ブロックの挿入、移動、削除はできません。
insert ブロックの挿入と削除を禁止しますが、既存ブロックの移動は許可します。
false 親ブロックにロックが含まれていても、ロックの適用を禁止します。

renderAppender

renderAppenderプロパティを使うと、ブロックアペンダーの種類を指定できます。

値 説明
default デフォルトのブロックアペンダーを表示します(段落ブロックが許可されている場合は段落スタイルのアペンダー)
button アペンダーとして+アイコンのボタンを表示します

useBlockProps

エディター内のInnerBlocksコンポーネントの外側のラッパーを、useBlockPropsで削除できます。詳しくはuseBlockPropsをご覧ください。

コンテキスト

登録

BlockstudioはInnerBlocksコンポーネントのコンテキストに対応しています。親ブロックから子ブロックへデータを渡せます。内部ではWordPressのコアコンテキスト機構を使用していますが、Blockstudioはより使いやすいAPIを提供します。

コンテキストに渡す属性を1つずつ定義する代わりに、親ブロックのすべての属性を簡単に購読できます。

各子ブロックは、エディターの初回事前読み込みレンダリング時も含め、それぞれの親の値を受け取ります。プロバイダーのフィールドを更新すると、前のレンダリングがまだ読み込み中でも、エディター内の子ブロックが更新されます。異なるプロバイダーの下にある同一の子ブロックは、コンテキストに応じた個別のキャッシュ済みレンダリングを維持します。

次のようなコンテナブロックを設定したとします。

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関数を使ってコンテンツが空かどうかを確認できます。

動的テンプレート

SelectフィールドタイプとRadioフィールドタイプは、フィールド値に応じてInnerBlocksテンプレートを動的に生成できます。ユーザーがInnerBlocksコンポーネントのテンプレートを選べるようにする場合に便利です。

そのためには、テンプレートを指定したinnerBlocksキーをoptions配列に追加します。

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"
      }
    ]
  }
}

ブロックのコンテキストと通信

親ブロックと子ブロックがコンテキストを使ってデータを共有する方法をご覧ください。