experience-lwc-base-components-integrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Lightning Base Components

使用Lightning基础组件

Lightning Base Components (LBC) are the

lightning-*

web components shipped by Salesforce. This skill routes an agent through the right decision sequence so the final component choice is as specific as possible and backed by real API docs — not a hand-rolled reimplementation of something that already exists.

Lightning Base Components (LBC)是Salesforce提供的

lightning-*

Web组件。本技能会引导Agent完成正确的决策流程，最终选择的组件尽可能具体，且有真实API文档支持——而非重新实现已有的功能。

When to Use This Skill

何时使用本技能

User describes a UI need ("searchable dropdown", "record edit form", "modal with footer") and asks which
```
lightning-*
```
component fits.
User is about to build a primitive (button group, combobox, toast) and should be using LBC instead.
User asks you to review LWC markup for LBC-related issues — specifically overriding SLDS classes or restyling LBC internals.
User needs the authoritative props/events/slots for a specific
```
lightning-*
```
tag.

用户描述UI需求（「可搜索下拉框」、「记录编辑表单」、「带页脚的模态框」）并询问哪个
```
lightning-*
```
组件适用。
用户即将构建基础组件（按钮组、组合框、提示框），此时应使用LBC而非手动开发。
用户要求你审查LWC标记中与LBC相关的问题——特别是覆盖SLDS类或重新设置LBC内部样式的情况。
用户需要特定
```
lightning-*
```
标签的权威属性/事件/插槽信息。

Prerequisites

前提条件

Knowledge of which LBC namespace your org uses (
```
lightning
```
is the default public namespace; some platforms expose
```
lightning-community
```
or others — the user's meta files will clarify).
The skill ships authoritative API docs for every Lightning Base Component in references/lightning-components.md. Each component is a
```
# Component API Structure
```
block; grep for
```
**Name:** <camelCaseName>
```
(e.g.
```
**Name:** datatable
```
) to jump to its Properties / Methods / Events / Slots. Read this rather than relying on cached knowledge — LBC evolves and the reference is the source of truth.

了解你的组织使用的LBC命名空间（
```
lightning
```
是默认公共命名空间；部分平台会暴露
```
lightning-community
```
或其他命名空间——用户的元数据文件会明确说明）。
本技能附带了每个Lightning基础组件的权威API文档，位于references/lightning-components.md。每个组件对应一个
```
# Component API Structure
```
块；可以通过搜索
```
**Name:** <camelCaseName>
```
（例如
```
**Name:** datatable
```
）快速定位到其属性/方法/事件/插槽部分。请以此文档为准，而非依赖缓存知识——LBC一直在演进，该参考文档是唯一可信来源。

Workflow

工作流程

Step 1 — Read the entire component index first

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

Open lightning-component-index.md and scan all entries before making any selection. This is non-negotiable: LBC's value comes from picking the most specialized component, and skipping the scan leads to reinventing compound widgets out of primitives.

As you scan, compile a candidate list — every component whose description touches any aspect of the use case. Do not filter or rank yet.

打开lightning-component-index.md，在做出任何选择前先浏览所有条目。这是必须的：LBC的价值在于选择最专业的组件，跳过浏览步骤会导致用基础组件重新构建复合组件。

浏览时，整理一份候选列表——所有描述涉及用例任何方面的组件。暂不进行筛选或排序。

Step 2 — Narrow to the most specific fit per feature

步骤2 — 根据功能缩小到最贴合的特定组件

Once the scan is complete:

For each feature in the use case, select the most specific component that covers it. Prefer a specialized compound (
```
lightning-record-form
```
,
```
lightning-tabset
```
,
```
lightning-datatable
```
) over a generic primitive (
```
lightning-input
```
,
```
lightning-button
```
) when the specialized one covers the scenario end-to-end.
Avoid duplication: if
```
lightning-record-form
```
already renders fields for a record, do not pair it with
```
lightning-input-field
```
unless you're explicitly overriding behavior.

浏览完成后：

针对用例中的每个功能，选择最特定的组件来覆盖它。当专业复合组件（
```
lightning-record-form
```
、
```
lightning-tabset
```
、
```
lightning-datatable
```
）能端到端覆盖场景时，优先选择它而非通用基础组件（
```
lightning-input
```
、
```
lightning-button
```
）。
避免重复：如果
```
lightning-record-form
```
已经为记录渲染字段，除非明确要覆盖行为，否则不要将其与
```
lightning-input-field
```
搭配使用。

Step 3 — Share the shortlist and confirm

步骤3 — 分享候选列表并确认

Present the final shortlist to the developer with a one-line rationale per component. Wait for explicit confirmation before pulling full API docs. This prevents the agent from burning context on components the developer has already mentally ruled out.

向开发者展示最终候选列表，每个组件附带一行理由。在获取完整API文档前等待明确确认。这可以避免Agent在开发者已经排除的组件上浪费上下文。

Step 4 — Retrieve full API docs

步骤4 — 获取完整API文档

Once confirmed, use the bundled helper to pull the exact API blocks — this avoids ad-hoc grepping across a large reference:

bash

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

Convert

lightning-<foo>

tags to camelCase (no

lightning-

prefix):

```
lightning-datatable
```
→
```
datatable
```

lightning-record-edit-form

→

recordEditForm

```
lightning-button-icon
```
→
```
buttonIcon
```

Each returned block has the same shape: Basic Information (tag, namespace, type), Properties (name, type, default, description), Methods, Events, Slots, and (where applicable) usage notes. This skill is about picking the components; the bundled reference is about wiring them.

确认后，使用捆绑的工具提取准确的API块——这避免了在大型参考文档中临时搜索：

bash

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

将

lightning-<foo>

标签转换为驼峰式（去掉

lightning-

前缀）：

```
lightning-datatable
```
→
```
datatable
```

lightning-record-edit-form

→

recordEditForm

```
lightning-button-icon
```
→
```
buttonIcon
```

每个返回的块结构一致：基本信息（标签、命名空间、类型）、属性（名称、类型、默认值、描述）、方法、事件、插槽，以及（如有）使用说明。本技能负责选择组件，而捆绑的参考文档负责指导集成它们。

Step 5 — Produce integration guidance

步骤5 — 提供集成指导

Using the per-component reference, walk the developer through:

The exact
```
<lightning-...>
```
tag and required attributes.
Which events to bind (
```
onchange
```
,
```
oncommit
```
,
```
onsuccess
```
, …) and what the event payload contains.
Any slots to fill (headers, footers, custom content).
Known constraints from the component docs (e.g.
```
lightning-record-form
```
requires
```
object-api-name
```
and
```
record-id
```
for edit/view modes).

使用每个组件的参考文档，引导开发者完成以下内容：

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

Step 6 — Respect LBC styling rules

步骤6 — 遵守LBC样式规则

Do not override SLDS classes on LBC internals. See lbc-expert-guidance.md for specifics. Common issues:

Targeting
```
.slds-button
```
or
```
.slds-input
```
in the host component's CSS to restyle an LBC — LBC ships inside a shadow root, so these selectors either leak into sibling components or get stripped entirely. Use the component's documented styling hooks (
```
--sds-c-button-*
```
, etc.) instead.
Wrapping an LBC just to mutate its internal markup. You can't — the markup is hidden behind the shadow root. If the component doesn't expose the slot/prop you need, that's a platform-level gap, not a restyling job.

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

在宿主组件的CSS中定位
```
.slds-button
```
或
```
.slds-input
```
来重新设置LBC样式——LBC位于影子根（shadow root）内部，这些选择器要么会泄露到兄弟组件，要么会被完全剥离。请改用组件文档中提供的样式钩子（
```
--sds-c-button-*
```
等）。
包裹LBC只是为了修改其内部标记。这是不可能的——标记被隐藏在影子根之后。如果组件没有暴露你需要的插槽/属性，那是平台层面的缺口，而非样式修改任务。

Examples

示例

Example — "I need a multi-select combobox with typeahead"

示例 — "我需要一个带输入提示的多选组合框"

Scan the component index end-to-end.

Candidate list includes:

lightning-combobox

lightning-dual-listbox

lightning-record-picker

Shortlist:
```
lightning-dual-listbox
```
(the documented multi-select base component). Rule out
```
lightning-combobox
```
— its documented API is single-select; it has no
```
type="multi"
```
and no multi-select mode. Flag that
```
lightning-record-picker
```
only fits if the values are record IDs.
Developer confirms
```
lightning-dual-listbox
```
.

Run

scripts/extract-component-docs.sh dualListbox

Return the
```
options
```
,
```
value
```
,
```
onchange
```
payload, and required label props from the block's Properties / Events sections.

完整浏览组件索引。

候选列表包括：

lightning-combobox

、

lightning-dual-listbox

、

lightning-record-picker

。

候选短列表：
```
lightning-dual-listbox
```
（文档中明确的多选基础组件）。排除
```
lightning-combobox
```
——其文档API为单选；没有
```
type="multi"
```
属性，也没有多选模式。标记
```
lightning-record-picker
```
仅在值为记录ID时适用。
开发者确认选择
```
lightning-dual-listbox
```
。

运行

scripts/extract-component-docs.sh dualListbox

。

返回该块属性/事件部分中的
```
options
```
、
```
value
```
、
```
onchange
```
负载，以及必填的标签属性。

Example — "I'm going to write my own modal"

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

Scan finds

lightning-modal

lightning-modal-body

lightning-modal-footer

lightning-modal-header

Shortlist is the 4 modal components.
Confirm.

Run

scripts/extract-component-docs.sh modal modalHeader modalBody modalFooter

→ full modal API (how to extend

LightningModal

, the static

.open()

pattern, slotting the header/body/footer).

Steer the developer away from rolling their own dialog.

浏览发现

lightning-modal

、

lightning-modal-body

、

lightning-modal-footer

、

lightning-modal-header

。

候选短列表是这4个模态框组件。
确认。
运行
```
scripts/extract-component-docs.sh modal modalHeader modalBody modalFooter
```
→ 获取完整模态框API（如何扩展
```
LightningModal
```
、静态
```
.open()
```
模式、插槽页眉/正文/页脚的方法）。
引导开发者不要自行开发对话框。

Verification Checklist

验证清单

Troubleshooting

故障排除

Grep for
**Name:** <name>
returns no match — name is wrong, or the reference uses a different camelCase. Double-check against the component index (
```
lightning-record-form
```
→
```
recordForm
```
,
```
lightning-record-view-form
```
→
```
recordViewForm
```
,
```
lightning-button-icon
```
→
```
buttonIcon
```
).
Proposed component doesn't have the prop you expected — trust the real API doc over memory. LBC evolves; cached knowledge lies.
Developer resists the shortlist — don't skip Step 4. Still retrieve the docs for the developer's preferred choice so they see the actual trade-offs.
Developer wants to restyle LBC internals — redirect to styling hooks (see the LBC Expert reference). Refusing shadow DOM penetration is the correct answer.

搜索
**Name:** <name>
无匹配结果——名称错误，或参考文档使用了不同的驼峰式写法。请对照组件索引再次检查（
```
lightning-record-form
```
→
```
recordForm
```
、
```
lightning-record-view-form
```
→
```
recordViewForm
```
、
```
lightning-button-icon
```
→
```
buttonIcon
```
）。
推荐的组件没有你预期的属性——相信真实API文档而非记忆。LBC一直在演进；缓存知识可能过时。
开发者拒绝候选短列表——不要跳过步骤4。仍需获取开发者首选组件的文档，以便他们了解实际的权衡。
开发者想要重新设置LBC内部样式——引导他们使用样式钩子（参考LBC专家文档）。拒绝穿透影子DOM是正确的做法。