canvas-regions

レガシーの対象範囲

Region と RegionsProvider は非推奨となり、ページバリアントと合成されたページツリーが推奨されています。既存の統合は引き続き動作します。新しいリージョンプロバイダー統合を導入したり、既存のリージョンファイルを自動的に移行したりしないでください。

以下の手順は、既存のテーマグローバルリージョンのワークフローの保守のみを対象としています。新しいサイトクロームについては、これらのリージョンスペックを現在の作成モデルとして扱わず、対象の Canvas バージョンのページバリアントのドキュメントを参照してください。ページバリアントへの移行は別のタスクです。

プロジェクトの種類

このスキルを適用する前に、package.json に @drupal-canvas/headless という名前、または @drupal-canvas/headless- で始まる依存関係があるか確認してください。該当する依存関係がある場合、このプロジェクトは Canvas Headless のコードベースです。まず canvas-headless をお読みください。ヘッドレスプロジェクトではグローバルリージョンはサポートされていないため、このスキルは適用されません。該当する依存関係がない場合、このプロジェクトは Canvas レンダリングの React コードベースです。コンポーネントは React（index.jsx／.tsx）です。以下のレガシーガイダンスは、プロジェクトですでにテーマグローバルリージョンを使用している場合にのみ適用してください。プロジェクトの種類はこの2つのみです。

正式な定義

Canvas リージョンは、リポジトリで設定された regionsDir に保存される JSON リージョンスペックです。各リージョンは、特定のテーマの Drupal テーマリージョン（例：header、footer、sidebar_first）に対応し、その elements ツリーは、そのテーマを使用するすべてのページで該当リージョンにレンダリングされます。

Canvas CLI の push／pull ワークフローでは、これらのファイルを使ってローカルプロジェクトと Drupal Canvas の間でリージョンを同期します。

最低限の契約（MUST）

すべての Canvas リージョンは、以下のチェックをすべて満たす必要があります。

• リージョンファイルが、設定されたリージョンディレクトリ（canvas.config.json の regionsDir。デフォルトは ./regions）に存在する
• リージョンファイルが JSON オブジェクトである
• ファイル名が <region-machine-name>.json であり、マシン名が ^[a-z0-9_]+$ に一致する
• JSON に、リージョンが有効かどうかを示すブール値の status が含まれている
• JSON に elements オブジェクトが含まれている（空でもかまいません）
• elements 内のすべての要素に、検出済みコンポーネントの type が含まれている
• slots の各エントリーが、同じファイル内で定義された要素 ID を参照している

場所と命名

正式なローカルリージョンスペックは、設定されたリージョンディレクトリ（canvas.config.json の regionsDir）に作成します。regionsDir が設定されていない場合、デフォルトはトップレベルの regions/ ディレクトリです。

• 各リージョンを <regions-dir>/<region-machine-name>.json に配置します
• リージョンファイルは、設定されたリージョンディレクトリ直下に置きます。ネストされたファイルは無視されます
• ファイル名（.json を除く）がリージョンのマシン名です
• 使用できるファイル名の文字：小文字、数字、アンダースコア（^[a-z0-9_]+$）

例：

• <regions-dir>/header.json
• <regions-dir>/footer.json
• <regions-dir>/sidebar_first.json

リージョンファイルの形式

各リージョンファイルは、以下を含む JSON オブジェクトである必要があります。

• status：ブール値 — リージョンを有効にする場合は true、無効にする場合は false
• elements：作成したリージョン要素のオブジェクト（Canvas 管理のコンテンツがないリージョンでは空でもかまいません）

要素

elements の構造は Canvas ページスペックと同一です。要素の完全な契約、スロットのセマンティクス、画像のプロパティの形式、フォーマットの制約については、canvas-page-definition スキルを参照してください。

要点として、elements の各エントリーには以下が必要です。

• type：検出済みコンポーネントのタイプ（例：js.section、js.heading）

各エントリーには、以下も指定できます。

• props：その要素のルートプロパティ
• slots：スロット名を、同じファイル内の要素 ID の配列に対応付けるマップ

リージョンの構築時には要素の挿入順が維持されるため、トップレベルのセクションはレンダリングしたい順序で配置してください。

別のソース（エクスポートされた Canvas リージョンなど）から ID を意図的に維持する場合を除き、安定した、内容がわかりやすい要素 ID を使用してください。

例

{
  "status": true,
  "elements": {
    "header-section": {
      "type": "js.section",
      "props": {
        "width": "wide"
      },
      "slots": {
        "content": ["site-logo", "primary-nav"]
      }
    },
    "site-logo": {
      "type": "js.logo",
      "props": {
        "alt": "Site logo"
      }
    },
    "primary-nav": {
      "type": "js.navigation",
      "props": {
        "menu": "main"
      }
    }
  }
}

空でも有効になっているリージョンは有効です。リモートには存在するものの、Canvas で作成されたコンテンツがまだないリージョンのプレースホルダーとして使用できます。

{
  "status": true,
  "elements": {}
}

フォーマットの制約

リージョンではページ仕様と同じフォーマットを使用し、同じ制約が適用されます。リージョン仕様でサポートされるのは、検出されたコンポーネント要素と、その props および slots のみです。次のものを直接表現することはできません。

• 手書きの React ラッパー
• <div> や <section> などの生の HTML レイアウト要素
• className による間隔調整やカスタムラッパーのスタイル設定
• 既存のコンポーネントのマークアップをインラインコードで重複して記述すること

レイアウトプリミティブが必要な場合は、まず既存のコンポーネントを探してください。存在しない場合は、リージョン仕様で使用する前にコンポーネントとして作成してください（canvas-component-definition を参照）。

レイアウト

リージョンファイルで宣言するのは、各リージョンにどのコンポーネントを配置するかです。ページの周囲にヘッダー、フッター、サイドバーをどのように配置するかは決定しません。その配置は、プロジェクトレベルのレイアウトコンポーネントが担います。

レイアウトコンポーネント

canvas.config.json の layoutPath で設定したパス（デフォルトは ./src/layout.jsx）に、単一のレイアウトファイルを作成します。次の条件を満たす必要があります。

• { children } を受け取る React コンポーネントをデフォルトエクスポートします。
• ページごとのコンテンツを描画する場所に children を配置します。
• drupal-canvas の Region コンポーネントを使い、リージョンごとに名前を指定して、希望する位置に配置します。名前はローカルのリージョンファイル名と一致させます。

リージョン同士やページに対する相対的な配置を決めるのは、レイアウトだけです。ヘッダー → ページ → フッターといった垂直方向の順序、サイドバーの配置、構造上の要素にはレイアウトを使用してください。個々のリージョン JSON ファイルには、同じ階層の要素という概念はありません。

レイアウトファイルがない場合でも、リージョンファイルの検証と push は行われますが、ローカルプレビューには表示されません。

レイアウトコンポーネントの例

import { Region } from 'drupal-canvas';

export default function Layout({ children }) {
  return (
    <>
      <Region name="header" />
      <main>{children}</main>
      <Region name="footer" />
    </>
  );
}

各 <Region name="…" /> は、一致するリージョン JSON ファイル（例：regions/header.json）の要素を描画します。name プロパティには、.json 拡張子を除いたリージョンファイル名を指定する必要があります。

リージョンとレイアウトに含める内容

• リージョン — Canvas で作成し、差し替え可能なコンテンツ（ロゴ、メインナビゲーション、フッターの列、プロモーションバナーなど）です。Canvas で編集でき、push／pull で同期されます。
• レイアウト — 構造的な枠組み（ページ全体を囲む要素、<header>／<footer> の HTML 要素、スキップリンク、テーマプロバイダー、children の周囲におけるリージョンの順序など）です。これはコードであり、作成コンテンツではありません。
• JSON 内のリージョンのマシン名は、レイアウトが読み取る名前と一致する必要があります。新しいリージョンを追加するには、（1）<regions-dir>/<name>.json を追加し、（2）レイアウトコンポーネントでその名前を描画します。

レイアウトの適用範囲

レイアウトコンポーネントが制御するのはローカルプレビューのみです。稼働中の Drupal サイトでは、リージョンの配置はテーマ独自のリージョン定義に基づいて決まります。プレビューが本番環境を忠実に再現できるよう、レイアウトを対象テーマに合わせてください。

リージョンとページの違い

• ページは path で指定され、単一の URL に描画されます。リージョンはリージョンのマシン名で指定され、テーマを使用するすべてのページに描画されます。
• リージョンファイルには title、path、description を含めません。
• サイトの共通要素（ヘッダー、フッター、サイドバー）にはリージョンを使用します。固有の URL で表示するコンテンツにはページを使用します。
• すべてのページに表示するコンテンツは、ページ仕様に重複して記述するのではなく、リージョンに含めます。

ワークフロー

新しいリージョンの作成

1. リージョンのマシン名を確認する — ファイル名は、対象テーマで宣言されているリージョンのマシン名と一致する必要があります。不明な場合は、Drupal テーマの .info.yml を確認するか、ユーザーに尋ねてください。
2. 既存のリージョンファイルを確認する — 設定済みのリージョンディレクトリを一覧表示し、依頼がない限り既存のリージョンを上書きしないでください。リージョンのマシン名ごとに、使用できるファイルは1つだけです。
3. コンポーネントを選ぶ — src/components/ を確認し、レイアウトに合う component.yml の props／slots を持つコンポーネントを選びます。新しいコンポーネントを作成するより、既存のコンポーネントを優先してください。
4. 要素 ID を選ぶ — 安定した、説明的な ID を使用してください。
5. 上記の形式に従って JSON ファイルを作成する — ファイル名はリージョンのマシン名と一致する必要があります。

既存のリージョンの変更

1. 既存のリージョンファイルを読み、現在の構造を把握する。
2. 変更しない要素の既存の要素 ID を保持する — リモート側で ID が参照されている場合があります。
3. 新しく追加する要素には説明的な ID を選ぶ。
4. スロットの参照を検証する — スロット内のすべての ID が elements に存在する必要があります。
5. 意図的に対象を変更する場合を除き、ファイル名を変更しない — 名前を変更すると、リモート側でリージョンの識別情報が変わり、重複が作成される可能性があります。

検証

作成したすべてのリージョンを、作業を終える前に検証してください。

npx canvas validate