ue-component-model

Universal Editor コンポーネントモデルの設定

このスキルでは、AEM Edge Delivery Services（EDS）のブロックが Universal Editor（UE）でどのように表示され、動作するかを制御する3つの JSON 設定ファイルを作成または編集できます。

1. component-definition.json — UE のコンポーネントパレットにブロックを登録します
2. component-models.json — 各ブロックのプロパティパネルのフィールドを定義します
3. component-filters.json — ブロックを配置できる場所を制御します

使用するタイミング

• UE でのオーサリングに対応した新しいブロックを作成するとき
• 既存のブロックのプロパティパネルにフィールドを追加または変更するとき
• オーサーのコンポーネントパレットに表示されるようブロックを登録するとき
• 子項目を持つコンテナブロックを設定するとき
• ブロックのバリアントやスタイルオプションを追加するとき

ワークフロー

ステップ 1：ブロックを理解する

設定を生成する前に、次の内容を読み、分析してください。

1. ブロックの JS ファイル（blocks/<name>/<name>.js）— decorate(block) 関数がどのようなコンテンツを想定しているかを確認します。

   • ブロックの div から何を読み取りますか？（画像、リンク、テキスト、クラス）
   • フラットな構造と項目の行のどちらを想定していますか？
   • block.querySelector('a')（リンク／URL）、block.querySelector('picture')（画像）などを使用していますか？
   • CSS クラスやバリアントを確認していますか？

2. ブロックの CSS ファイル（blocks/<name>/<name>.css）— バリアント固有のスタイルを確認します。

3. 既存の設定 — エントリがすでに存在するか確認します。

   • component-definition.json でブロック ID を検索します
   • component-models.json でモデル ID を検索します
   • component-filters.json の section コンポーネントリストでブロックを検索します
   • blocks/<name>/_<name>.json の配布設定ファイルがあるか確認します

ステップ 2：ブロックの種類を判定する

JS の分析結果に基づいて判定します。

• シンプルブロック：独自のフィールドを持つコンポーネントが1つあります。ほとんどのブロックはこの種類です。

  • 例：Hero、Embed — 単一のモデルで、子項目はありません

• コンテナブロック：繰り返し可能な子項目（カード、スライド、タブ）を持ちます。

  • 手がかり：JS が block.children を反復処理する、または行から項目を作成する
  • 必要なもの：コンテナ定義＋項目定義＋フィルター

• キーと値のブロック：設定形式のブロック（2列のキーと値のペア）です。

  • 手がかり：各プロパティが独立しており、コンテンツのグリッドではない
  • 必要なもの：テンプレート内の "key-value": true

ステップ 3：モデルフィールドを設計する

ブロックが想定するコンテンツを、コンポーネントのモデルフィールドに対応付けます。フィールドタイプの詳細については、references/field-types.md を参照してください。

一般的なフィールドの対応付け：

ブロックが想定するもの...	使用するコンポーネントタイプ	備考
画像	reference（名前：image）	imageAlt という名前の text フィールドと組み合わせます
URL／リンク	aem-content（名前：link または url）	ページリンクや外部 URL に使用します
リッチテキストコンテンツ	richtext	見出し、リスト、リンクを含む書式付きテキストに使用します
プレーンテキスト（1 行）	text	タイトル、ラベル、短い文字列に使用します
プレーンテキスト（複数行）	textarea	書式設定のない説明、メモ、長文に使用します
見出しレベルの選択	h1～h6 の選択肢を指定した select	タイトルとともに自動で折りたたまれるよう、名前を titleType にします
スタイルのバリエーション	multiselect（名前：classes）	値はブロックの div の CSS クラスになります
複数の切り替え項目	checkbox-group	複数の独立したブール値オプションに使用します
ブール値の切り替え	boolean	表示／非表示オプションに使用します
数値	number	件数や上限に使用します
コンテンツフラグメント	aem-content-fragment	CF を使用するブロックに使用します
エクスペリエンスフラグメント	aem-experience-fragment	再利用可能なコンテンツとレイアウトのフラグメントに使用します
コンテンツタグ	aem-tag	AEM タグピッカーによる分類に使用します

フィールド名のルール（意味に基づく折りたたみ）：

• image + imageAlt → <picture><img alt="..."> に折りたたまれます
• link + linkText + linkTitle + linkType → 任意のクラスを含む <a href="..." title="...">text</a> に折りたたまれます
• title + titleType → <h2>title</h2> に折りたたまれます（レベルは titleType で指定）
• group_（アンダースコア区切り）で始まるフィールドは、1 つのセルにグループ化されます

ステップ 4：設定を生成する

3 つすべてのファイルにエントリーを生成します。プロジェクトが集中型設定と分散型設定のどちらを使用しているかによって、手順が異なります。

分散型設定のパターンを確認する：ブロックのディレクトリに _<blockname>.json ファイル（例：blocks/hero/_hero.json）がある場合は、集中型のファイルを編集する代わりに、分散型設定ファイルを作成します。

集中型設定の場合（ルートにある 3 つの JSON ファイルを編集する場合）：

component-definition.json — "Blocks" グループの components 配列に追加します。

{
  "title": "<Block Display Name>",
  "id": "<block-id>",
  "plugins": {
    "xwalk": {
      "page": {
        "resourceType": "core/franklin/components/block/v1/block",
        "template": {
          "name": "<Block Name>",
          "model": "<model-id>"
        }
      }
    }
  }
}

コンテナーブロックの場合は、コンテナーとアイテムの両方の定義を追加します。コンテナーには "model" の代わりに "filter" を設定し、アイテムには "core/franklin/components/block/v1/block/item" を resourceType として指定します。

キーバリューブロックの場合は、テンプレートに "key-value": true を追加します。

テンプレートには、任意のモデルフィールドのデフォルト値を指定できます（例："titleType": "h3"、"classes": ["light"]）。

component-models.json — 新しいモデルエントリーを追加します。

{
  "id": "<model-id>",
  "fields": [
    {
      "component": "<field-type>",
      "name": "<property-name>",
      "label": "<Display Label>",
      "valueType": "string"
    }
  ]
}

component-filters.json — section フィルターの components 配列にブロック ID を追加します。コンテナーブロックの場合は、許可する子要素を定義する新しいフィルターエントリーも追加します。

分散型設定の場合（blocks/<name>/_<name>.json を作成する場合）：

3 つすべての設定を含む単一のファイルを作成します。

{
  "definitions": [ ... ],
  "models": [ ... ],
  "filters": [ ... ]
}

引き続き、中央の component-filters.json にある section フィルターにブロックを追加します。

ステップ 5：検証する

設定を生成したら、以下を確認します。

1. ID の一貫性：定義の id が component-filters.json で使用されている ID と一致していること。template.model の値が component-models.json の id と一致していること。
2. フィルターへの登録：ブロックの ID が section フィルターの components 配列に含まれていること（そうでない場合、作成者はページにブロックを追加できません）。
3. フィールド名とブロック JS の一致：モデルフィールドの name プロパティによって生成される HTML が、ブロックの decorate() 関数で処理できること。
4. 意味に基づく折りたたみ：フィールドのペアで正しいサフィックスを使用していること（例：意図的な場合を除き、image／altText ではなく image／imageAlt を使用）。
5. 有効な JSON：編集後も 3 つすべてのファイルが有効な JSON であること。
6. ID の重複がないこと：既存のエントリーとモデル ID またはフィルター ID が競合していないこと。

参照ファイル

詳細については、必要に応じて以下の参照ファイルをお読みください。

• references/architecture.md — 3 つのファイルの連携方法、AEM→Markdown→HTML の全パイプライン、リソースの種類、フィールドの命名規則、セマンティックな統合ルール、RTE フィルターの設定
• references/field-types.md — 17 種類のフィールドコンポーネント（text、textarea、richtext、reference、aem-content、aem-content-fragment、aem-experience-fragment、aem-tag、select、multiselect、checkbox-group、radio-group、boolean、number、date-time、container、tab）の完全なリファレンス、valueType の制約、必須プロパティ、フィールドプロパティ、バリデーションの種類、条件付きフィールド、オプションの形式
• references/examples.md — Hero（シンプル）、Embed（URL 付きのシンプルな例）、Cards（コンテナー）、Teaser（バリエーション）、Product Details（キーと値）、Article（コンテンツフラグメント）、Section の設定、Metadata（textarea）、Feature Toggles（checkbox-group）、RTE フィルターの設定を示す実例

よくある落とし穴

• セクションフィルターへの追加忘れ：section フィルターの components リストに含めないと、作成者の追加メニューにブロックが表示されません。
• resourceType の誤り：ほとんどすべてのカスタムブロックでは、core/franklin/components/block/v1/block を使用します。独自のリソースタイプを作らないでください。
• モデル ID とフィルター ID の不一致：template.model はモデルの id と完全に一致し、template.filter はフィルターの id と完全に一致する必要があります。
• テキストフィールドの種類の選択ミス：1 行の文字列には text、複数行のプレーンテキストには textarea、書式付きコンテンツには richtext を使用します。URL とページリンクには aem-content を使用し、作成者がコンテンツピッカーを使えるようにします。
• valueType の誤り：ほとんどのコンポーネントでは、特定の valueType が必須です（例：boolean には "boolean"、number には "number"、checkbox-group には "string[]" を使用します）。必ず valueType を指定し、必須値については field-types のリファレンスを確認してください。
• フィルターのないコンテナー：コンテナーブロックのテンプレートには、model ではなく filter が必要です。また、component-filters.json に対応するフィルターエントリーも必要です。