generating-flexipage

このスキルを使用する場面

次の作業が必要な場合に、このスキルを使用します。

• Lightning ページ（RecordPage、AppPage、HomePage）を作成する
• FlexiPage メタデータ XML を生成する
• 既存の FlexiPage にコンポーネントを追加する
• FlexiPage のデプロイエラーをトラブルシューティングする
• FlexiPage の構造とコンポーネントの設定を理解する
• ページレイアウトや Lightning ページのカスタマイズを行う
• 任意の *.flexipage-meta.xml ファイルを編集または更新する

仕様

FlexiPage 生成ガイド

概要

重要：新しい FlexiPage を作成する場合は、必ず CLI のテンプレートコマンドから開始してください。 FlexiPage XML を一から作成してはいけません。CLI は有効な構造、適切な領域、正しいコンポーネント設定を提供し、デプロイエラーを防ぎます。

CLI による初期設定を使用してコンポーネントを検出・設定し、Lightning ページ（RecordPage、AppPage、HomePage）を生成します。

---

クイックスタートのワークフロー

ステップ 1：CLI で初期設定する

新しいページでは必須です。このステップは省略できません。 新しい FlexiPage を作成する際は、必ず CLI のテンプレートコマンドを使用してください。CLI は有効な XML 構造、適切な領域、正しいメタデータを生成し、よくあるデプロイエラーを防ぎます。既存の FlexiPage ファイルを編集する場合に限り、このステップを省略してください。

sf template generate flexipage \
  --name <PageName> \
  --template <RecordPage|AppPage|HomePage> \
  --sobject <SObject> \
  --primary-field <Field1> \
  --secondary-fields <Field2,Field3> \
  --detail-fields <Field4,Field5,Field6,Field7> \
  --output-dir force-app/main/default/flexipages

重要： sf template generate flexipage コマンドが失敗した場合は、作業を中止してください。

1. テンプレートプラグインをインストールします。

   sf plugins install templates
   

2. sf template generate flexipage コマンドを再実行します
3. FlexiPage XML ファイルが作成されたことを確認します

テンプレートコマンドが成功するまで、ステップ 2 に進まないでください。生成された XML は、ワークフロー全体で必要です。

テンプレートごとの要件

RecordPage：

• --sobject が必要です（例：Account、Custom_Object__c）
• 次のフィールドパラメーターが必要です。
  • --primary-field：最も重要な識別フィールド（例：Name）
  • --secondary-fields：レコードの概要（推奨 4～6 個、最大 12 個）
  • --detail-fields：必須フィールドを含むレコードの詳細全体（例：Name）

AppPage：

• 追加要件はありません

HomePage：

• 追加要件はありません

フィールド選択ルール

• フィールドが存在することを確認する：コマンドで指定する前に、MCP ツールまたは describe コマンドを使用して、オブジェクトで利用できるフィールドを確認します
• 複合フィールドを優先する：利用できる場合は、FirstName／LastName ではなく Name、BillingStreet／BillingCity／BillingState ではなく BillingAddress、MailingAddress などを使用します
• 必須フィールドを detail-fields に含める：--primary-field または --secondary-fields でも使用している場合を含め、オブジェクトの必須フィールド（Name など）は必ず --detail-fields パラメーターに含めます

生成される内容

• 正しい構造の有効な FlexiPage XML
• 設定済みの領域と基本コンポーネント
• 正しいフィールド参照と facet 構造
• そのままデプロイすることも、さらに拡張することも可能な状態

ステップ 2：ベースページをデプロイする

ページと依存関係を検証するため、プロジェクト全体の ドライラン デプロイを実行します。

sf project deploy start --dry-run -d "force-app/main/default" --test-level NoTestRun --wait 10 --json

重要： 先に進む前に、デプロイエラーをすべて修正してください。ページの検証が正常に完了する必要があります。

ステップ 3：中止する — これ以上変更しない

必須：ステップ 2 の後で作業を中止してください。コンポーネントの追加や FlexiPage XML の編集はしないでください。

ユーザーが次の作業を依頼した場合も同様です。

• コンポーネントの追加
• ページのカスタマイズ
• コンポーネントの設定

できること：

• 役立つコンポーネントを提案する
• 可能な拡張について説明する
• 手動で追加する必要がある内容を記録する

できないこと：

• XML ファイルを変更する
• コンポーネントを追加する
• 拡張を行う

---

重要な XML ルール

1. プロパティ値のエンコード（最もよくあるエラー）

HTML／XML 文字を含むプロパティ値は、必ず次の順序で手動でエンコードしてください（順序を誤ると二重エンコードによる破損が発生します）。

1. & → &   (FIRST! Encode this before others)
2. < → &lt;
3. > → &gt;
4. " → &quot;
5. ' → &apos;

誤り：

<value><b>Important</b> text</value>

正しい例：

<value>&lt;b&gt;Important&lt;/b&gt; text</value>

XML を確認してください： <value> タグを検索し、生の < や > 文字が含まれていないことを確認します。

2. フィールド参照

必ず使用： Record.{FieldApiName}
使用禁止： {ObjectName}.{FieldApiName}

<fieldItem>Record.Name</fieldItem>

        
<fieldItem>Account.Name</fieldItem>

3. リージョンとファセットの種類

テンプレートリージョン（ヘッダー、メイン、サイドバー）:

<name>header</name>
<type>Region</type>

コンポーネントファセット（fieldSection の列などの内部スロット）:

<name>Facet-12345</name>
<type>Facet</type>

ルール: テンプレートリージョン名の場合 → Region。コンポーネントスロットの場合 → Facet。

4. fieldInstance の構造

すべての fieldInstance には以下が必要です:

<itemInstances>
   <fieldInstance>
      <fieldInstanceProperties>
         <name>uiBehavior</name>
         <value>none</value> 
      </fieldInstanceProperties>
      <fieldItem>Record.FieldName__c</fieldItem>
      <identifier>RecordFieldName_cField</identifier>
   </fieldInstance>
</itemInstances>

ルール:

• 各 fieldInstance はそれぞれ独自の <itemInstances> ラッパー内に配置する
• uiBehavior を持つ fieldInstanceProperties が必須
• Record.{Field} 形式を使用する

5. 一意の識別子とリージョン名（重要 - 重複エラーを防止）

すべての識別子およびリージョン/ファセット名は、FlexiPage ファイル全体で一意でなければなりません。

重要なルール:

• ❌ 同じ <name> を持つ 2 つの <flexiPageRegions> ブロックを絶対に作成しないでください
• ✅ 複数のコンポーネントが同じファセットに属する場合は、それらを 1 つのリージョンにまとめ、複数の <itemInstances> を持たせてください
• ❌ 同じ <identifier> 値を絶対に再利用しないでください
• ✅ 常に最初にファイル全体を読み込み、既存のすべての識別子と名前を抽出してください

誤り - これは重複名エラーで失敗します:

<flexiPageRegions>
   <itemInstances>
      <componentInstance>
         <identifier>flexipage_property_details_fieldSection</identifier>
         ...
      </componentInstance>
   </itemInstances>
   <name>detailTabContent</name>  
   <type>Facet</type>
</flexiPageRegions>


<flexiPageRegions>
   <itemInstances>
      <componentInstance>
         <identifier>flexipage_pricing_fieldSection</identifier>
         ...
      </componentInstance>
   </itemInstances>
   <name>detailTabContent</name>  
   <type>Facet</type>
</flexiPageRegions>

正しい - itemInstances を 1 つのリージョンにまとめます:

<flexiPageRegions>
   <itemInstances>
      <componentInstance>
         <identifier>flexipage_property_details_fieldSection</identifier>
         ...
      </componentInstance>
   </itemInstances>
   <itemInstances>
      <componentInstance>
         <identifier>flexipage_pricing_fieldSection</identifier>
         ...
      </componentInstance>
   </itemInstances>
   <name>detailTabContent</name>  
   <type>Facet</type>
</flexiPageRegions>

まとめる場合と分ける場合:

• まとめる: 論理的に同じタブ/セクションに属するコンポーネント（例: 詳細タブ内の複数の項目セクション）
• 分ける: 異なるタブ/セクションに属するコンポーネント（例: detailTabContent と relatedTabContent）

---

よくあるデプロイエラー

「We couldn't retrieve or load the information on the field」

原因: 無効な項目 API 名 - 項目がオブジェクトに存在しないか、スペルが正しくない 修正: MCP ツールまたは describe コマンドを使用して有効な項目を検出し、項目参照を更新します（項目選択ルールを参照）

「Invalid field reference」

原因: Record.Field ではなく ObjectName.Field を使用している 修正: Record.{FieldApiName} に変更します

「Element fieldInstance is duplicated」

原因: 1 つの itemInstances 内に複数の fieldInstance が存在する 修正: 各 fieldInstance には独自の <itemInstances> ラッパーが必要です

「Missing fieldInstanceProperties」

原因: uiBehavior が指定されていない 修正: uiBehavior を持つ fieldInstanceProperties を追加します

「Unused Facet」

原因: ファセットが定義されているが、どのコンポーネントからも参照されていない 修正: ファセットを削除するか、コンポーネントのプロパティで参照します

「XML parsing error」

原因: プロパティ値内の HTML/XML がエンコードされていない 修正: すべての <value> タグ内で <、>、&、"、' を手動でエンコードします

「Cannot create component with namespace」

原因: 無効なページ名（ページ名に __c サフィックスを使用しないでください） 修正: 「Volunteer__c_Record_Page」ではなく「Volunteer_Record_Page」を使用します

「Region specifies mode that parent doesn't support」

原因: リージョンに <mode> タグを追加している 修正: <mode> タグを削除します - 標準リージョンには不要です

---

一意の識別子の生成

重要: 新しい識別子またはファセット名を生成する前に、上記の「重要な XML ルール」のセクション 5 のルールに従ってください。

識別子生成アルゴリズム:

1. Extract ALL existing <identifier> AND <name> values from XML
2. Generate base name: {componentType}_{context}
   Examples: "relatedList_contacts", "richText_header", "tabs_main"
3. Find first available number:
   - Try "{base}_1"
   - If exists, try "{base}_2", "{base}_3", etc.
   - Use first available

例:

• 最初の contacts 関連リスト: relatedList_contacts_1
• 2 番目の contacts 関連リスト: relatedList_contacts_2
• ヘッダー内のリッチテキスト: richText_header_1
• 項目セクション: fieldSection_details_1

ファセットの命名 - 2 つのパターン:

1. 名前付きファセット（主要なコンテンツ領域向け）:

   • detailTabContent（詳細タブのコンテンツ）
   • maintabs（メインタブコンテナ）
   • sidebartabs（サイドバータブコンテナ）
   • ファセットが意味のあるコンテンツ領域を表す場合に使用します

2. UUID ファセット（内部構造向け）:

   • 形式: Facet-{8hex}-{4hex}-{4hex}-{4hex}-{12hex}
   • 例: Facet-66d5a4b3-bf14-4665-ba75-1ceaa71b2cde
   • 項目セクションの列、ネストされたコンテナ、匿名スロットに使用します

既存のファイルにコンポーネントを追加する場合:

• 対象のファセット名がすでに存在するか確認します
• 存在する場合: その既存のリージョンに新しい <itemInstances> を追加します（詳細は上記のセクション 5 を参照）
• 存在しない場合: 一意の名前で新しいリージョンを作成します

---

リージョンの選択

ファイルからリージョンを解析します — 名前をハードコードしないでください。テンプレートによって異なります。

• flexipage:recordHomeTemplateDesktop → header、main、sidebar
• runtime_service_fieldservice:... → header、main、footer
• その他のテンプレートでは、異なるリージョン名が使われる場合があります

デフォルトの配置場所：対象リージョンの末尾（最後の <itemInstances> の後）

挿入パターン：

<flexiPageRegions>
   <name>main</name>  
   <type>Region</type>
   <itemInstances></itemInstances>
   <itemInstances></itemInstances>
   <itemInstances>
      
   </itemInstances>
</flexiPageRegions>

---

ファセットを持つコンテナコンポーネント

タブ、アコーディオン、項目セクションなどのコンポーネントにはファセットが必要です。

パターン：

<flexiPageRegions>
   <itemInstances>
      <componentInstance>
         <componentName>flexipage:tabset2</componentName>
         <identifier>tabs_main_1</identifier>
         <componentInstanceProperties>
            <name>tabs</name>
            <value>tab1_content</value>
            <value>tab2_content</value>
         </componentInstanceProperties>
      </componentInstance>
   </itemInstances>
   <name>main</name>
   <type>Region</type>
</flexiPageRegions>

        
<flexiPageRegions>
<itemInstances></itemInstances>
<name>tab1_content</name>
<type>Facet</type>
</flexiPageRegions>

<flexiPageRegions>
<itemInstances></itemInstances>
<name>tab2_content</name>
<type>Facet</type>
</flexiPageRegions>

重要：ファセットのリージョンはテンプレートリージョンの子ではなく、同じ階層にある兄弟要素です。

コンポーネント固有のヒント

dynamicHighlights（レコードページのヘッダー）

場所： header リージョンに配置する必要があります。 明示的な項目（CLI 経由）：レコードの概要を表示するために、最も重要な項目を使用します。単一の主項目は、名前など、レコードの識別に使用します。副項目（最大 12 個、推奨 6 個）は、レコードの概要として使用します。

--primary-field Name
--secondary-fields Phone,Industry,AnnualRevenue

CLI は項目参照を含むファセットを自動的に生成します。

fieldSection

用途： 項目を列に表示します。 構造： 3 階層のネスト：

1. テンプレートリージョン（リージョンタイプ）
2. 列ファセット（ファセットタイプ）
3. 項目ファセット（ファセットタイプ） コンポーネントプロパティでの参照：

<componentInstanceProperties>
   <name>columns</name>
   <value>Facet-{uuid}</value>
</componentInstanceProperties>

リッチテキストコンポーネント

コンポーネント名：flexipage:richText

用途：テキストの書式設定、見出し、リスト、表、画像、リンク、フォーム、マルチメディア要素に対応した、HTML 形式のリッチテキストコンテンツを表示します。スタイルとレイアウトを保持します。デフォルトテキスト内の特殊文字はすべてエスケープしてください。

場所：任意のページタイプ（ホーム、レコード、アプリ、コミュニティページ）の任意のリージョンで使用できます。

CLI はネストした構造を使わずに、コンポーネントを直接生成します。

ユーザー：「force-app/.../Account_Record_Page.flexipage-meta.xml にリッチテキストコンポーネントを追加してください」

構造：単一階層のコンポーネント（ファセットなし）：

1. コンポーネントインスタンス（flexipage:richText）と直接のプロパティ

XML 構造の例：

<itemInstances>
   <componentInstance>
      <componentInstanceProperties>
         <name>decorate</name>
         <value>true</value>
      </componentInstanceProperties>
      <componentName>flexipage:richText</componentName>
      <identifier>flexipage_richText</identifier>
   </componentInstance>
</itemInstances>

識別子のパターン：flexipage_richText または flexipage_richText_{sequence}

---

必須のメタデータ構造

<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
   <flexiPageRegions>
      
   </flexiPageRegions>
   <masterLabel>Page Label</masterLabel>
   <template>
      <name>flexipage:recordHomeTemplateDesktop</name>
   </template>
   <type>RecordPage</type>
   <sobjectType>Object__c</sobjectType> 
</FlexiPage>

ページタイプ：

• RecordPage — <sobjectType> が必要です
• AppPage — sobjectType は不要です
• HomePage — sobjectType は不要です

---

検証チェックリスト

デプロイ前に確認します。

• [新しいページのみ] CLI を使用して初期化します — FlexiPage XML を最初から作成してはいけません
• すべての識別子が一意であること — ファイル内の <identifier> 値に重複がない
• すべてのリージョン名／ファセット名が一意であること — <flexiPageRegions> 内の <name> 値に重複がない
• 同じファセット内の複数のコンポーネントがまとめられていること — 同じ名前のリージョンを個別に作成するのではなく、複数の <itemInstances> を含むリージョンを 1 つ使用する
• すべての項目参照が Record.{Field} 形式である
• 各 fieldInstance に uiBehavior を含む fieldInstanceProperties がある
• 各 fieldInstance が独自の <itemInstances> ラッパー内にある
• テンプレートリージョンが <type>Region</type> を使用している
• コンポーネントファセットが <type>Facet</type> を使用している
• HTML／XML を含むプロパティ値が手動でエンコードされている
• リージョンに <mode> タグがない
• ページ名に __c サフィックスがない
• 各ファセットがコンポーネントプロパティからちょうど 1 回参照されている

---

クイックリファレンス：CLI コマンド

# RecordPage with fields
sf template generate flexipage \
  --name Account_Custom_Page \
  --template RecordPage \
  --sobject Account \
  --primary-field Name \
  --secondary-fields Phone,Industry,AnnualRevenue \
  --detail-fields Street,City,State,Name,Phone,Email

# AppPage
sf template generate flexipage \
  --name Sales_Dashboard \
  --template AppPage \
  --label "Sales Dashboard"

# HomePage
sf template generate flexipage \
  --name Custom_Home \
  --template HomePage \
  --description "Custom home for sales team"

すべてのテンプレートで使用できます：

• --output-dir（デフォルト：カレントディレクトリ）
• --api-version（デフォルト：最新）
• --label（デフォルト：ページ名）
• --description