platform-custom-lightning-type-generate

何時使用此技能

當您需要以下情況時，使用此技能：

• 為結構化輸入/輸出建立自訂 Lightning 類型（CLT）
• 為 Lightning Platform 產生以 JSON Schema 為基礎的類型定義
• 為 Einstein Agent 動作設定 CLT
• 設定自訂 UI 的編輯器與轉譯器設定
• 排解與自訂 Lightning 類型相關的部署錯誤

規格

CustomLightningType 中繼資料規格

概觀與目的

自訂 Lightning 類型（CLT）是以 JSON Schema 為基礎的類型定義，由 Lightning Platform（包括 Einstein Agent 動作）用來描述結構化輸入/輸出，並驅動編輯器/轉譯器體驗。

設定

• 為巢狀物件選擇參考 CLT 模式 - 當您需要可重複使用或單獨部署的巢狀類型時，為該形狀建立 CLT，並使用 "lightning:type": "c__<CLTName>" 參考它。該字串是參考類型的 lightning:type 值 / FQN / 註冊識別碼——不是 JSON Schema 的 title。
• 當結構簡單且可用屬性與支援的基本 lightning:type 識別碼表達時，選擇標準 Lightning 類型。
• 當結構已存在於伺服器端，且您希望 Apex 類別定義形狀時，選擇 Apex 類別類型（@apexClassType/...）。
• 僅在需要自訂 UI 行為（自訂 LWC 輸入/輸出元件）時，才包含編輯器/轉譯器設定。否則，省略。

關鍵規則（請先閱讀）

• 關鍵：絕對不要在 schema.json 中包含 "$schema" 欄位
  • Salesforce CLT 驗證器會拒絕包含此欄位的結構描述，即使它是有效的 JSON Schema $schema 宣告。
• 根物件結構描述必須包含：
  • "type": "object"
  • "title"
  • "lightning:type": "lightning__objectType"
  • "unevaluatedProperties": false
• "unevaluatedProperties" 由 CLT 中繼結構描述強制為 false。請勿將其設為 true。
• 當設定 "unevaluatedProperties": false 時，根物件結構描述不得包含 "examples"。
• 巢狀物件（在 properties 內）不得設定 "lightning:type": "lightning__objectType"。
  • 巢狀物件可以是：使用 c__<CLTName> 語法參考其他 CLT。
• 清單/陣列屬性受到 CLT 中繼結構描述的高度限制：
  • 關鍵限制：CLT 中繼結構描述可能完全拒絕 items 關鍵字。將 items 視為預設不允許。
  • 根層級陣列（根 properties 的直接子項）：
    • 必須包含 "lightning:type": "lightning__listType"
    • 不得包含 "items"
    • 可選 "type": "array"
  • 巢狀陣列（巢狀物件內的陣列）是最常見的失敗原因：
    • 必須包含 "type": "array"
    • 不得包含 "lightning:type": "lightning__listType"
    • 不得包含 "items"
• 當設定 "unevaluatedProperties": false 時，任何未知關鍵字都會導致驗證失敗。建議移除關鍵字，而不是放寬嚴格性。
• Apex 類別 CLT 是最精簡的：
  • 僅包含** title、description（可選）和 lightning:type 設為 @apexClassType/...。
  • 請勿**新增 type、properties、required 或 unevaluatedProperties。
• 沒有會觸發 Vibes 安全 shell 篩選器的 shell 中繼字元。 在此技能發出的任何 Bash 工具呼叫中，請勿使用命令替換（$(…) 或反引號）、程序替換（<(…)、>(…)）、大括號展開（{a,b,c} 或 {1..N}）或 eval / exec。Vibes 即使在 Bypass 模式下也會強制手動核准這些模式，並阻礙評估。請發出單獨的命令（mkdir -p a && mkdir -p b）或使用各自的命令列印每個值，並根據輸出進行推理，而不是將其捕獲到 shell 變數中。

其他 CLT 中繼結構描述驗證

• 組織命名空間驗證：標題/描述和其他字串欄位可能會被驗證，以確保您沒有在不允許的地方使用組織命名空間。
• Lightning 類型驗證：CLT 會經過驗證，以防止參考內部命名空間（例如，在不允許的地方禁止來自內部命名空間（如 sfdc_cms）的類型）。
• 物件類型驗證：CLT 根會經過驗證，以確保 lightning:type 正好是 lightning__objectType。

基本類型與限制

當您需要支援的基本 lightning:type 識別碼的完整清單、其限制以及允許的屬性層級關鍵字時，請閱讀此技能目錄中的 assets/primitive-types-and-constraints.md。

產生工作流程

1. 確認 CLT 方法
   • 如果參考 Apex：捕獲確切的類別參考（@apexClassType/namespace__ClassName$InnerClass）。
   • 如果使用標準基本類型：列出欄位、其 Lightning 基本類型，以及哪些欄位是必填的。
2. 草擬 schema.json
   • 請勿在頂部包含 "$schema"
   • 從根物件結構開始（必要的根欄位）。
   • 使用有效的基本 lightning:type 識別碼新增 properties。
   • 對於巢狀物件屬性，使用 CLT 參考模式：
     • "lightning:type": "c__<CLTName>" 以參考另一個 CLT
     • 參考的 CLT 必須先部署到組織，然後才能部署父 CLT。
   • 對於以 Apex 為基礎的巢狀物件：當結構存在於伺服器端時，使用 @apexClassType/...。
   • 如果提示明確要求真正的巢狀物件輸出，請優先使用以 Apex 為基礎的 CLT（@apexClassType/...）以獲得可安全部署的巢狀結構。
   • 對於陣列：遵循嚴格的清單規則（避免 items；避免在巢狀陣列中使用 lightning:type）。
   • 在部署之前，驗證確切的 lightning:type 拼寫（例如，使用 lightning__richTextType，而不是拼寫錯誤的變體）。
3. （可選）草擬 editor.json（僅在需要自訂 UI 時）
   • 支援的形狀： 頂層 editor 物件，包含 editor.componentOverrides 和 editor.layout。
     • 頂層 editor 物件。
     • 使用 editor.componentOverrides 進行元件覆寫。
     • 使用 editor.layout 進行版面配置。
     • 已棄用：請勿使用 propertyRenderers 或 view——這些是舊版關鍵字。一律使用 componentOverrides 和 layout 代替。
   • 根覆寫模式（最常見於完全自訂的編輯 UI）：
     • editor.componentOverrides["$"] = { "definition": "c/<yourEditorComponent>", "attributes": { ... } }
     • 將結構描述資料傳入自訂 LWC 時，使用 {!$attrs.<name>} 語法進行屬性對應：例如 "attributes": { "myField": "{!$attrs.value}" }，以便執行階段將結構描述值繫結到元件的屬性。
     • 關鍵：{!$attrs.<name>} 中的 <name> 必須是類型結構描述中定義的屬性。例如，如果您的結構描述有一個名為 temperature 的屬性，請使用 {!$attrs.temperature}，而不是 {!$attrs.value}，除非 value 是實際屬性。
   • 屬性層級覆寫模式（適用於個別欄位）：
     • editor.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/<...>" }
     • 有效的編輯器元件（範例）：es_property_editors/inputText、es_property_editors/inputNumber、es_property_editors/inputRichText、es_property_editors/inputImage、es_property_editors/inputTextarea。請勿使用 es_property_editors/inputList。
   • 集合編輯器（適用於根層級 lightning__listType 屬性）：使用集合層級覆寫，以便清單由自訂元件編輯：collection.editor.componentOverrides["$"] = { "definition": "c/<yourCollectionEditorComponent>" }。或者，使用 editor.layout 搭配 lightning/propertyLayout 和 attributes.property = "<listPropertyName>" 進行預設清單編輯。
   • 版面配置模式：
     • editor.layout.definition = "lightning/verticalLayout"
     • editor.layout.children[*].definition = "lightning/propertyLayout" 搭配 attributes.property = "<propertyName>"
     • 關鍵：lightning/propertyLayout 僅接受 property 屬性。請勿新增 label、title 或任何其他屬性——這些會因 additionalProperties: false 錯誤而驗證失敗。
   • 避免已知無效的模式：
     • 請勿使用 es_property_editors/inputList。
     • 請勿使用 itemSchema 屬性。
4. （可選）草擬 renderer.json（僅在需要自訂 UI 或 Widget 呈現時）
   • 支援的形狀： 頂層 renderer 物件，包含 renderer.componentOverrides 和 renderer.layout。
     • 頂層 renderer 物件。
     • 使用 renderer.componentOverrides 進行元件覆寫。
     • 使用 renderer.layout 進行版面配置。
     • 已棄用：請勿使用 propertyRenderers 或 view——這些是舊版關鍵字。一律使用 componentOverrides 和 layout 代替。
   • Widget 呈現模式（參考現有的 WidgetBundle 作為根轉譯器）：轉譯器檔案是一個精簡包裝器，透過開發人員名稱（"definition": "@widget/c/<widgetDeveloperName>"）指向 Widget，並透過 {!$attrs.<schemaPropertyName>} 將 CLT 結構描述屬性對應到 Widget 屬性。請勿**在 renderer.json 中重複 Widget 主體。請參閱 references/widget-rendition.md 以了解完整形狀、繫結規則和限制。如需完整的 Apex → Lightning Type → Widget 管線，請使用 platform-lightning-type-widget-coordinate 協調器，而不是此技能。
   • 根覆寫模式（最常見於使用自訂 LWC 的完全自訂呈現 UI）：
     • renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
     • 在將結構描述資料繫結到自訂轉譯器元件屬性時，在屬性對應中使用 {!$attrs.<name>}。
     • 關鍵：屬性對應（如 {!$attrs.propertyName}）必須參考類型結構描述中實際存在的屬性。參考不存在的屬性將導致驗證失敗。
     • 類型比對：屬性值必須符合元件的預期類型。例如，如果元件預期字串屬性，傳入整數將導致驗證失敗。
   • 屬性層級覆寫模式：
     • renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }。有效的轉譯器元件（範例）：es_property_editors/outputText、es_property_editors/outputNumber、es_property_editors/outputImage。避免在轉譯器中使用輸入樣式元件。
   • 轉譯器的版面配置模式：
     • renderer.layout.definition = "lightning/verticalLayout"
     • renderer.layout.children[*].definition = "lightning/propertyLayout" 搭配 attributes.property = "<propertyName>"
     • 關鍵：與編輯器版面配置相同，lightning/propertyLayout 僅接受 property 屬性。請勿新增 label、title 或任何其他屬性。
   • 集合轉譯器（適用於根層級 lightning__listType 屬性）：使用 collection.renderer.componentOverrides["$"] = { "definition": "c/<yourListRendererComponent>" } 或 es_property_editors/genericListTypeRenderer 來呈現清單。
5. 將檔案放在正確的套件結構中
   • lightningTypes/<TypeName>/schema.json
   • （可選）lightningTypes/<TypeName>/lightningDesktopGenAi/editor.json
   • （可選）lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json
   • 對於 Gen AI / Copilot，標準路徑是 lightningDesktopGenAi/。其他目標（例如 Experience Builder、Mobile Copilot、Enhanced Web Chat）在支援時使用不同的子資料夾：experienceBuilder/、lightningMobileGenAi/、enhancedWebChat/。
6. 設定自訂 LWC 元件（如果使用自訂元件）
   • 關鍵：在編輯器/轉譯器設定中參考的自訂 LWC 元件必須在其 -meta.xml 檔案中具有正確的目標設定：
     • 對於編輯器元件（在 editor.json 中使用的 c/<componentName>）：LWC 的 -meta.xml 檔案必須包含 <target>lightning__AgentforceInput</target>
     • 對於轉譯器元件（在 renderer.json 中使用的 c/<componentName>）：LWC 的 -meta.xml 檔案必須包含 <target>lightning__AgentforceOutput</target>
   • 沒有正確的目標，部署將失敗，並出現：Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.
   • 轉譯器元件的 -meta.xml 範例：

     <?xml version="1.0" encoding="UTF-8"?>
     <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
         <apiVersion>60.0</apiVersion>
         <isExposed>true</isExposed>
         <targets>
             <target>lightning__AgentforceOutput</target>
         </targets>
     </LightningComponentBundle>
     

常見部署錯誤

錯誤 / 症狀	可能原因	修正
結構描述驗證因未知關鍵字而失敗	unevaluatedProperties: false + 不允許的關鍵字（通常是 examples、items）	移除有問題的關鍵字；保持結構描述精簡
巢狀物件驗證失敗	組織/通道驗證拒絕 LightningTypeBundle 中的巢狀物件類型	使用 CLT 參考（c__<CLTName>）或 Apex 類別類型
無效的 CLT 參考	參考的 CLT 不存在於組織中，或語法不正確	先部署參考的 CLT；c__<CLTName> 必須符合參考類型的 lightning:type 值 / FQN / 註冊識別碼，而不是 title
無效或拼寫錯誤的 lightning:type（例如，lightning__richtextType 而不是 lightning__richTextType）	產生的類型名稱不正確	交叉檢查所有 lightning:type 值與支援的類型名稱，並在部署前修正
陣列屬性被拒絕	使用 items（或巢狀陣列中的 lightning:type）被驗證器拒絕	對於巢狀陣列：僅保留 type: "array"。對於根陣列：使用精簡結構；如果被拒絕，移除 items
以 Apex 為基礎的 CLT 被拒絕	新增了額外欄位（例如，type、properties）	僅使用 title、可選的 description 和 lightning:type
編輯器設定被拒絕	使用無效模式（es_property_editors/inputList、itemSchema）或無法識別的頂層鍵	使用 editor.componentOverrides 和 editor.layout；保持設定精簡
版面配置屬性上的 additionalProperties 錯誤	在 lightning/propertyLayout 中新增 label 或其他屬性	僅在 lightning/propertyLayout 中使用 property 屬性。移除 label、title 或任何其他屬性
自訂 LWC 的目標設定無效	自訂 LWC 元件的 -meta.xml 缺少必要的目標（lightning__AgentforceInput 或 lightning__AgentforceOutput）	在 LWC 的 -meta.xml 中新增正確的目標：編輯器使用 lightning__AgentforceInput，轉譯器使用 lightning__AgentforceOutput
屬性對應不存在於類型結構描述中	使用 {!$attrs.propertyName}，但 propertyName 未在結構描述中定義	確保所有屬性對應都參考類型結構描述 properties 區段中的實際屬性
使用已棄用鍵時出現 additionalProperties 錯誤	在編輯器/轉譯器設定中使用 propertyRenderers 或 view	將已棄用的 propertyRenderers 替換為 componentOverrides，並將 view 替換為 layout
元件屬性中的類型不符	為元件屬性傳入錯誤的類型（例如，整數而不是字串）	確保屬性值符合元件定義的預期類型

驗證檢查清單

• [ ] 根結構描述具有 type: "object"、title、lightning:type: "lightning__objectType" 和 unevaluatedProperties: false
• [ ] 啟用嚴格驗證時，根結構描述不包含 examples
• [ ] 沒有巢狀物件包含 lightning:type: "lightning__objectType"
• [ ] 陣列以精簡方式定義（尤其是巢狀陣列）
• [ ] 僅對葉子屬性使用支援的基本 lightning:type 識別碼
• [ ] Apex 類別 CLT 僅包含 title/description 和 lightning:type: "@apexClassType/..."
• [ ] 套件結構和檔案名稱符合 Lightning Types 要求
• [ ] 編輯器設定僅使用允許的模式（沒有 es_property_editors/inputList、沒有 itemSchema）；使用有效的元件（例如 es_property_editors/inputText、es_property_editors/inputNumber）或自訂 c/ 元件
• [ ] 轉譯器設定在適用的地方使用輸出樣式元件（例如 es_property_editors/outputText、es_property_editors/outputNumber），而不是輸入編輯器
• [ ] 版面配置設定使用 lightning/propertyLayout，且僅使用 property 屬性（沒有 label、title 或其他屬性）
• [ ] 所有屬性對應（{!$attrs.propertyName}）都參考類型結構描述中存在的屬性
• [ ] 自訂 LWC 元件在 -meta.xml 中具有正確的目標：編輯器使用 lightning__AgentforceInput，轉譯器使用 lightning__AgentforceOutput
• [ ] 根結構描述不包含 "$schema" 欄位