FORSMILE
EN
Twig2021/01/28

Twig include・extendsの使い方|部品化とテンプレート継承の実例

Twigのincludeによる部品化と、extends・blockによるレイアウト継承を、with・onlyを含む実例で整理します。

← ブログ一覧へ / Back to Blog
Quick Answer / まず結論

include / extendsの最短チェック

部品を読み込む時は include、共通レイアウトを継承する時は extends を使います。extendsはテンプレートの先頭付近に置くのが基本です。

Twig syntax guide

更新(2026/11/04):Twig公式ドキュメントに合わせて、include関数の位置づけと、名前付き引数の書き方(『:』は3.12以降、『=』はTwig 3.xの公式ドキュメントに記載)を補いました。

includeでテンプレート部品を読み込む

twig
{% include 'components/card.html.twig' with { product: product } only %}

onlyを付けると、指定した変数だけを読み込み先へ渡せます。部品が暗黙に親の変数へ依存するのを防げます。

include関数を使う

twig
{{ include('components/card.html.twig', { product: product }, with_context: false) }}

Twig公式ドキュメントは、includeタグよりinclude関数を使うよう勧めています。同じ機能を持ち、結果を変数に入れたりフィルタを掛けたりしやすいためです。『with_context: false』のように『:』で名前付き引数を書けるのはTwig 3.12以降で、それより前の版では『with_context = false』のように『=』で書きます(3.xの公式ドキュメントでは、『=』と『:』の両方が使えると書かれています)。Twig 3.29以降には、現在の変数を渡さないinclude_only()関数もあります。既存コードの方針とTwigの版に合わせて選びます。

extendsとblockでレイアウトを継承する

twig
{# pages/product.html.twig #}
{% extends 'base.html.twig' %}

{% block title %}{{ product.name|e }}{% endblock %}
{% block content %}
  <h1>{{ product.name|e }}</h1>
{% endblock %}

extendsは子テンプレートの先頭のタグとして置き、親が定義したblockを子側で上書きします。親の内容も残す場合はparent()を使います。

  • ▸繰り返し表示する小さな部品はinclude
  • ▸ページ全体の共通骨格はextendsとblock
  • ▸部品の入力を明確にするならwithとonlyを組み合わせる
Related articles