platform-custom-lightning-type-generate

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（可选）和设置为 @apexClassType/... 的 lightning:type。
- 不要添加 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。

生成工作流

确认 CLT 方法
- 如果引用 Apex：捕获确切的类引用（@apexClassType/namespace__ClassName$InnerClass）。
- 如果使用标准原始类型：列出字段、它们的 Lightning 原始类型以及哪些字段是必需的。
起草 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，而不是拼写错误的变体）。
（可选）起草 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 属性。
（可选）起草 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 来渲染列表。
将文件放置在正确的捆绑包结构中
- 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/。
配置自定义 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" 字段

你可能还喜欢

skill-creator

385Kagent-workflows

Create, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files.

steipete

获取

homelab-vlan-segmentation

238Kagent-workflows

Segmenting home networks into VLANs for IoT, guest, trusted, and server traffic using UniFi, pfSense/OPNsense, and MikroTik — including switch trunk config, firewall rules, and wireless SSID mapping.