experience-lwc-base-components-integrate

使用 Lightning 基础组件

Lightning 基础组件（LBC）是 Salesforce 提供的 lightning-* Web 组件。这项技能会引导 Agent 按照正确的决策流程进行选择，确保最终选用的组件尽可能具体，并有真实 API 文档作为依据，而不是手工重新实现已有功能。

何时使用这项技能

• 用户描述了 UI 需求（例如“可搜索下拉菜单”“记录编辑表单”“带页脚的模态框”），并询问适合使用哪个 lightning-* 组件。
• 用户准备构建基础组件（例如按钮组、组合框、toast），但实际上应该使用 LBC。
• 用户要求检查 LWC 标记中的 LBC 相关问题，尤其是覆盖 SLDS 类或重新设置 LBC 内部样式。
• 用户需要了解特定 lightning-* 标签的权威属性、事件和插槽信息。

前提条件

• 了解组织使用的 LBC 命名空间（lightning 是默认的公共命名空间；某些平台会提供 lightning-community 或其他命名空间——用户的元文件会说明具体情况）。
• 这项技能包含每个 Lightning 基础组件的权威 API 文档，见 references/lightning-components.md。每个组件都对应一个 # Component API Structure 区块；搜索 **Name:** <camelCaseName>（例如 **Name:** datatable）即可跳转到其属性、方法、事件和插槽。请阅读该文档，而不要依赖缓存的知识——LBC 会不断更新，参考文档才是权威来源。

工作流

第 1 步——先阅读完整的组件索引

打开 lightning-component-index.md，并在做出任何选择前浏览所有条目。这一点不可妥协：LBC 的价值在于选用最专用的组件，跳过浏览可能导致用基础组件重新实现复合组件。

浏览时，请整理一份候选清单——列出描述涉及用例任何方面的所有组件。此时不要筛选或排序。

第 2 步——针对每项功能缩小范围，选出最具体的匹配项

浏览完成后：

• 针对用例中的每项功能，选择能够满足需求的最具体组件。如果专用复合组件（lightning-record-form、lightning-tabset、lightning-datatable）能够端到端覆盖场景，应优先于通用基础组件（lightning-input、lightning-button）。
• 避免重复：如果 lightning-record-form 已经为记录呈现字段，就不要再搭配 lightning-input-field，除非你明确要覆盖其行为。

第 3 步——分享候选名单并确认

向开发者展示最终候选名单，并为每个组件提供一句理由。等待明确确认后再获取完整 API 文档。这可以避免 Agent 将上下文消耗在开发者心中已经排除的组件上。

第 4 步——获取完整 API 文档

确认后，使用随附的辅助工具提取准确的 API 区块——这样可以避免在大型参考文档中临时搜索：

scripts/extract-component-docs.sh <camelCaseName> [<camelCaseName>...]

将 lightning-<foo> 标签转换为 camelCase（去掉 lightning- 前缀）：

• lightning-datatable → datatable
• lightning-record-edit-form → recordEditForm
• lightning-button-icon → buttonIcon

每个返回的区块结构相同：基本信息（标签、命名空间、类型）、属性（名称、类型、默认值、说明）、方法、事件、插槽，以及（适用时的）使用说明。这项技能侧重于选择组件；随附的参考文档则侧重于如何接入组件。

第 5 步 — 提供集成指导

使用每个组件的参考文档，指导开发者了解：

• 确切的 <lightning-...> 标签和必需属性。
• 要绑定哪些事件（onchange、oncommit、onsuccess，等等），以及事件载荷包含什么。
• 需要填充哪些插槽（页眉、页脚、自定义内容）。
• 组件文档中列出的已知限制（例如，lightning-record-form 在编辑/查看模式下需要 object-api-name 和 record-id）。

第 6 步 — 遵循 LBC 样式规则

不要覆盖 LBC 内部使用的 SLDS 类。具体说明请参阅 lbc-expert-guidance.md。 常见问题：

• 在宿主组件的 CSS 中使用 .slds-button 或 .slds-input 来重新设置 LBC 的样式 — LBC 位于 shadow root 中，因此这些选择器要么会泄漏到相邻组件，要么会被完全剥除。请改用组件文档中说明的样式钩子（--sds-c-button-*，等等）。
• 仅为修改 LBC 内部标记而给它套一层包装。你做不到 — 这些标记被隐藏在 shadow root 后面。如果组件没有提供你需要的插槽/属性，那是平台级缺口，而不是重新设置样式的问题。

示例

示例 —“我需要一个支持输入提示的多选组合框”

1. 从头到尾扫描组件索引。
2. 候选列表包括：lightning-combobox、lightning-dual-listbox、 lightning-record-picker。
3. 缩小候选范围：lightning-dual-listbox（文档说明的多选基础 组件）。排除 lightning-combobox — 其文档说明的 API 只支持单选；它没有 type="multi"，也没有多选模式。 指出只有在值为记录 ID 时，lightning-record-picker 才适用。
4. 开发者确认使用 lightning-dual-listbox。
5. 运行 scripts/extract-component-docs.sh dualListbox。
6. 从块的 Properties / Events 部分返回 options、value、onchange 载荷和必需的 label 属性。

示例 —“我打算自己写一个模态框”

1. 扫描发现 lightning-modal、lightning-modal-body、 lightning-modal-footer、lightning-modal-header。
2. 候选范围是这 4 个模态框组件。
3. 确认。
4. 运行 scripts/extract-component-docs.sh modal modalHeader modalBody modalFooter → 完整的模态框 API（如何扩展 LightningModal、静态 .open() 模式，以及如何设置页眉/正文/页脚插槽）。
5. 劝开发者不要自行实现对话框。

验证清单

• 在进行任何选择之前，已扫描完整的组件索引（未走按关键词搜索的捷径）。
• 候选列表包含涉及该使用场景的所有组件。
• 最终候选范围为每项功能选择了最具体的组件。
• 在打开整合后的组件参考文档之前，开发者已确认候选范围。
• 集成指导引用了真实 API 文档中的属性 / 事件 / 插槽（而非推断）。
• 没有建议通过覆盖 SLDS 类来重新设置 LBC 的样式。

故障排除

• Grep 搜索 **Name:** <name> 没有匹配项 — 名称错误，或者参考文档使用了不同的 camelCase。请对照组件索引仔细检查（lightning-record-form → recordForm， lightning-record-view-form → recordViewForm， lightning-button-icon → buttonIcon）。
• 建议使用的组件没有你预期的属性 — 以真实 API 文档为准，不要依赖记忆。LBC 会不断演进；缓存的知识不可信。
• 开发者不接受候选范围 — 不要跳过第 4 步。仍然要检索开发者首选组件的文档，让他们了解实际的权衡。
• 开发者想要重新设置 LBC 内部样式 — 引导他们改用样式钩子（参阅 LBC 专家参考文档）。拒绝穿透 shadow DOM 才是正确做法。