Magento: referenceBlock と referenceContainer の違いと使い分け

Nishi
2026-07-27
2026-07-27

こんにちは！
Nishiです。前回はMagentoの「Magento: Layout XMLの基本構造を理解しよう」についての記事を書きました。
今回は、Layout XMLでよく登場する referenceBlock と referenceContainer の違いについて書いていきたいと思います。

※本記事は、Magento Open Source 2.4.7-p3 を使用しています。

referenceContainer と referenceBlock の違い

イメージとしては、Containerが棚で、Blockがその棚に並べる商品のようなイメージです。
棚（Container）は表示する場所を表し、その中に商品（Block）を置くことで実際の表示内容が決まります。
Layout XMLでは、Container と Block を参照するために、referenceContainer と referenceBlock を使用します。

それぞれの役割を見ていきましょう。

referenceContainer とは？

「referenceContainer」は、すでに定義されているContainerを参照して、そのContainerにBlockを追加したり、レイアウトを変更したりするときに使用します。

<referenceContainer name="既存のContainer名">
    ここに追加したい内容を書く
</referenceContainer>

前回の記事「Magento: Layout XMLの基本構造を理解しよう」で使用した
<referenceContainer name="content"> も、
content という名前の Container を参照しているため、referenceContainer を使っています。
content が Container かどうかは、Magentoのコアファイルで確認できます。
以下のファイルを開いてみましょう。

vendor/magento/module-theme/view/frontend/layout/default.xml

ファイルの中を見ると、以下のように定義されています。

<container name="content" label="Main Content Area"/>

containerタグで定義されているため、content は Container  として定義されていることが分かります。
そのため、contentを参照するときは「referenceContainer」を使用します。

referenceBlock とは？

referenceBlock は、すでに定義されている Block を参照して、子Blockの追加や設定変更、表示制御などを行うときに使用します。

<referenceBlock name="既存のBlock名">
    ここに追加したい内容を書く
</referenceBlock>

ここで言う「既存のBlock」とは、MagentoのLayout XMLですでに定義されているBlockのことです。
Layout XMLでいう「Block」は、PHPクラスで定義された画面の表示部品を指します。
管理画面で作成する「CMSブロック」とは名称が似ていますが、別のものなので注意してください。

Layout XMLで定義されているBlockは、コアファイルで確認することができます。
例えば、ヘッダーのロゴは以下のファイルで確認できます。

vendor/magento/module-theme/view/frontend/layout/default.xml

<block class="Magento\Theme\Block\Html\Header\Logo" name="logo">

block タグで定義されているので、logo は Block として定義されていることが分かります。
そのため、logo を参照するときは referenceBlock を使用します。

使い分けのポイント

どちらを使うか迷った場合は、参照先がContainerかBlockかを確認しましょう。
基本的な流れは以下のとおりです。

  1. 追加・変更したい場所の名前を確認する（例：content、logo）
  2. コアのLayout XMLファイルで、その名前が container タグか block タグかを確認する
  3. container なら referenceContainer
  4. block なら referenceBlock

最後に

今回は、referenceBlock と referenceContainer の違いについてまとめました。
どちらを使えばよいか迷ったときは、参照先が Block か Container かを確認するようにしましょう。

次回は、before / after / remove を使ったレイアウト変更の方法について書いていきたいと思います。
© Future Spirits Co.Ltd.