开始使用 Lightning Web Components | Salesforce LWC 入门指南

什么是 Lightning Web Components？

Lightning Web Components（LWC）是一个用于构建自定义用户界面、Web 和移动应用以及数字体验的现代框架，运行于 Salesforce 平台之上。Lightning Web Components 是使用标准 HTML 和 JavaScript 构建的自定义 HTML 元素。Salesforce 提供了基于 Lightning Design System 构建的 Lightning 基础组件，作为构建自定义体验的预制模块。使用基础组件可以为你的用户提供一致的外观和体验，同时简化你的开发工作。

可用版本：适用于 Lightning Experience，支持 Enterprise、Performance、Unlimited 和 Developer 版本。

编写标准 JavaScript 和 HTML

Lightning Web Components 使用核心 Web Components 标准，仅提供在 Salesforce 支持的浏览器中高性能运行所必需的功能。因为 LWC 构建在浏览器原生运行的代码之上，所以它非常轻量，并提供卓越的性能。你所编写的大部分代码都是标准的 JavaScript 和 HTML。

Salesforce 致力于开发开放的 Web 标准，是万维网联盟（W3C）的成员。Salesforce 开发人员也是 Ecma 国际技术委员会 39（TC39）的贡献成员，该委员会负责推动 JavaScript 语言的发展。此外，Lightning Web Components 还是开源的。

关键特性

构建在浏览器原生运行的代码之上 —— 轻量且提供卓越性能
大部分代码为标准 JavaScript 和 HTML —— 无需学习专有语法
使用核心 Web Components 标准 —— 符合 W3C 规范
Salesforce 是 W3C 成员 —— 积极参与 Web 标准制定
LWC 是开源的 —— 可在 github.com/salesforce/lwc 和 lwc.dev 获取

向后兼容性

你可以使用两种编程模型构建 Lightning 组件：Lightning Web Components（推荐）和原始的 Aura Components。Lightning Web Components 和 Aura 组件可以在同一页面上共存并互操作。对于管理员和最终用户来说，它们都是 Lightning 组件。

Lightning 基础组件既提供 Lightning Web Components 版本，也提供 Aura Components 版本。组件参考中包含了两种版本的文档、规范和示例。

最佳实践：当你在 LWC 和 Aura 之间有选择时，始终选择 LWC。LWC 性能更好，更易于开发。只有在需要使用 LWC 尚未支持的功能时，才将 LWC 包装在 Aura 组件中。需要注意，LWC 不能包含 Aura 组件，但 Aura 可以包含 LWC。

Lightning 组件库

Lightning 组件库包含了组件参考信息以及 Lightning Web Security 和 Lightning Locker 的安全工具。你可以在两个地方找到组件库：公开站点（无需登录）和连接到你的 Salesforce 组织的认证站点。

公开组件库

无需登录 Salesforce 即可访问：developer.salesforce.com/docs/component-library
包含 Component Reference、LWC Developer Guide、LWS Console、LWS Distortion Viewer、Locker Console 和 Locker API Viewer 标签页

组织专属组件库（认证站点）

登录后访问：https://<myDomainName>.lightning.force.com/docs/component-library
额外功能：查看组织独有的 Lightning 组件、查看托管包中安装的组件、按组织拥有或包安装进行筛选

组件参考（Component Reference）

新版 Lightning 组件参考：developer.salesforce.com/docs/platform/lightning-component-reference
旧版组件库：不再更新，将于 Spring '26 停止发布

旧版组件参考的已知限制

非 lightning 命名空间差异：公开站点中非 lightning 命名空间的组件参考可能包含过时内容，建议在认证站点中验证
不支持自定义 LWC 文档：组件参考不显示你组织中的自定义 Lightning Web Components 文档
规格面板缺少内容：部分模块（如 lightning/empApi、lightning/flowSupport 等）在规格页面上不显示描述和方法
不支持版本和本地化：组件参考没有版本或语言选择器，仅显示当前版本，且仅提供英文内容

Lightning Web Security 和 Lightning Locker

Lightning Web Security（LWS）—— 新一代安全架构

LWS 是 Spring '22 引入的新一代安全架构，基于最新的 Web 标准，通过在虚拟 JavaScript 沙箱中运行组件来防止不安全代码行为。使用 LWS Console 和 LWS Distortion Viewer 来开发与 LWS 兼容的安全 JavaScript 代码。

Lightning Locker —— 传统安全机制

Lightning Locker 是传统的安全架构，通过 API 过滤提供组件隔离和安全保护，允许来自多个来源的代码使用安全、标准的 API 进行执行和交互。使用 Locker Console 和 Locker API Viewer 来开发与 Locker 兼容的代码。

LWS 与 Locker 的关键区别

LWS：现代虚拟沙箱方式，基于最新 Web 标准
Lightning Locker：传统 API 过滤方式
两者共同点：都强制执行 JavaScript 严格模式（strict mode）

平台安全限制

在 Salesforce 平台上，this.template.host 始终返回 null（与 OSS 不同，OSS 中返回组件宿主元素）
通过 template 获取的组件的 shadowRoot 也始终返回 null

开始编码：创建你的第一个组件

编写你的第一个 Lightning Web Component 的最快方式是使用在线实时编码环境。推荐使用 StackBlitz 在线 IDE 快速入门。你也可以使用 Salesforce DX 工具将 LWC 代码推送到你的组织。

注意：StackBlitz 是第三方产品，受其自身条款和条件的约束。Salesforce 不对 StackBlitz 上提供的内容、服务或付费选项负责。

在 StackBlitz 上创建你的第一个组件

访问 playground.lwc.dev（无需注册即可使用，使用 GitHub 账户登录可保存更改）
将鼠标悬停在 x 目录上，点击 Add Folder 图标，输入组件名称，例如 myComponent
在 myComponent 目录下创建 HTML 文件 myComponent.html（文件名必须与目录名一致）：
```
<template>
  <p>Hello {name}!</p>
</template>
```

创建 JavaScript 文件 myComponent.js（同样需要匹配目录名）：

import { LightningElement } from "lwc";

export default class MyComponent extends LightningElement {
  name = "LWC";
}

在 app.html 中的 <x-counter></x-counter> 后面添加 <x-my-component></x-my-component>
保存更改并刷新预览区域，将显示 "Hello LWC!"

组件结构要点

每个组件 = 一个文件夹 + .html 文件 + .js 文件
命名空间 + 组件名 → <x-my-component>（HTML 中使用 kebab-case，JS 中使用 PascalCase）
必须继承 LightningElement 类
{表达式} 用于数据绑定

开发环境与后续步骤

StackBlitz 使用指南

自动更新：StackBlitz 自动更新到最新的 OSS LWC 版本，该版本通常领先于你的 Salesforce 组织版本。可在 package.json → devDependencies → lwc 值查看版本（如 3.6.0）
无法访问 Salesforce 数据：不支持 @salesforce/* 导入，不支持 Lightning Data Service wire adapters
不包含 SLDS 和基础组件：如需基础组件示例，请使用组件参考
适合学习 LWC 框架基础和复现框架问题

StackBlitz 之后的后续步骤

在你的本地机器上搭建开发环境（Salesforce DX 工具）
将 LWC 代码推送到你的 Salesforce 组织
学习模板中的数据绑定
探索 Trailhead 和示例代码
开始使用 Salesforce 数据构建应用

Lightning Web Components 开源

Lightning Web Components 是开源的，让你可以探索源代码、根据需求自定义行为，并在任何平台上（不仅仅是 Salesforce）构建企业级 Web Components。

开源资源

GitHub 仓库：github.com/salesforce/lwc
开源开发者站点：lwc.dev

使用 LWC 开源的优势

使用同一框架构建 Salesforce 和非 Salesforce 应用
在应用之间共享代码
使用基于 Web 标准的前沿框架
采用最新的模式和最佳实践

LWC OSS 与 LWC on Platform 对比

特性	LWC OSS	LWC on Platform
部署方式	下载、配置、部署到任意主机	Salesforce 管理配置、部署和升级
发布周期	每周发布	每年 3 次发布
版本领先性	领先平台 3-6 个月	落后 OSS 3-6 个月
引擎	完全相同	完全相同
区别	编译器和运行时配置不同

编译时差异（Salesforce 平台）

实验性 LWC API（如 lwc:dynamic、buildCustomElementConstructor、createElement 等）被限制，会抛出 linting 错误
强制执行 @salesforce/eslint-config-lwc/base 中的所有规则
禁止动态 import（import('c/foo')）
禁止从 LWC 访问 Aura（如 $A）
@salesforce/* 导入会针对组织元数据进行验证

运行时差异（Salesforce 平台）

组件以 @lwc/synthetic-shadow 模式运行
SVG <use> 元素的 link/href 属性被 Locker 清理以防止恶意脚本注入
this.template.host 始终返回 null
通过 template 获取的子组件 shadowRoot 始终返回 null

LWC API 版本管理

可用 API 版本：LWC API v59.0 及更高版本

从 Winter '24 开始，LWC 支持自定义组件的版本管理。从 Spring '25 开始，版本管理对于所有自定义组件变为强制要求。当组件指定了版本时，该组件便依赖于该特定版本的 Salesforce 发布。组件的每个 HTML、CSS 和 JS 文件都对应一个 API 版本，API 版本告诉 LWC 框架按照该 Salesforce 发布对应的行为来运行，从而确保你的组件拥有稳定的执行环境。

关键规则

之前保存的未版本化组件可以继续运行
下次修改组件时，必须同时设置 API 版本
尝试保存未版本化的组件将导致错误

版本管理的优势

保证向后兼容性 —— 组件行为不会因平台升级而改变
稳定执行环境 —— 组件行为锁定到特定 Salesforce 发布版本
安全升级 —— 可以安全地升级平台，而不会破坏现有组件
灵活迁移 —— 每个组件可以使用不同的 API 版本，支持渐进式升级

支持的浏览器和 JavaScript

支持的浏览器

Lightning Web Components 支持与 Lightning Experience 相同的浏览器 —— 最新稳定版本的 Edge、Chrome、Firefox 和 Safari。Salesforce 已于 2023 年 1 月 1 日停止支持 Internet Explorer 11。Winter '24 之后，你将无法再使用 IE11 和其他旧版浏览器访问 Lightning Experience。

关于浏览器扩展

Salesforce 不提供对第三方浏览器扩展的支持，使用风险自负
操纵 DOM 的浏览器扩展（如插入或删除 DOM 元素）可能会干扰 Lightning Experience 的稳定性
建议通过 AppExchange 或组件参考寻找受支持的替代方案
如需操作 DOM，考虑使用 lightning/platformResourceLoader 来引入 JavaScript 库

支持的 JavaScript

使用最新版本的 JavaScript
可以使用浏览器支持且 Lightning Locker/LWS 允许的任何 JavaScript 功能
标准 JavaScript 文档参见 MDN（Mozilla Developer Network）
LWC 特定功能（如 wire adapters）在本开发者指南中记录
LWS 和 Lightning Locker 都强制执行 JavaScript 严格模式（strict mode）

支持的 Salesforce 目标、工具和 API

支持的目标平台

在开发组件时，请在组件的配置文件中指定其目标平台：

Lightning Experience 和 Salesforce 移动应用
Lightning App Builder 和 Experience Builder
Lightning Web Runtime 和独立应用
Lightning 控制台应用和实用工具栏
Flows（流程）、快速操作、自定义标签页
Gmail/Outlook 集成、嵌入式服务聊天
Lightning Out（Beta）、OmniScripts
第一代/第二代托管包、非托管包、变更集
URL 可寻址组件

不支持的场景（需要用 Aura 包装）

Chatter 扩展、全局操作
列表视图操作、相关列表视图操作
标准操作覆盖

支持的 Salesforce API

CRM Analytics API —— 数据集和仪表板
Einstein Discovery API —— 检索 Einstein Discovery 故事
Einstein 生成式 AI Models API —— 连接 LLM 大语言模型
EMP API —— 订阅流式频道事件
Lightning Console API —— 工作区标签页和实用工具栏
Metadata API —— 部署和检索 LWC 包
Mobile SDK —— 在混合应用中使用 LWC
Service Cloud Voice Toolkit API
Service Knowledge API —— 知识文章
Tooling API —— LWC 包管理
UI API —— 记录、列表视图等（通过 wire adapters）

不支持的 API（需要用 Aura 包装）

Lightning Console Navigation Item API
Conversation Toolkit API
Omni Toolkit API

如何选择：Lightning Web Components 还是 Aura？

Lightning Web Components 比 Aura 组件性能更好，更易于开发。然而，在开发 LWC 时，你有时也需要使用 Aura，因为 LWC 目前还不支持 Aura 的所有功能。

核心原则：始终选择 Lightning Web Components，除非你需要一个不受支持的功能。

要使用不受支持的体验或功能，开发一个 LWC 并将其包装在一个仅访问该体验、功能或接口的 Aura 组件中。要使用一个尚不可用作 LWC 的基础组件，你可能需要完全（或几乎完全）使用 Aura 进行开发。

感谢阅读本指南。如需继续学习，请参阅下一章：搭建你的开发环境。

开始使用 Lightning Web Components — Salesforce LWC 入门指南