创建 Lightning Web Components

Lightning Web Component 是一个可重用的自定义 HTML 元素，拥有自己的 API。一个渲染 UI 的 LWC 必须包含 HTML 文件、JavaScript 文件和配置文件。API 模块组件（库）不需要 HTML 文件。本章将全面介绍组件的创建过程。

组件文件夹与文件结构

每个组件都是一个文件夹，直接位于 force-app/main/default/lwc/ 下。文件夹及其核心文件必须使用相同的名称（包括大小写和下划线）。

标准项目结构

force-app/main/default/lwc/
  myComponent/
    ├── myComponent.html         (UI 必需)
    ├── myComponent.js           (必需)
    ├── myComponent.js-meta.xml  (必需)
    ├── myComponent.css          (可选)
    ├── myComponent.svg          (可选)
    ├── utils.js                 (可选)
    └── __tests__/
        └── myComponent.test.js  (可选)

文件要求一览

文件	必需	最大大小	说明
HTML	仅 UI 组件	128 KB	根标签为 `<template>`，声明式编写组件 UI
JavaScript	是	1 MB	ES6 模块，UI 组件继承 LightningElement，API 模块导出函数
配置文件	是	-	.js-meta.xml 格式，定义 apiVersion、targets、设计配置
CSS	可选	128 KB	标准 CSS 语法，自动应用于组件
SVG	可选	-	在 App Builder 和 Experience Builder 中的自定义图标
工具 JS	可选	-	额外的 JavaScript 文件，用于结构化代码
测试	可选	-	Jest 测试文件，放在 `__tests__` 文件夹中

命名规则

必须以小写字母开头
只能包含字母、数字或下划线
在命名空间中必须唯一
不能包含空格
不能以下划线结尾
不能包含连续两个下划线
不能包含连字符（短横线）

命名转换规则：CamelCase 文件夹名自动映射为 kebab-case 标记名。myComponent → <c-my-component>。下划线不映射（my_component → <c-my_component> 合法但不推荐）。组件不能嵌套在其他组件文件夹中。

组件 JavaScript 文件

每个组件必须有一个 JavaScript 文件。LWC 中的 JavaScript 文件是 ES6 模块，默认情况下模块中声明的所有内容都是局部作用域的。

UI 组件

每个 UI 组件至少需要以下代码：

import { LightningElement } from "lwc";
export default class MyComponent extends LightningElement {
  // 你的代码：字段、@api 属性、事件处理器
}

LightningElement 是标准 HTML 元素的自定义包装器
类必须是默认导出（default export），UI 组件不支持导出其他变量或函数
类名约定为 PascalCase：myComponent.js → class MyComponent
不能通过扩展任何其他 Salesforce 基础组件类来创建 LWC

API 模块组件（库/服务组件）

不需要 HTML 文件。用于在组件之间共享代码：

// myUtils.js — 导出函数和变量
export function doSomething() { }
export const MY_CONST = 42;

// 其他组件导入：
import { doSomething } from 'c/myUtils';

允许的 LWC 导入

只能从 lwc 模块中使用以下命名导入：

LightningElement —— 基础类
api —— @api 装饰器，用于公开属性
track —— @track 装饰器，用于响应式字段
wire —— @wire 装饰器，用于数据服务

// 有效导入：
import { LightningElement, api, wire } from "lwc";

// 无效导入（编译错误）：
import lwc from "lwc";          // 不支持默认导入
import * as lwc from "lwc";     // 不支持命名空间导入
import "lwc";                   // 不支持副作用导入
export {} from "lwc";           // 不支持重新导出

组件配置与 CSS 文件

配置文件（.js-meta.xml）—— 必需

配置文件定义了组件的元数据值，包括支持的 targets 和设计配置：

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>false</isExposed>
</LightningComponentBundle>

关键元素

apiVersion —— LWC API 版本（45.0+）
isExposed —— 是否暴露给 App Builder/Experience Builder
targets —— 组件可用于哪些目标（如 lightning__AppPage、lightning__RecordPage）
targetConfigs —— 在 Builder 中可配置的设计时属性

注意：如果缺少配置文件，推送时会报错：Cannot find Lightning Component Bundle <component_name>。

CSS 文件 —— 可选，自动应用

使用标准 CSS 语法（无需预处理器）
创建与组件同名的样式表（如 myComponent.css），自动应用
最大文件大小：128 KB
可通过创建仅含 CSS 文件和配置文件的模块来共享样式

SVG 图标 —— 可选

命名为 componentName.svg
在 App Builder 和 Experience Builder 中用作自定义图标
每个组件文件夹只能有一个 SVG

其他可选文件

额外 JS 文件：如 utils.js、helpers.js，必须是 ES6 模块，名称在文件夹内唯一
Jest 测试：放在 __tests__/ 文件夹中，推荐命名 *.test.js

组件命名空间

每个组件都属于一个命名空间（namespace），命名空间将相关组件分组并防止来自不同命名空间的组件发生命名冲突。默认命名空间是 c。

在 HTML 模板中使用命名空间

<template>
  <!-- c 命名空间（你自己的组件） -->
  <c-contact-tile contact={contact}></c-contact-tile>

  <!-- lightning 命名空间（基础组件） -->
  <lightning-card title="My Card">
  </lightning-card>
</template>

在 JavaScript 中导入 API 模块

import { MyNamedExport } from 'c/commonUtils';
import MyDefaultExport from 'c/commonUtils';

格式为 namespace/moduleName，用正斜杠 / 分隔。

使用 LWS 进行跨命名空间访问

安全架构	可访问的命名空间	说明
LWS（Lightning Web Security）	任何命名空间	通过虚拟代码隔离允许跨命名空间交互，同时防止跨命名空间数据访问
Lightning Locker（传统）	仅 c 和 lightning	无法访问其他命名空间（如安装的托管包）的组件

命名空间注意事项

始终使用 c 命名空间前缀引用你自己的组件
如果计划在 AppExchange 上发布托管包，需要唯一的命名空间前缀
同一命名空间中的 LWC 和 Aura 组件不能同名

LWC API 版本管理

可用 API 版本：LWC API v59.0 及更高版本。Spring '25（API v63.0）起强制要求所有自定义组件进行版本管理。

为什么需要版本管理？

隔离变更：当 Salesforce 发布新功能、错误修复和性能改进时，版本管理确保你的组件不受意外影响
稳定执行环境：API 版本告诉 LWC 框架按照该版本对应的 Salesforce 发布行为运行
安全废弃：帮助 Salesforce 在必要时安全地废弃旧功能

版本管理如何工作

每个组件在 .js-meta.xml 中设置一个 apiVersion
所有文件（HTML、CSS、JS）使用相同的 API 版本
不同版本的组件可以在同一页面共存
子组件可以使用与父组件不同的版本

有效的 API 版本范围

最早有效版本：45.0（Summer '23）
最早实用版本：58.0（所有 ≤58.0 对应 Summer '23 行为）
首次版本管理支持：59.0（Winter '24）
最新版本：当前 Salesforce 发布
不能使用未来版本 —— 保存时会导致错误

未版本化组件的过渡

之前未设置 API 版本的组件仍可继续运行
下次修改时必须设置 API 版本
从 Salesforce 检索时自动添加与当前行为匹配的 apiVersion 标签

重要：无论 apiVersion 如何设置，自定义组件始终使用最新版本的 Lightning Data Service 和 Lightning 基础组件。

升级 API 版本与版本管理注意事项

升级组件 API 版本

发布组件 → 修复 SFDX 控制台中的警告
在 Sandbox 中运行 → 修复浏览器 DevTools 中的警告（一个版本中的警告可能在下一版本中变成错误，建议逐版本升级）
增加 .js-meta.xml 中的 apiVersion
重新发布 → 验证不再有警告

<!-- 从 58.0 升级到 59.0 -->
<apiVersion>59.0</apiVersion>

最佳实践：每次修改组件时都更新 apiVersion，以利用最新功能和错误修复。

各版本的重大变更

v63.0（Spring '25） —— 版本管理变为强制要求
v62.0（Winter '25）
v61.0（Summer '24）
v60.0（Spring '24）
v59.0（Winter '24） —— 首次引入版本管理

版本管理注意事项

同一页面或同一托管包中的组件可以使用不同的 API 版本
apiVersion 低于 58.0 → LWC 使用 58.0
设置未来版本 → 保存错误
LWC API 版本管理不适用于 Aura 组件或 LWR
仅在 Lightning Experience 或 Experience Builder 中通过 .js-meta.xml 文件使用
LWR 中：组件使用最新 API 版本（无版本化行为）

感谢阅读本指南。如需继续学习，请参阅下一章：HTML 模板。

创建 Lightning Web Components — Salesforce LWC 组件结构完全指南