DEX475

课程介绍

同学们，我们一起来看一下这张幻灯片。它告诉我们，Lightning Web 组件本质上就是一个可以重复使用的自定义 HTML 元素，而且它有自己的 API，也就是说它定义好了可以跟外部交互的方法和属性。 那一个完整的 UI 组件必须包含三个文件：一个 HTML 文件，负责定义组件的结构和展示；一个 JavaScript 文件，负责编写组件的逻辑；还有一个配置文件，用来声明这个组件的元数据，比如它要用到哪些 Salesforce 功能。 不过，如果你的组件是一个 API 模块，也就是一个纯功能库，不包含任何界面，那就可以不需要 HTML 文件，只要 JavaScript 和配置文件就够了。 这一章呢，会完整地带大家走一遍组件创建的过程，包括文件的组织方式、命名的规范、文件夹怎么放，还有 API 版本控制该怎么做。这样大家就能从零开始，一步步搭出自己的 Lightning Web 组件了。

课程章节

本课程共有 6 个章节

• 1

  Component Folder & File Structure

  第 27 页

  好，我们接着看这一页幻灯片，讲的是Lightning Web组件的结构和命名规范，这个基础一定要打牢。 首先，每个Lightning Web组件，在代码里就是一个文件夹，放在`force-app/main/default/lwc/`这个路径下面。注意，文件夹的名字和它里面最核心的几个文件，必须保持相同的名字。比如你给文件夹取名`myComponent`，那里面就得有`myComponent.html`、`myComponent.js`这些文件。 那一个最基本的UI组件需要哪些文件呢？最少得有三个： 一个HTML文件，这个文件大小不能超过128KB，而且它最外层的根标签必须是`<template>`。 一个JavaScript文件，大小上限是1MB，里面的类要继承自`LightningElement`。 还有一个配置文件，名字后面加个`.js-meta.xml`，这个文件告诉Salesforce这个组件该怎么暴露出去使用。 除了这三个必需的，你还可以加可选的CSS文件，大小也是128KB以内，用来装饰组件样式。如果你想要自定义图标，可以在文件夹里放一个JPEG图片。这些都是可选的，按需来就行。 接下来是命名规则，很重要，因为不遵守的话代码会报错。 组件的名字必须以小写字母开头（其实幻灯片上写的“收件箱规则”可能是笔误，应该是“命名规则”），只能用字母、数字和下划线，不能有连字符，并且在整个命名空间里要是唯一的。 有意思的是，文件夹的名字我们用的是驼峰写法，比如`myComponent`，但在HTML里引用它的时候，要用短横线分隔的kebab-case写法，并且加上命名空间前缀`c-`，就成了`<c-my-component>`。这个映射关系别搞混了。 最后一点，组件文件夹不能套娃，就是你不能在一个组件文件夹里再嵌套另一个组件文件夹。每个组件都是平级地放在`lwc`目录下的，这点一定要记住。 所以总结一下，每个LWC就是一个规范的文件夹，里面有固定的文件结构，名字统一，写法对应好，这样Salesforce平台才能正确识别和渲染你的组件。接下来我们看看具体的代码示例，会更清楚。好，这一页讲完了，有问题随时打断我。

  ▶ 播放视频 查看详情
• 2

  Component JavaScript File

  第 28 页

  同学们，我们来看一下这个知识点：每个 Lightning Web Component 都必须有一个 JavaScript 文件，用的是 ES6 的模块格式。 首先，如果你创建的是一个能在页面上显示的 UI 组件，那就必须从 `lwc` 这个核心库里导入 `LightningElement`，然后导出一个默认的类，并且这个类要继承自 `LightningElement`。要注意哦，这个导出一定是默认导出，你不能在这个文件里再额外导出其他变量或函数。因为这个文件的任务很单纯，就是定义一个组件类。 那如果我们需要写一些不渲染界面的纯逻辑库，也就是 API 模块组件、或者叫服务组件，这种情况下我们就可以导出多个函数和变量，给其他组件导入使用。这种组件就不需要继承 `LightningElement` 了。 还有一个很重要的限制：从 `lwc` 模块里导入东西时，只允许使用四种具名导入，分别是 `LightningElement`、`api`、`track` 和 `wire`。你不能用默认导入的方式，比如 `import lwc from 'lwc'`；也不可以用命名空间导入全量对象，比如 `import * as lwc from 'lwc'`；更不能从 `lwc` 重新导出什么内容。这些操作都是无效的。 最后，类的命名要遵循 PascalCase 的约定，也就是每个单词首字母大写的驼峰形式，而且类名必须跟你这个组件的文件名相匹配。比如组件文件夹叫 `myComponent`，那你的类名就应该是 `MyComponent`，这样框架才能正确识别。 简单总结一下：UI 组件一定要有 JS 文件，从 `lwc` 导入 `LightningElement` 并默认导出一个继承它的类，不能导出别的；只能导入那四种特定符号；类名和文件名要保持一致。这样我们的组件就能稳稳地跑起来了。

  ▶ 播放视频 查看详情
• 3

  Component Configuration & CSS Files

  第 29 页

  今天我们来讲讲Lightning Web Components里一个非常重要但又容易被忽略的部分——组件的文件结构，尤其是那个关键的配置文件。 首先，每个组件都必须有一个叫 .js-meta.html 的文件，也就是我们常说的配置文件。这个文件是必需的，绝对不能少。它定义了什么呢？主要是 API 版本、这个组件是否向构建者公开、它支持哪些目标，以及可以设置哪些设计属性。如果少了这个文件，你马上就会看到一个错误提示：“找不到Lightning组件捆绑包”。所以同学们，创建组件的时候，一定要先检查有没有这个 meta 文件，不然整个组件都没法用。 接下来，我们说说 CSS。CSS 是可选的，不是必须的。如果你写了 CSS 文件，它会通过标准的 CSS 语法自动应用到组件上。不过要注意，它的大小有限制，最大不能超过 128 KB。如果你想在多个组件之间共享 CSS，可以通过只支持 CSS 的模块来实现。这样一来，就能避免重复写样式了。 再来看图标。我们可以在组件文件夹里放一个 JPEG 图片，这个图片是用来给应用程序构建器或者体验生成器提供一个自定义图标的。注意，每个文件夹只能放一个这样的图标文件。 另外，我们还可以添加额外的 JS 文件，这些文件能帮助我们更好地结构化 UI 组件里的代码，也可以用来从 API 模块中共享代码。这样代码就更清晰、更容易维护了。 最后，别忘了测试。我们写的是 Jest 测试，测试文件的命名规则是 .test.js，而且必须放在 __tests__ 文件夹里面。这样 Salesforce 就知道这些是用来测试的文件了。 简单总结一下：.js-meta.html 配置文件是必选的，没有就报错；CSS 可选的，大小有限制，可以模块化共享；JPEG 图标每个文件夹一个；额外 JS 文件可以模块化代码；测试文件放在 __tests__ 里，命名要有 .test.js。这些就是组件的基本构成，大家记住了吗？

  ▶ 播放视频 查看详情
• 4

  Component Namespaces

  第 30 页

  同学们，今天我们来聊聊组件的命名空间，这个概念很简单，但特别重要。在 Lightning Web Components 里，每个组件都住在某个命名空间下面。 你创建的自定义组件，默认的命名空间是 c，就是小写字母 c。这个小 c 非常万能，不管代码在哪运行——无论这个组织有没有设置自己的命名空间，也不管你的组件是放在非托管包里，还是将来打包成托管包，c 这个命名空间都可以放心用。 Salesforce 官方的基础组件，像 lightning‑button、lightning‑card 这些，全部放在 lightning 这个命名空间里。在过去还没启用 Lightning Web Security 的时候，只能严格用 c 和 lightning 这两个命名空间里的组件，别的都不给用。 但是现在，只要我们开启了 Lightning Web Security，也就是 LWS，情况就灵活多了。启用 LWS 之后，你可以使用任何命名空间里的组件，包括从 AppExchange 安装的托管包自带的组件。LWS 会通过命名空间实现虚拟代码隔离，不同命名空间的代码互不干扰，安全又有条理。 最后记住一点，如果你要打包一个托管包放在 AppExchange 上分发，就必须给你这个包申请一个全局唯一的命名空间前缀。以后所有组件在使用时，都会带上这个前缀，比如 `yourPrefix__myComponent`，用来区分不同的来源。 好，关于命名空间的核心要点就是这些，你明白了吗？

  ▶ 播放视频 查看详情
• 5

  LWC API Versioning — Overview

  第 31 页

  同学们，今天我们来聊聊LWC里的API版本控制，这个概念听起来有点技术，但其实很好理解，我们慢慢说。 首先，你得知道，从2024年冬季版本开始，也就是API版本59.0，Salesforce要求所有新的自定义组件都必须指定一个API版本。到了2025年春季，这个要求就更严格了，所有现有的自定义组件也都得加上版本。所以，现在你开发LWC，版本号是逃不掉的。 那这个版本是怎么设置的呢？在你的组件文件夹里，有一个叫js-meta.html的文件，里面有个apiVersion标签，就是它来告诉LWC框架：“嘿，我这个组件是按照哪个版本的规则来运行的。” 框架就会按照那个版本的行为方式来解析和渲染你的组件，这样能保证稳定性。比如，某个版本里改了某个特性的处理方式，用了老版本号的组件就不会受影响，继续按老规矩运行。 记住，每个组件只用一个API版本，它所有的文件——比如HTML、JavaScript、CSS——都沿用这同一个版本。但别担心，不同版本的组件可以在同一个页面上和平共处，互不干扰。你完全可以一边用版本50.0的老组件，一边用版本59.0的新组件，它们在同一页上工作得好好的。 那有效的版本范围是什么呢？从最早的45.0一直到当前的版本，比如现在可能是59.0、60.0这样。注意，你可不能随便写个未来的版本，比如你写个61.0，但Salesforce现在最高才60.0，那保存时就会直接报错，不让你这么干。 还有一个贴心的设计：如果你以前创建的组件从来没指定过版本，当这些组件从Salesforce里被检索下来的时候，系统会自动帮你加上apiVersion标签，填上当时最新的版本号，省得你一个一个手动去补。 最后一点，不管你设的apiVersion是多少，组件里用到的Lightning Data Service和基础组件（比如lightning-button、lightning-input这些），永远都是用最新的版本。也就是说，你组件逻辑可以停留在老版本，但底层服务的性能和特性可是自动跟着平台升级的，这样既安全又强大。 好啦，关于API版本控制，咱们就说这么多。记住这几个要点：从59.0开始必须设版本，每个组件一个版本，不同版本能共存，别写未来版本，没设的会被自动加上，底层的服务永远最新。很简单吧？下次写组件的时候，别忘了看一眼你的js-meta.html哦。

  ▶ 播放视频 查看详情
• 6

  Upgrade API Version & Versioning Considerations

  第 32 页

  我们来看这一页很重要的内容，是关于API版本的。这听起来可能有点技术，但其实你把它想成是咱们组件的一个“系统版本号”就行了，很简单。 想象一下，Salesforce这个平台每年都会更新好几次，每次更新都可能带来一些新功能，或者稍微调整一下底层的运作方式。为了让你的组件知道该按哪一套“规矩”来运行，我们就给它设定一个API版本。 那这个版本的升级，有个非常关键的黄金法则，你一定要记住：，一次只升一个版本，并且每一次升级后都要仔细验证。， 为什么？因为Salesforce的版本升级很聪明。比如你现在的组件是从58.0版本升级到59.0版本，如果Salesforce打算在60.0版本里彻底改掉某个功能，它不会直接让你的组件报错不能用。它会先在一个版本里给你一个“警告”。这个警告就像是个温馨提醒，告诉你：“嘿，你这个写法要过时了，得赶紧换换。” 如果你不理它，继续升下个版本，那这个“警告”就会立刻变成一个“错误”，你的组件可能就打不开了。所以，一次只跨一步，能让你安全地处理掉这些警告。 这个API版本的变革，是从59.0版本开始支持的，一直到最新的63.0版本，也就是Spring '25的版本。在每一个版本发布时，官方文档里都会清楚列出“重大更改”，也就是那些可能会让你的组件出错的变化，升级前最好去看一眼。 接下来，还有几个你以后可能会遇到的实际状况，得心里有个数： 第一，同一个页面上，不同的组件完全可以跑在不同的API版本上。你的新组件可以用最新的61.0版本，旁边一个老组件可能还在用58.0版本，它们能和平共处，互不干扰。 第二，有一个默认行为要记一下。如果你的组件版本号写的是低于58.0的，系统会自动把它当作58.0来运行。这就像一个最低保障线。 第三，千万别耍小聪明，直接把版本号写成一个很未来的版本，比如64.0。编译器不认识它，会直接报一个保存错误，根本不让你保存。 那么，这个API版本控制到底写在哪儿，又对谁有效呢？这才是关键。 它是写在组件的`[组件名].js-meta.xml`这个配置文件里的。请特别注意，这个版本控制，只对Lightning Web Components有效，而且只在Lightning Experience主界面或者Experience Builder站点构建器里运行时才起作用，。它不适用于Aura组件，也不适用于在LWR站点上运行的LWC组件。 说到LWR，要特别提醒一下，LWR非常独特，它像一个先锋派，永远使用最新的API版本。你根本没法通过文件配置来控制它，它会自动升级。 好，总结一下这一页的核心：谨慎地、一步一步地通过修改`.js-meta.xml`文件来递增API版本，及时处理警告。记住，这只管得住LWC在核心平台上的行为，管不住LWR，也跟Aura没关系。清楚了这一点，版本升级就没什么可怕的了。

  ▶ 播放视频 查看详情