generating-custom-lightning-type

何时使用此技能

在需要以下操作时使用此技能：

• 为结构化输入/输出创建自定义 Lightning 类型（CLT）
• 为 Lightning Platform 生成基于 JSON Schema 的类型定义
• 为 Einstein Agent 操作配置 CLT
• 为自定义 UI 设置编辑器和渲染器配置
• 创建采用 widget/mosaic/fragment 呈现方式的 CLT
• 排查与自定义 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" 字段
  • 即使该字段是有效的 JSON Schema $schema 声明，Salesforce CLT 验证器也会拒绝包含此字段的架构。
• 根对象架构必须包含：
  • "type": "object"
  • "title"
  • "lightning:type": "lightning__objectType"
  • "unevaluatedProperties": false
• CLT 元架构会将 "unevaluatedProperties" 强制设为 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（可选）以及设为 @apexClassType/... 的 lightning:type。
  • 不要添加 type、properties、required 或 unevaluatedProperties。

其他 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}；除非 value 是实际属性，否则不要使用 {!$attrs.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 或 mosaic 呈现时）
   • 支持的结构： 顶层 renderer 对象，包含 renderer.componentOverrides 和 renderer.layout。
     • 顶层 renderer 对象。
     • 使用 renderer.componentOverrides 配置组件覆盖。
     • 使用 renderer.layout 配置布局。
     • 已弃用：不要使用 propertyRenderers 或 view——这些是旧版键。始终改用 componentOverrides 和 layout。
   • 根覆盖模式（完全自定义呈现 UI 时最常用）：
     • renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
     • 将架构数据绑定到自定义呈现组件属性时，在属性映射中使用 {!$attrs.<name>}。
     • 重要：{!$attrs.propertyName} 之类的属性映射必须引用类型架构中实际存在的属性。引用不存在的属性会导致验证失败。
     • 类型匹配：属性值必须与组件所需的类型相匹配。例如，组件需要字符串属性时，传入整数会导致验证失败。
   • Widget 呈现模式（适用于 widget 呈现）：
     • 适用场景： 当用户要求为其 CLT 提供“mosaic”“widget”“fragment”或“跨平台呈现”时使用。
     • 结构： renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }
     • 必须遵循的工作流：
       • 停止：不要尝试自行创建 widget 呈现。
       • 首要步骤（必须执行）：继续之前，必须先获取此技能目录中的参考文件 references/widget-rendition.md。
       • 遵循 widget-rendition.md 中记录的完整工作流，并以生成的 CLT 架构作为基础架构。
       • widget-rendition.md 参考文件包含完整的 widget 生成工作流：通过 discoverUiComponents 发现 UEM 区块、调用 getUiComponentSchemas、构建 UEM 树以及编写 renderer.json。
       • 未先获取 widget-rendition.md 参考文件时，不要尝试生成 widget 呈现。
   • 属性级覆盖模式：
     • 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/..."
• Bundle 结构和文件名符合 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 中具有正确的 targets：编辑器使用 lightning__AgentforceInput，渲染器使用 lightning__AgentforceOutput
• 根架构不包含 "$schema" 字段