avonni-lwc-components

avonni-lwc-components

每当需要在 LWC 组件中添加或使用 Avonni 组件时，都要使用此技能。此技能规定了如何通过 MCP 发现、配置和验证 Avonni 组件，而不涉及如何搭建周边的 LWC。

工具集

此技能仅适用于 Avonni MCP 的 lwc 工具集。所有 MCP 工具调用都必须在适用时包含 toolset: "lwc"。请勿将此技能用于 Avonni Dynamic Components、Avonni Experience Sites 组件或 Avonni Flow Screen Components。

如果当前会话中没有 Avonni MCP 工具，请停止操作，并让用户配置包含 lwc 工具集的 Avonni MCP 服务。切勿在没有 MCP 的情况下继续操作。

权威性

• MCP 是所有 Avonni 组件 API 的唯一事实来源。
• 切勿依赖对组件的既有认知或假设。
• 如果 MCP 数据与既有认知冲突，以 MCP 数据为准。
• 如果缺少必要信息，不要猜测——请询问用户。
• **切勿虚构组件、属性、事件、方法、插槽或对象键。**只能使用 MCP 明确记录的内容。

步骤

1. 理解请求——确定所需功能以及可能涉及的 Avonni 组件。
2. 使用 toolset: "lwc" 调用 list_components——获取当前可用组件列表。切勿跳过此步骤。
3. 选择组件——根据下方的选择标准，选出最能满足请求的组件。
4. 对每个选定的组件使用 toolset: "lwc" 调用 get_component_docs——每个组件调用一次，切勿在不同组件间重复使用文档。
5. 对属性、事件或返回值中引用的每个非基本类型调用 get_type。
6. 递归解析嵌套类型——重复调用 get_type，直到完全了解所有类型。
7. 对每个需要设置样式的组件调用 get_component_styles 并使用 toolset: "lwc"——仅当用户请求涉及 CSS 或视觉自定义时才调用。
8. 验证——编写任何代码之前，先运行下方的检查清单。
9. 生成代码——仅使用 MCP 已确认的内容编写 HTML、JS 和/或 CSS。

不得跳过或调整这些步骤的顺序。

组件选择

如果有多个组件都能满足需求，优先选择符合以下条件的组件：

1. 所需自定义逻辑最少
2. 利用内置数据功能（查询／映射 API）
3. 产生的额外代码最少

尽可能复用已有组件实例。

属性规则

• 属性名称必须与 MCP 中的名称完全一致。
• 在 JS 中使用 camelCase，在 HTML 模板中使用 kebab-case。
• 始终包含必需属性。
• 如果属性值等于文档中的默认值，则省略该属性。
• 仅使用已解析类型架构中定义的对象键。
• 对于任何非基本属性，使用前都必须获取其类型定义。

复杂类型

• 当组件引用复杂类型（即非基本类型，例如 DdListMapping 或 DdListAvatar）时，在编写任何使用该类型的代码之前，必须使用该类型的确切名称调用 get_type。
• 存在多个嵌套类型时，递归调用 get_type 获取每个引用的嵌套类型，直到代码中使用的所有类型都已解析。

事件规则

• 仅使用组件 MCP 文档中列出的事件。
• HTML 中的事件处理器属性必须使用小写（例如 onvaluechange）。
• 只能通过 event.detail 访问负载。
• 仅使用事件架构中记录的属性。

数据驱动型组件

• 切勿自行查询 Salesforce 数据。
• 使用组件内置的 query 和 mapping API。
• 每个查询都必须包含 objectApiName。
• filter 必须是有效的 SOQL WHERE 子句，且不包含 WHERE 关键字。
• orderBy 必须是有效的 SOQL ORDER BY 语法，且不包含 ORDER BY 关键字。
• 所有引用的字段都必须存在于所查询的对象上。
• 模板表达式必须使用准确语法 {{Record.FieldApiName}}（区分大小写，可用于任意嵌套层级）。

插槽规则

• 插槽列在组件文档的 slots 数组中。
• 每个插槽都有一个 name 和一个 description。
• 名为 "default" 的插槽是 LWC 中未命名的默认插槽——不要给其子元素添加 slot 属性：

  <avonni-alert-banner>
      <p>此内容会放入默认插槽。</p>
  </avonni-alert-banner>
  

• 命名插槽（名称不是 "default"）要求子元素带有匹配的 slot 属性：

  <avonni-some-component>
      <p slot="actions">此处放置操作内容。</p>
  </avonni-some-component>
  

• 一个组件可以有多个插槽；每个插槽独立使用。
• 没有内容可放入插槽时，绝不要添加该插槽。 生成的代码中应完全省略空插槽。
• 绝不要使用组件文档中未列出的插槽名称。
• 如果组件文档没有 slots 数组（或该数组为空），则该组件不接受插槽内容——不要添加用于插槽投影的子元素。

样式规则

• 要为 Avonni 组件设置样式，必须先为该组件调用 get_component_styles，并设置 toolset: "lwc"。
• get_component_styles 会返回该组件公开的所有 CSS 自定义属性（样式钩子）及其默认值。
• 只能使用 get_component_styles 返回的 CSS 变量——不要臆造变量名称。
• 在组件的 CSS 文件中使用标准 CSS 自定义属性语法应用样式钩子：

avonni-some-component {
    --avonni-some-component-color-background: #f0f0f0;
}

• 每个组件只调用一次 get_component_styles——缓存结果，不要为同一个组件再次调用。
• 如果 get_component_styles 返回空列表，则该组件没有公开的样式钩子；请告知用户。

实用函数

Avonni LWC 包公开了一个实用函数：removePageHeader。

• 使用前先调用 get_util_docs，并设置 name: "removePageHeader"——不要依赖先前对其签名的了解。
• 仅在用户明确需要隐藏 Salesforce 页面标题时使用。
• 在 LWC JS 文件的生命周期钩子（例如 connectedCallback）中调用。

验证清单

生成最终代码前，请确认以下各项：

• MCP 列表中存在每个组件
• 组件文档中存在每个属性名称
• 组件文档中存在每个事件名称
• 组件文档中存在每个方法名称
• 使用每个非基本类型前都已调用 get_type
• 每个对象键都存在于已解析的类型架构中
• 已包含所有必需属性
• 未使用任何未记录的 API
• 使用的每个插槽名称都存在于组件的 slots 数组中
• 未渲染任何空插槽
• 样式中使用的每个 CSS 变量都由 get_component_styles 返回

输出代码前，请修复所有问题。

错误处理

情况	操作
工具调用失败	重试一次
工具调用再次失败	停止；没有 Avonni MCP 服务，此技能无法运行
一个组件的文档获取失败	继续处理成功的组件；报告获取失败的组件
列表中未找到组件	告知用户该组件可能不存在或尚无文档
运行时验证失败	重新检查 MCP 文档，再判断组件是否有问题

代码风格

• 遵循工作区的 LWC 格式和文件结构约定。
• 优先使用组件 API 和内置功能，而不是自定义包装逻辑。
• 将文档中的示例用作结构参考，但应根据实际请求调整所有值。