Lightning 基础组件 | Salesforce LWC | Salesforce CRM 中文站

使用 Lightning 基础组件

Lightning 基础组件是构成 Lightning Experience、Salesforce 移动应用和 Experience Builder 站点的构建块。它们整合了 SLDS 标记和样式，提供最佳性能和内置无障碍支持。基础组件包括可视化组件和API 模块，可大幅加速应用开发。LWC 和 Aura 都可使用——但推荐优先使用 LWC。

基础组件 —— 概述与分类

基础组件基于 SLDS 设计指南构建，但并非实现每个指南中的所有功能。使用基础组件而非自己从 SLDS 蓝图构建——基础组件自动获得最新 SLDS 设计更新。基础组件当前不进行版本管理——无论自定义组件的 API 版本如何，始终使用最新行为。

十大类别：Actions and Menus（按钮/菜单）、Containers（手风琴/卡片/标签页/模态框/布局）、Images and Visuals（头像/徽章/图标/地图）、Input（输入/选择器/滑块/富文本）、Forms（记录表单/编辑/查看）、Navigation（面包屑/垂直导航）、Notifications（Toast/Alert/Confirm/Prompt）、Output（格式化显示——日期/数字/邮件/电话等）、Progress（进度条/进度环/旋转器）、Tables and Trees（数据表/树/树形网格）。

还有 Utility Modules——无对应的 SLDS 设计，提供额外功能：lightning/navigation、lightning/messageService、lightning/platformResourceLoader、lightning/refresh 等。

基础组件 —— 最低 API 版本与应用容器

API 版本

基础组件不进行版本管理——更改自定义组件的 API 版本不影响基础组件的行为。API 版本 ≤ 58.0 默认使用 58.0。大多数基础组件从 Spring '19（API 45.0）起可用。建议始终更新到最新版本以获取最新功能和错误修复。

应用容器

基础组件设计为平台无关——可在 Lightning Experience、Experience Builder、Salesforce 移动应用和 LWC OSS 中使用。但某些组件依赖 Salesforce 平台：记录表单组件（需要 Salesforce 记录数据）、LDS API 模块（lightning/uiRecordApi、lightning/uiGraphQLApi）、Salesforce API 模块（lightning/platformUtilityBarApi 等）。查看 Component Reference 的 Targets 面板了解每个组件支持的容器。LWR 站点上只有子集支持 SSR。

基础组件 —— 命名、命名空间与 API 模块

命名格式：模板中使用连字符分隔名（lightning-button-group）；JS 导入中使用斜杠分隔名（lightning/toast）。调用 Salesforce API 的基础组件受相应 API 生命周期政策约束。

命名空间：基础组件主要在 lightning 命名空间。其他命名空间包括：lightningsnapin（嵌入式服务聊天）、experience（Experience Builder 站点）、wave（CRM Analytics）。

API 模块：部分组件必须先导入 JS 才能使用：UI 基础组件（lightning/toast、lightning/prompt——传递配置给模块方法）、服务/工具方法（lightning/navigation、lightning/messageService）、LDS 数据访问（lightning/uiRecordApi 等）。

注意：只使用公开属性。标记为 "Reserved for internal use" 的属性可能在将来版本中变更。使用 lwc:ref 而非 id 定位基础组件——this.refs 比 querySelector 更高效。

使用模式 —— 在标记中使用基础组件

基础组件在模板中像普通 HTML 一样使用。组件封装复杂功能同时让你通过属性自定义外观：

<lightning-button variant="brand" label="Submit" title="Submit this form"
    onclick={handleClick} class="slds-m-left_x-small"></lightning-button>

<!-- 渲染为：
   -->

variant 和 label 是组件特有属性；title、class、onclick 是 HTML 全局属性——作为公共属性暴露，值被传递到底层 HTML 元素。基础组件内部将 variant 值转换为对应 CSS 类。

可以查看 DOM 来理解行为，但绝不要依赖内部标记或 CSS 类——它们可能在未来版本中变化。

使用模式 —— 模块导入与扩展

模块导入

通知组件需要先导入模块：lightning/alert、lightning/confirm、lightning/prompt——调用 .open() 方法创建实例。与 window.alert() 不同，它们不阻塞执行且返回 Promise——用 async/await 或 .then() 处理模态框关闭后的代码。

Toast 组件：lightning/platformShowToastEvent（事件驱动，不支持 LWR 站点）和 lightning/toast（推荐——函数调用方式，支持 LWR）。

类扩展

除另有说明外，只能扩展 LightningElement。仅少数基础组件允许扩展：lightning/modal——创建自定义模态框组件，提供覆盖层和开关机制，用 lightning-modal-header/body/footer 构建 UI；lightning/datatable——创建自定义数据类型。

全局属性 —— 支持与类传递

基础组件可使用 HTML 全局属性，但部分无效或不适用。例如 lightning-button 支持 name、type、value，但不支持 autofocus——未传递给内部 <button>。

关键陷阱：部分组件将全局属性重新命名为不同属性名。例如 lightning-badge 的 title 属性只应用到外层包装——要获得图标悬停文本需用 icon-alternative-text（内部转为 title）。始终查阅规格文档确认支持的属性。

传递类：class 属性应用到基础组件的外层包装元素，而非内部元素。内部元素保持其 SLDS 类不变，你的自定义类被追加到外层。

处理基础组件上的事件

事件处理器格式为 on{eventname}（如 onclick、onchange）。基础组件也可派发自定义事件（如 lightning-datatable 的 resize 和 rowselection）。

<lightning-input type="text" label="Enter some text"
    onchange={handleChange}></lightning-input>
<p>{val}</p>

handleChange(event) { this.val = event.target.value; }

自定义事件 + 传递数据：子组件用 new CustomEvent("childbuttonclick", { detail: { label: this.buttonLabel } }) 派发，父组件通过 event.detail.label 获取。事件传播指南：避免不必要的 composed 事件；如需 composed，在目标组件停止传播；减少不必要的传播和意外行为。

注意：未明确记录的全局事件可能无效、导致回归或在组件内部变更后停止触发。

基础组件组合 —— 组合结构

组合结构通过声明式嵌套实现——父组件包含子组件的插槽：

<lightning-breadcrumbs>
  <lightning-breadcrumb label="Parent Account" href="path/1"></lightning-breadcrumb>
  <lightning-breadcrumb label="Case" href="path/2"></lightning-breadcrumb>
</lightning-breadcrumbs>

也可用 for:each 动态生成子组件列表——如遍历数据对象生成菜单项。常见父子组合：accordion/accordion-section、breadcrumbs/breadcrumb、button-group/button、button-menu/menu-item、layout/layout-item、tabset/tab、record-edit-form/input-field 等。

性能建议：大量组合组件时考虑将逻辑从子组件移回父组件——减少自定义组件的渲染数量。避免或合并不必要的 DOM 元素和事件处理器。对频繁重用的组件，避免深拷贝大对象、避免批量处理记录集合、避免强制重渲染。

基础组件组合 —— 扁平结构

部分基础组件内部渲染子组件——对外呈现更扁平的表面：

<lightning-select label="Quantity" value={value}
    options={options} onchange={handleChange}></lightning-select>

get options() { return [
  { label: "choose one...", value: "" },
  { label: "one", value: "1" }, { label: "two", value: "2" }
]; }

扁平结构用属性（如 options）传递配置信息，组件内部负责渲染 <select> 和 <option>。使用扁平结构的基础组件包括：checkbox-group、combobox、dual-listbox、datatable、map、pill-container、radio-group、select、tree。

选择指南：组合结构适合将代码/逻辑分解为更小单元；扁平结构适合渲染大量元素（每次避免自定义组件的实例化开销，渲染原生 HTML 内联提升性能）。

传递标记到基础组件插槽

大多数情况下推荐使用插槽而非属性传递配置。

默认插槽

未命名插槽接受任何标记。如 lightning-accordion 内部用 <slot></slot> 接受 lightning-accordion-section：

<lightning-accordion>
  <lightning-accordion-section name="A" label="Section A">...</>
</lightning-accordion>

命名插槽

lightning-card 包含一个默认插槽 + 三个命名插槽（title/actions/footer）：

<lightning-card title="Example" icon-name="standard:account">
  <p>Hello, {greeting}!</p>  <!-- 默认插槽 -->
  <div slot="footer">Content for footer</div>  <!-- 命名插槽 -->
</lightning-card>

使用插槽得到直观、易理解、可维护的代码。

传递配置和数据 —— 属性模式

部分基础组件需要用属性传递配置而非插槽。如果 lightning-button-group 用属性模式，会导致代码复杂难读——这就是为什么它使用组合结构。属性模式适合：

需要精细控制组件内元素渲染
更容易对元数据进行验证检查
渲染原生 HTML 内联以获得性能提升

性能示例：lightning-select 内部用 <select> 元素 + for:each 迭代 options 数组渲染 <option> 元素——全部是原生 HTML 而非自定义组件实例，渲染效率更高。

基础组件无障碍

基础组件提供内置无障碍支持——遵循 W3C 标准和最佳实践：

ARIA 编写支持：遵循 W3C ARIA Authoring Practices Guide。例如 lightning-accordion 在展开/折叠时自动切换 aria-hidden；lightning-input 验证错误时自动追加 aria-describedby；lightning-breadcrumbs 使用 aria-label="Breadcrumbs" + role="navigation" 提供语义
颜色使用：符合 WCAG 2.1 AA 对比度标准。通过 variant 属性控制颜色（如 success=绿色/error=红色），也可用 SLDS 样式钩子统一自定义
表单和输入：遵循 WCAG 可预测输入和输入辅助指南——标签关联（<label>）、控件分组（<fieldset>/<legend>）、表单指令引导、输入验证
图像和视觉：提供文本替代属性（如 lightning-avatar 的 alternative-text 转为 alt 和 title；lightning-icon 使用 slds-assistive-text 隐藏描述）

感谢阅读本指南。如需继续学习，请参阅下一章：使用事件通信。

使用 Lightning 基础组件 — LWC Base Components 完全指南