Lightning Web 组件调度标准 DOM 事件。组件还可以创建和调度自定义事件。使用事件向上传达组件包含层次结构。例如，子组件 调度一个事件，以告知其父组件 ，用户选择了它。c-todo-itemc-todo-app

Lightning Web 组件中的事件基于 DOM 事件构建，DOM 事件是每个浏览器中可用的 API 和对象的集合。

DOM 事件系统是一种包含这些元素的编程设计模式。

• 事件名称，称为类型
• 用于初始化事件的配置
• 发出事件的 JavaScript 对象

要创建事件，我们强烈建议使用界面。在 Lightning Web 组件中，提供跨浏览器的更一致的体验。它不需要设置或样板，它允许您通过属性传递任何类型的数据，这使得它很灵活。CustomEventCustomEventdetail

Lightning Web 组件实现了该接口，允许它们调度事件、侦听事件和处理事件。EventTarget

提示

若要向下通信组件包含层次结构，请通过 HTML 属性将属性传递给子级，或调用其公共方法。要在组件之间进行通信，请使用 Lightning 消息服务或发布订阅实用程序。

创建和调度事件

在组件的 JavaScript 类中创建和调度事件。若要创建事件，请使用构造函数。若要调度事件，请调用该方法。CustomEvent()EventTarget.dispatchEvent()

构造函数有一个必需的参数，该参数是指示事件类型的字符串。作为组件作者，您可以在创建事件时命名事件类型。您可以使用任何字符串作为事件类型。但是，我们建议您遵守 DOM 事件标准。CustomEvent()

• 没有大写字母
• 无空格
• 使用下划线分隔单词

不要在事件名称前面加上字符串 ，因为内联事件处理程序名称必须以字符串 开头。如果调用事件，则标记将为 。注意双倍的单词，这很令人困惑。onononmessage<c-my-component ononmessage={handleMessage}>onon

使用自定义事件进行跨组件通信

示例：调度和处理事件

让我们跳到一些代码中。

该组件包含“上一个”和“下一个”按钮。当用户单击按钮时，组件将创建并调度事件。您可以将组件拖放到需要“上一个”和“下一个”按钮的任何组件中。该父组件侦听事件并处理它们。c-paginatorpreviousnextpaginator

<!-- paginator.html -->
<template>
  <lightning-layout>
    <lightning-layout-item>
      <lightning-button
        label="Previous"
        icon-name="utility:chevronleft"
        onclick={previousHandler}
      ></lightning-button>
    </lightning-layout-item>
    <lightning-layout-item flexibility="grow"></lightning-layout-item>
    <lightning-layout-item>
      <lightning-button
        label="Next"
        icon-name="utility:chevronright"
        icon-position="right"
        onclick={nextHandler}
      ></lightning-button>
    </lightning-layout-item>
  </lightning-layout>
</template>

当用户单击按钮时，将执行 or 函数。这些函数创建和调度 和 事件。previousHandlernextHandlerpreviousnext

// paginator.js
import { LightningElement } from "lwc";

export default class Paginator extends LightningElement {
  previousHandler() {
    this.dispatchEvent(new CustomEvent("previous"));
  }

  nextHandler() {
    this.dispatchEvent(new CustomEvent("next"));
  }
}

这些事件是简单的“某事发生”事件。它们不会将数据有效负载传递到 DOM 树上，它们只是宣布用户单击了一个按钮。

让我们进入一个名为 的组件，它侦听并处理 和 事件。paginatorc-event-simplepreviousnext

要侦听事件，请使用语法为 的 HTML 属性。由于我们的事件类型是 和 ，因此侦听器是 和 。oneventtypepreviousnextonpreviousonnext

<!-- eventSimple.html -->
<template>
  <lightning-card title="EventSimple" icon-name="custom:custom9">
    <div class="slds-m-around_medium">
      <p class="slds-m-vertical_medium content">Page {page}</p>
      <c-paginator onprevious={previousHandler} onnext={nextHandler}></c-paginator>
    </div>
  </lightning-card>
</template>

当收到 和 事件时，并增加和减少页码。c-event-simplepreviousnextpreviousHandlernextHandler

// eventSimple.js
import { LightningElement } from "lwc";

export default class EventSimple extends LightningElement {
  page = 1;

  previousHandler() {
    if (this.page > 1) {
      this.page = this.page - 1;
    }
  }

  nextHandler() {
    this.page = this.page + 1;
  }
}

提示

查看 github.com/trailheadapps/lwc-recipes 存储库中的 c-event-simple 组件和 c-paginator 组件。

在事件中传递数据

若要将数据传递到接收组件，请在构造函数中设置属性。接收组件访问事件侦听器的处理程序函数中属性中的数据。detailCustomEventdetail

注意

该接口对属性不施加任何类型要求或结构。但是，仅发送原始数据很重要。JavaScript 通过引用传递除基元之外的所有数据类型。如果组件在其属性中包含对象，则任何侦听器都可以在组件不知情的情况下更改该对象。这是一件坏事！最佳做法是仅发送基元，或者在将数据添加到属性之前将数据复制到新对象。将数据复制到新对象可确保仅发送所需的数据，并且接收方无法更改数据。CustomEventdetaildetaildetail

让我们看一下 lwc-recipes 存储库中的组件。c-event-with-data

联系人列表中的每个项目都是一个嵌套组件。c-contact-list-item

该组件使用执行函数的事件侦听器将联系人姓名和图片包装在锚标记中。c-contact-list-itemonclickselectHandler

<!-- contactListItem.html -->
<template>
    <a href="#" onclick={selectHandler}>
        <lightning-layout vertical-align="center">
            <lightning-layout-item>
                <img src={contact.Picture__c}></img>
            </lightning-layout-item>
            <lightning-layout-item padding="around-small">
                <p>{contact.Name}</p>
            </lightning-layout-item>
        </lightning-layout>
    </a>
</template>

当用户单击以选择联系人时，该组件将创建并调度被调用的 .该事件包括数据，即所选联系人的 ID。父级 ， 使用联系人引用来显示有关联系人的详细信息。CustomEventselecteddetail: this.contact.Idc-event-custom

// contactListItem.js
import { LightningElement, api } from "lwc";

export default class ContactListItem extends LightningElement {
  @api contact;

  selectHandler(event) {
    // Prevents the anchor element from navigating to a URL.
    event.preventDefault();

    // Creates the event with the contact ID data.
    const selectedEvent = new CustomEvent("selected", { detail: this.contact.Id });

    // Dispatches the event.
    this.dispatchEvent(selectedEvent);
  }
}

该组件侦听属性中的事件，并在事件处理程序中处理该事件。c-event-with-dataselectedonselectedcontactSelected

<!-- eventWithData.html -->
<template>
    <lightning-card title="EventWithData" icon-name="custom:custom9">
        <lightning-layout class="slds-m-around_medium">
            <lightning-layout-item>
                <template lwc:if={listIsNotEmpty}>
                    <template for:each={contacts.data} for:item="contact">
                        <c-contact-list-item key={contact.Id} contact={contact} onselected={contactSelected}></c-contact-list-item>
                    </template>
                </template>
            </lightning-layout-item>
            <lightning-layout-item class="slds-m-left_medium">
                <template lwc:if={selectedContact}>
                    <img src={selectedContact.Picture__c}></img>
                    <p>{selectedContact.Name}</p>
                    <p>{selectedContact.Title}</p>
                    <p><lightning-formatted-phone value={selectedContact.Phone}></lightning-formatted-phone></p>
                    <p><lightning-formatted-email value={selectedContact.Email}></lightning-formatted-email></p>
                </template>
            </lightning-layout-item>
        </lightning-layout>
    </lightning-card>
</template>

在事件处理程序中，组件将属性分配给属性。它在通过 置备的阵列中查找具有该 ID 的联系人，并在模板中显示联系人的姓名、职务、电话和电子邮件。contactSelectedevent.detailcontactIdcontacts@wire

// eventWithData.js
import { LightningElement, wire } from "lwc";
import getContactList from "@salesforce/apex/ContactController.getContactList";

export default class EventWithData extends LightningElement {
  selectedContact;

  @wire(getContactList) contacts;

  contactSelected(event) {
    const contactId = event.detail;
    this.selectedContact = this.contacts.data.find((contact) => contact.Id === contactId);
  }

  get listIsNotEmpty() {
    return this.contacts && Array.isArray(this.contacts.data) && this.contacts.data.length > 0;
  }
}

提示

查看 github.com/trailheadapps/lwc-recipes 存储库中的 c-event-with-data 组件。

处理事件

有两种方法可以侦听事件：从组件的 HTML 模板以声明方式侦听事件，或者使用命令式 JavaScript API 以编程方式侦听事件。最好从 HTML 模板中监听，因为它减少了您必须编写的代码量。若要处理事件，请在组件的 JavaScript 类中定义方法。

以声明方式附加事件侦听器

在所有者组件的模板中以标记形式声明侦听器，在本例中为 .c-parent

<!-- parent.html -->
<template>
  <c-child onnotification={handleNotification}></c-child>
</template>

在此示例中，在 JavaScript 文件中定义处理程序函数。handleNotificationc-parent

// parent.js
import { LightningElement } from "lwc";
export default class Parent extends LightningElement {
  handleNotification() {
    // Code runs when event is received
  }
}

以编程方式附加事件侦听器

在 JavaScript 中定义侦听器和处理程序函数。c-parent

// parent.js
import { LightningElement } from "lwc";
export default class Parent extends LightningElement {
  constructor() {
    super();
    this.template.addEventListener("notification", this.handleNotification);
  }
  handleNotification = () => {};
}

如果将同一侦听器重复添加到同一元素中，则浏览器将忽略重复项。

如果未删除事件侦听器，则可以选择在调用中内联代码。handleNotificationaddEventListener()

this.template.addEventListener("notification", (evt) => {
  console.log("Notification event", evt);
});

重要

不要使用 .这是一个反模式，因为返回一个新函数，因此组件不能使用相同的函数实例进行调用。由于组件不能使用相同的函数实例，因此侦听器会造成内存泄漏。addEventListener({eventName}, this.handleNotification.bind(this))bind()removeEventListener()

添加事件侦听器有两种语法。一个用于将事件侦听器添加到组件的影子边界内的元素，另一个用于将事件侦听器添加到模板不拥有的元素，例如，传递到槽中的元素。

要将事件侦听器添加到阴影边界内的元素，请使用 .template

this.template.addEventListener();

若要将事件侦听器添加到模板不拥有的元素，请直接调用。addEventListener

this.addEventListener();

获取对调度事件的组件的引用

若要获取对调度事件的对象的引用，请使用 Event.target 属性，该属性是事件的 DOM API 的一部分。

提示

lwc-recipes repo 中的几个配方使用 .若要查找示例，请在存储库中搜索 .Event.targetEvent.target

事件重定向

当事件冒泡 DOM 时，如果它越过阴影边界，则 的值会更改以匹配侦听器的范围。此更改称为“事件重定向”。事件被重新定位，因此侦听器无法看到调度事件的组件的影子 DOM。事件重定向保留了影子 DOM 封装。Event.target

让我们看一个简单的例子。

<!-- myButton.html -->
<template>
  <button>{label}</button>
</template>

单击侦听器始终接收作为目标，即使单击发生在元素上也是如此。<my-button>my-buttonbutton

想象一下，一个事件是从组件中的元素调度出来的。在组件的影子 DOM 中，是 .但是对于包含组件中元素的侦听器来说，是 ，因为该元素无法看到影子 DOM。divc-todo-itemEvent.targetdivpc-todo-appEvent.targetc-todo-itempc-todo-item

<c-todo-app>
  #shadow-root
  <div>
    <p>Your To Do List</p>
  </div>
  <c-todo-item>
    #shadow-root
    <div>
      <p>Go to the store</p>
    </div>
  </c-todo-item>
</c-todo-app>

有趣的是，对于 上的侦听器来说，是 ，而不是 ，因为 在阴影边界之外。c-todo-itemEvent.targetc-todo-itemdivc-todo-item

侦听输入字段的更改

若要侦听模板中接受输入的元素（如文本字段 （ 或 ））的更改，请使用该事件。<input><lightning-input>onchange

<!-- form.html -->
<template>
  <input type="text" value={myValue} onchange={handleChange} />
</template>

// form.js
import { LightningElement } from "lwc";
export default class Form extends LightningElement {
  myValue = "initial value";

  handleChange(evt) {
    console.log("Current value of the input: " + evt.target.value);
  }
}

在此示例中，每次输入值更改时都会调用 JavaScript 文件中的方法。handleChange()

该属性表示输入元素的值。此属性值不会在每次更改时自动更新。myValue

您可能需要对用户输入的值进行额外验证，以便在用户键入时自动更正或限制某些值。若要与输入的当前值保持同步，请在方法中更新。以下代码通过删除字符串开头和结尾的空格来自动更正键入的值。用于获取输入字段的当前值。myValuemyValuehandleChange()evt.target.value

// form.js
import { LightningElement } from "lwc";
export default class Form extends LightningElement {
  myValue = "initial value";

  handleChange(evt) {
    const typedValue = evt.target.value;
    const trimmedValue = typedValue.trim(); // trims the value entered by the user
    if (typedValue !== trimmedValue) {
      evt.target.value = trimmedValue;
    }
    this.myValue = trimmedValue; // updates the internal state
  }
}

此示例演示如何将 input value 属性重置为行 中的修剪值。它还演示了如何使属性与规范化值保持同步，以防组件将来被重新冻结（加载新值）。evt.target.value = trimmedValuemyValue

注意

从通过模板定义的元素中更改属性可能会在组件中的其他位置产生不希望的副作用。在我们的示例中，元素的输入值属性从模板中定义的值更改为 。该示例更改模板 （） 中使用的值，以使组件元素的状态保持同步。否则，模板解除冻结会在尝试将输入元素的状态与组件的状态进行协调时检测到属性值不匹配。这种不匹配会生成运行时警告，您需要调整组件或 JavaScript，以保持整个模板中数据的完整性。evt.targetmyValue

删除事件侦听器

作为组件生命周期的一部分，该框架负责为您管理和清理侦听器。但是，如果您将侦听器添加到其他任何内容（如对象、对象等），则您有责任自行删除侦听器。windowdocument

要删除事件侦听器，请使用 disconnectedCallback 生命周期挂钩。

配置事件传播

触发事件后，它可以通过 DOM 向上传播。若要了解事件的处理位置，请了解事件的传播方式。

事件通过 DOM 冒泡;这就是孩子和父母的沟通方式——向下支撑，向上事件。当事件冒泡时，它将成为组件 API 的一部分，事件路径上的每个使用者都必须了解该事件。了解冒泡的工作原理非常重要，这样您就可以选择适用于您的组件的最具限制性的冒泡配置。

Lightning Web 组件事件的传播规则与 DOM 事件相同。Lightning Web 组件仅使用冒泡阶段。不支持调度事件或将侦听器添加到捕获阶段。简单地将事件的路径视为从组件开始，然后移动到其父组件，然后是祖父级，依此类推。

事件目标不会传播到组件实例的影子根之外。在组件外部，所有事件目标都是组件本身。但是，在影子树中，您可以处理来自树中特定目标的事件。根据事件的侦听器附加位置以及事件发生的位置，可以具有不同的目标。

注意

此内容改编自 Salesforce 开发人员博客文章 Lightning Web 组件中的事件如何冒泡。

创建事件时，请使用事件的两个属性和 定义事件传播行为。bubblescomposed

• Event.bubbles一个 Boolean 值，该值指示事件是否通过 DOM 冒泡。缺省值为 .false
• Event.composed一个 Boolean 值，该值指示事件是否可以穿过阴影边界。缺省值为 .false

若要获取有关事件的信息，请使用事件 Web API 的这些属性和方法。

• Event.target调度事件的元素。每个组件的内部 DOM 都封装在一个影子 DOM 中。阴影边界是常规 DOM（也称为轻量级 DOM）和阴影 DOM 之间的线。如果事件冒泡并越过阴影边界，则 value of 的值将更改为表示与侦听器位于同一作用域中的元素。事件重定向可保留组件封装，并防止暴露组件的内部。Event.target例如，单击侦听器始终接收作为目标，即使单击发生在元素上也是如此。<my-button>my-buttonbutton<!-- myButton.html --> <template> <button>{label}</button> </template>
• Event.currentTarget当事件遍历 DOM 时，此属性始终引用事件处理程序附加到的元素。
• Event.composedPath()当事件遍历 DOM 时，将在其上调用侦听器的事件目标的数组。

静态成分

静态合成不使用插槽。在这个简单的例子中，compose ，而 compose 。c-appc-parentc-child

<c-app onbuttonclick={handleButtonClick}></c-app>

应用程序中的父组件处理按钮单击。

<!-- app.html -->
<template>
  <h2>My app</h2>
  <c-parent onbuttonclick={handleButtonClick}></c-parent>
</template>

父组件包含一个带有子组件的包装器，这两个组件都侦听按钮单击事件。

<!-- parent.html -->
<template>
  <h3>I'm a parent component</h3>
  <div class="wrapper" onbuttonclick={handleButtonClick}>
    <c-child onbuttonclick={handleButtonClick}></c-child>
  </div>
</template>

子组件包含带有处理程序的按钮。onclick

<!-- child.html -->
<template>
  <h3>I'm a child component</h3>
  <button onclick={handleClick}>click me</button>
</template>

// child.js
handleClick() {
    const buttonclicked = new CustomEvent('buttonclick', {
        //event options
    });
    this.dispatchEvent(buttonclicked);
}

该示例从单击按钮时触发事件 。事件侦听器为以下元素上的自定义事件附加：buttonclickc-child

• body
• c-app主机
• c-parent
• div.wrapper
• c-child主机

扁平化的树如下所示：

<body>
  <!-- Listening for buttonclick event -->
  <c-app>
    <!-- Listening for buttonclick event -->
    #shadow-root
    |  <h2>My app</h2>
    |  <c-parent>
    |    <!-- Listening for buttonclick event -->
    |    #shadow-root
    |    |  <h3>I'm a parent component</h3>
    |    |  <div class="wrapper">
    |    |     <!-- Listening for buttonclick event -->
    |    |     <c-child>
    |    |      #shadow-root 
    |    |      |  <!-- Listening for buttonclick event -->
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |      </c-child>
    |    |    </div>
    |  </c-parent>
  </c-app>
</body>

气泡：假，组合：假

默认配置。该事件不会通过 DOM 冒泡，也不会越过阴影边界。侦听此事件的唯一方法是直接在调度事件的组件上添加事件侦听器。

建议使用此配置，因为它的中断最小，并且为组件提供最佳封装。

事件最多只能冒泡。c-child

<body>
  <c-app>
    #shadow-root
    |  <c-parent>
    |    #shadow-root
    |    |  <div class="wrapper">
    |    |    <c-child>
    |    |    <!-- Event bubbles up here -->
    |    |      #shadow-root
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |     </c-child>
    |    |  </div>
    |  </c-parent>
  </c-app>
</body>

检查处理程序会在事件上返回这些值。c-child

• event.currentTarget = c-child
• event.target = c-child

从这里开始，您可以开始实现更宽松的配置，如以下几节所示。

提示

lwc-recipes 存储库中的 c-event-with-data 组件使用 c-contact-list-item 组件，该组件使用 和 创建事件。bubbles: falsecomposed: false

气泡：真，组合：假

事件通过 DOM 冒泡，但不会越过影子边界。因此，两者都可以对事件做出反应。c-childdiv.wrapper

<body>
  <c-app>
    #shadow-root
    |  <c-parent>
    |    #shadow-root
    |    |  <div class="wrapper">
    |    |  <!-- Event bubbles up here -->
    |    |    <c-child>
    |    |    <!-- Event bubbles up here -->
    |    |      #shadow-root
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |    </c-child>
    |    |  </div>
    |  </c-parent>
  </c-app>
</body>

事件处理程序返回以下内容。

C-Child 处理程序

• event.currentTarget = c-child
• event.target = c-child

div.childWrapper 处理程序

• event.currentTarget = div.childWrapper
• event.target = c-child

使用此配置有两个用例。

• 创建内部活动若要在组件的模板中冒泡事件，请在模板中的元素上调度该事件。该事件仅冒泡到模板内元素的祖先。当事件到达阴影边界时，它将停止。// myComponent.js this.template.querySelector("div").dispatchEvent(new CustomEvent("notify", { bubbles: true }));必须在 中处理该事件。包含组件中的处理程序不会执行，因为事件不会越过阴影边界。myComponent.js<!-- container.html --> <template> <!-- handleNotify doesn’t execute --> <c-my-component onnotify={handleNotify}></c-my-component> </template>
• 将事件发送到组件的祖父级如果将组件传递到槽中，并且您希望将该组件中的事件冒泡到包含该组件的模板，请在主机元素上调度该事件。该事件仅在包含组件的模板中可见。让我们看一下从 lwc-recipes 存储库中的组件中删节的示例代码。从子级到祖父级的组件层次结构是 。eventBubblingc-contact-list-item-bubbling -> lightning-layout-item -> c-event-bubbling该组件调度一个调用 的自定义事件。c-contact-list-item-bubblingcontactselectbubbles: true事件侦听器位于其父级 上，事件在其祖父级 中处理。oncontactselectlightning-layout-itemc-event-bubbling<!-- eventBubbling.html --> <template> <lightning-card title="EventBubbling" icon-name="standard:logging"> <template lwc:if={contacts.data}> <lightning-layout class="slds-var-m-around_medium"> <!-- c-contact-list-item-bubbling emits a bubbling event so a single listener on a containing element works --> <lightning-layout-item class="wide" oncontactselect={handleContactSelect}> <template for:each={contacts.data} for:item="contact"> <c-contact-list-item-bubbling class="slds-show slds-is-relative" key={contact.Id} contact={contact} ></c-contact-list-item-bubbling> </template> </lightning-layout-item> </lightning-layout> </template> </lightning-card> </template>// contactListItemBubbling.js import { LightningElement, api } from "lwc"; export default class ContactListItemBubbling extends LightningElement { @api contact; handleSelect(event) { // Prevent default behavior of anchor tag click which is to navigate to the href url event.preventDefault(); const selectEvent = new CustomEvent("contactselect", { bubbles: true, }); this.dispatchEvent(selectEvent); } }

气泡：真，组合：真

事件通过 DOM 冒泡，越过影子边界，然后继续冒泡通过 DOM 冒泡到文档根目录。

重要

如果事件使用此配置，则事件类型将成为组件公共 API 的一部分。它还强制使用组件及其所有祖先将事件作为其 API 的一部分包含在内。

由于此配置将事件一直冒泡到文档根目录，因此可能会导致名称冲突。名称冲突可能会导致触发错误的事件侦听器。

<body>
<!-- Event bubbles up here -->
  <c-app>
  <!-- Event bubbles up here -->
    #shadow-root
    |  <c-parent>
    |  <!-- Event bubbles up here -->
    |    #shadow-root
    |    |  <div class="wrapper">
    |    |  <!-- Event bubbles up here -->
    |    |    <c-child>
    |    |    <!-- Event bubbles up here -->
    |    |      #shadow-root
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |   </c-child>
    |    |  </div>
    |  </c-parent>
  </c-app>
</body>

如果确实使用此配置，请在事件类型前面加上命名空间，例如 。HTML 事件侦听器将具有尴尬的名称。mydomain__myeventonmydomain__myevent

气泡：假，组合：真

Lightning Web 组件不使用此配置。

跨 DOM 进行通信

有两种方法可以在不在同一 DOM 树中的组件之间进行通信。使用 Lightning 消息服务 （），或使用遵循发布-订阅模式的单例库。lightning/messageService

使用 Lightning 消息服务

要在单个 Lightning 页面或多个页面的组件之间进行通信，请使用 Lightning 消息服务通过 Lightning 消息通道进行通信。优点是消息通道不限于单个页面。Lightning Experience 应用程序中侦听消息通道上事件的任何组件在收到消息时都会更新。它可以在 Lightning Web 组件、Aura 组件和 Visualforce 页面之间工作，可以在 Lightning Experience 中的任何选项卡或任何弹出窗口中使用。它也可以跨命名空间工作。有关更多信息，请参阅使用 Lightning 消息服务跨 DOM 进行通信。pubsub

使用 pubsub 模块

在不支持 Lightning 消息传递服务的容器中，使用该模块。从 github.com/developerforce/pubsub 下载模块。pubsub

在发布-订阅模式中，一个组件发布一个事件。其他组件订阅以接收和处理事件。订阅该事件的每个组件都会接收该事件。该模块将事件限制在单个页面中。pubsub

活动最佳实践

我们建议在处理事件时遵循这些最佳做法。CustomEvent.detail

要将数据传达给同一影子树中的元素，请不要添加到 .事件的使用者可以使用 .myPropertyevent.detailevent.target.myProperty

若要将数据传达给不在同一影子树中的元素，请使用 .在这些情况下，不起作用，因为侦听器看不到真正的目标。（当事件冒泡 DOM 时，如果它越过影子边界，则 的值会更改以匹配侦听器的范围。事件被重新定位，因此侦听器无法看到调度事件的组件的影子树。event.detailevent.target.*Event.target

如果使用 ，请使用基元类型。JavaScript 通过引用传递除基元之外的所有数据类型。如果一个组件在其属性中包含一个对象，任何侦听器都可以在组件不知情的情况下改变该对象，这是一件坏事！detaildetail

使用非基元类型时，可以避免泄漏内部状态。在向属性添加数据之前，请将其复制到新对象或数组。将数据复制到新对象可确保仅发送所需的数据，并且接收方无法更改数据。detail

不要包含非基元 from 或 in 。这些值被包裹在只读膜中。在 IE 11 中，当穿过 LWC 到 Aura 桥时，只读膜丢失，这意味着可能会发生突变。@api@wiredetail事件传播

使用配置了 和 的事件，因为它们的中断最小。这些事件不会通过 DOM 冒泡，也不会越过影子边界。bubbles: falsecomposed: false

不建议使用冒泡和组合事件，因为它们会冒泡整个 DOM 树，跨越阴影边界，并通过父组件（除非停止）。如果使用 和 配置事件，则事件类型将成为组件公共 API 的一部分。它还强制使用组件及其所有祖先将事件作为其 API 的一部分包含在内。这是一个需要注册的大型 API 合约。如果使用此配置，则事件类型应全局唯一。bubbles: truecomposed: true

Lightning Web 组件的生命周期由框架管理。框架创建组件，将它们插入到 DOM 中，呈现它们，然后将它们从 DOM 中删除。它还监视组件的属性更改。

生命周期流程

此图显示了从创建到渲染的组件生命周期流程。

此图显示了从 DOM 中删除组件实例时发生的情况。

创建组件时运行代码

该方法在创建组件实例时触发。不要在构造过程中向 host 元素添加属性。您可以在任何其他生命周期挂钩中向 host 元素添加属性。constructor()

构造函数从父级流向子级。

构造函数注意事项

HTML： Custom elements 规范中的这些要求适用于 .constructor()

• 第一个语句必须不带参数。此调用为 建立正确的原型链和值。在触摸之前务必先打电话。super()thissuper()this
• 不要在构造函数主体中使用语句，除非它是简单的提前返回 （ 或 ）。returnreturnreturn this
• 不要使用 or 方法。document.write()document.open()
• 不要检查元素的属性和子元素，因为它们尚不存在。
• 不要检查元素的公共属性，因为它们是在创建组件后设置的。

不要在构造过程中向主机元素添加属性

您可以在组件生命周期的任何阶段（构造除外）向主机元素添加属性。

不建议使用此模式，因为它会向 host 元素添加一个属性。constructor()

// don't do this
import { LightningElement } from "lwc";
export default class Deprecated extends LightningElement {
  constructor() {
    super();
    this.classList.add("new-class");
  }
}

若要向 host 元素添加属性，请改用该方法。connectedCallback()

import { LightningElement } from "lwc";

export default class New extends LightningElement {
  connectedCallback() {
    this.classList.add("new-class");
  }
}

在 DOM 中插入或删除组件时运行代码

当组件插入到 DOM 中时，生命周期钩子会触发。当组件从 DOM 中删除时，生命周期挂钩会触发。connectedCallback()disconnectedCallback()

两个钩子都从父级流向子级。您无法从回调访问子元素，因为它们尚不存在。要访问 host 元素，请使用 .要访问组件模板中的元素，请使用 .thisthis.template

用于与组件的环境进行交互。例如，使用它来：connectedCallback()

• 与当前文档或容器建立通信，并协调与环境的行为。
• 执行初始化任务，例如获取数据、设置缓存或侦听事件
• 订阅和取消订阅消息通道。

钩子是使用传递给组件的初始属性调用的。如果组件从属性派生其内部状态，则最好在 setter 中编写逻辑，而不是在 中编写逻辑。有关示例代码，请参阅 Salesforce 工程师 Pierre-Marie Dartus 撰写的这篇 StackExchange 文章。connectedCallback()connectedCallback()

钩子可以发射不止一次。例如，如果删除一个元素，然后将其插入到另一个位置，例如在对列表重新排序时，挂钩会触发几次。如果希望代码运行一次，请编写代码以防止其运行两次。connectedCallback()

用于清理 中完成的工作，例如清除缓存或删除事件侦听器。disconnectedCallback()connectedCallback()

要检查组件是否连接到 DOM，可以使用 this.isConnected。

在组件呈现时运行代码

这是 Lightning Web 组件所独有的。使用它在组件完成渲染阶段后执行逻辑。renderedCallback()

此挂钩从子级流向父级。

当组件呈现时，将重新计算模板中使用的表达式。

连接并渲染组件后，对组件状态的更改（或突变）会将组件标记为脏组件，并将微任务排入队列以重新渲染组件。有关跟踪哪些更改的详细信息，请参阅反应性。

在应用程序的生命周期中，组件通常会呈现多次。要使用此钩子执行一次性操作，请使用布尔字段 like 来跟踪是否已执行。第一次执行时，执行一次性操作并设置 .如果 ，则不执行该操作。hasRenderedrenderedCallback()renderedCallback()hasRendered = truehasRendered = true

最好在 HTML 模板中以声明方式添加事件侦听器。但是，如果确实需要以编程方式向模板元素添加事件侦听器，请在 中执行此操作。您无需删除侦听器。如果将侦听器重复添加到同一元素中，浏览器将忽略重复项。renderedCallback()

重新呈现模板时，LWC 引擎会尝试重用现有元素。在以下情况下，引擎使用差异算法来决定是否丢弃元素。

• 使用 for：each 指令创建的元素。重用这些迭代元素的决定取决于属性。如果发生更改，则元素可能会被重新呈现。如果未更改，则不会重新呈现元素，因为引擎假定迭代元素未更改。keykeykey
• 作为槽内容接收的元素。引擎尝试重用 中的元素，但差异算法确定是否逐出元素并重新创建它。<slot>

更新组件的状态可能会导致无限循环。例如：renderedCallback()

• 不要更新 中的电线适配器配置对象属性。请参阅了解 Wire Service。renderedCallback()
• 不要更新 中的公共属性或字段。请参阅反应性。renderedCallback()

提示

lwc-recipes samples 存储库中的模块使用 lifecycle hook。libsChartjsrenderedCallback()

处理组件错误

这是 Lightning Web 组件所独有的。实现它以创建一个错误边界组件，该组件捕获其树中所有后代组件中的错误。它捕获在后代的生命周期挂钩中或在 HTML 模板中声明的事件处理程序期间发生的错误。您可以对错误边界组件进行编码，以记录堆栈信息并呈现替代视图，以告知用户发生了什么以及下一步要做什么。errorCallback()

您可以创建错误边界组件，并在整个应用中重复使用它。由您决定在哪里定义这些错误边界。您可以包装整个应用程序，也可以包装每个单独的组件。最有可能的是，你的架构介于两者之间。想一想你想在什么地方告诉用户出了问题。

<!-- boundary.html -->
<template>
  <template lwc:if={error}>
    <error-view error={error} info={stack}></error-view>
  </template>
  <template lwc:else>
    <healthy-view></healthy-view>
  </template>
</template>

// boundary.js
import { LightningElement } from "lwc";
export default class Boundary extends LightningElement {
  error;
  stack;
  errorCallback(error, stack) {
    this.error = error;
  }
}

参数是 JavaScript 本机错误对象，参数是字符串。errorstack

您不必在模板中使用。例如，假设您定义了一个组件模板。如果此组件引发错误，框架将在重新渲染期间调用并卸载该组件。lwc:[if|elseif|else]errorCallback

<!-- boundary.html -->
<template>
  <my-one-and-only-view></my-one-and-only-view>
</template>

辅助软件和辅助技术使残障用户能够使用您构建的产品。开发组件，以便所有用户都能感知、理解、导航并与之交互。

我们建议您在创建自定义组件时遵循 WCAG 辅助功能指南。

组件辅助功能属性

若要使组件可用于屏幕阅读器和其他辅助技术，请在组件上使用 HTML 属性。HTML 属性描述它们所包含的 UI 元素。辅助功能软件通过大声朗读属性来解释 UI 元素。

辅助功能的一个关键部分是属性的使用。屏幕阅读器向用户读出属性值。当您使用具有属性的 Lightning Web 组件时，请始终指定一个值。例如，组件具有属性。titletitletitlelightning-buttontitle

<!-- parent.html -->
<template>
  <lightning-button title="Log In" label="Log In" onclick={login}></lightning-button>
</template>

该模板创建如下所示的 HTML 输出，供屏幕阅读器向用户读出“登录”。

<!-- Generated HTML -->
<lightning-button>
  <button title="Log In">Log In</button>
</lightning-button>

创建 Lightning Web 组件时，如果您希望屏幕阅读器向用户大声朗读值，请使用 to 公开公共属性。@apititle

当您通过将某个属性公开为公共属性来控制该属性时，默认情况下，该属性将不再显示在 HTML 输出中。若要将值作为属性传递到呈现的 HTML（以反映属性），请为属性定义 getter 和 setter 并调用该方法。setAttribute()

您还可以在 setter 中执行操作。使用私有属性来保存计算值。

// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  privateTitle;
  @api
  get title() {
    return this.privateTitle;
  }

  set title(value) {
    this.privateTitle = value.toUpperCase();
    this.setAttribute("title", this.privateTitle);
  }
}

<!-- parent.html -->
<template>
  <c-my-component title="Hover Over the Component to See Me"></c-my-component>
</template>

/* Generated HTML */
<c-my-component title="HOVER OVER THE COMPONENT TO SEE ME">
  <div>Reflecting Attributes Example</div>
</c-my-component>

有关使用 的详细信息，请参阅将 JavaScript 属性反映到 HTML 属性。setAttribute()

ARIA 属性

若要提供更高级的辅助功能，例如屏幕阅读器读出按钮的当前状态，请使用 ARIA 属性。这些属性为支持 ARIA 标准的屏幕阅读器提供了更详细的信息。

您可以将 ARIA 属性与 HTML 模板中的属性相关联。在组件的模板文件中，值必须是唯一的，以便屏幕阅读器可以将 ARIA 属性（如 、）与特定元素相关联。ididaria-describedbyaria-detailsaria-owns

注意

呈现模板时，值可能会转换为全局唯一值。不要在 CSS 或 JavaScript 中使用选择器，因为它与转换后的 .请改用元素的属性或类似 的属性。idididclassdata-*data-id

让我们看一些代码。该属性告诉屏幕阅读器在按下按钮时说出该按钮。使用组件时，您可以编写：aria-pressedlightning-button

<!-- parent.html -->
<template>
  <lightning-button
    title="Log In"
    label="Log In"
    onclick={login}
    aria-label="Log In"
    aria-pressed
  ></lightning-button>
</template>

该组件将 ARIA 属性定义为公共属性，并使用字段来获取和设置公共属性。

<!-- lightning-button.html -->
<template>
  <button
    title="Log In"
    label="Log In"
    onclick={login}
    aria-label={innerLabel}
    aria-pressed={pressed}
  ></button>
</template>

组件 JavaScript 使用 camel-case 属性映射来获取和设置 中的值。lightning-button.js

// lightning-button.js
import { LightningElement, api } from "lwc";
export default class LightningButton extends LightningElement {
  innerLabel;

  @api
  get ariaLabel() {
    return this.innerLabel;
  }

  set ariaLabel(newValue) {
    this.innerLabel = newValue;
  }

  pressed;

  @api
  get ariaPressed() {
    return this.pressed;
  }

  set ariaPressed(newValue) {
    this.pressed = newValue;
  }
}

生成的 HTML 为：

<lightning-button>
  <button
    title="Log In"
    label="Log In"
    onclick={login}
    aria-label="Log In"
    aria-pressed="true"
  ></button>
</lightning-button>

支持 ARIA 的屏幕阅读器读取标签并指示按钮已按下。

注意

ARIA 属性在访问器函数中使用驼峰大小写。例如，变为 .完整的映射列表位于 GitHub 存储库 lwc/packages/@lwc/template-compiler/src/parser/constants.ts 中。aria-labelariaLabel

默认 ARIA 值

组件作者可能希望在自定义组件上定义默认的 ARIA 属性，并且仍允许组件使用者指定属性值。在这种情况下，组件作者在组件的元素上定义默认的 ARIA 值。

// lightning-button.js sets "Log In" as the default label
import { LightningElement } from "lwc";
export default class LightningButton extends LightningElement {
  connectedCallback() {
    this.template.ariaLabel = "Log In";
  }
}

注意

在 中定义属性。不要在 中定义属性。connectedCallback()constructor()

当您使用组件并提供值时，将显示提供的值。aria-label

<!-- parent.html -->
<template>
  <lightning-button
    title="Log In"
    label="Submit"
    onclick={login}
    aria-label="Submit"
    aria-pressed
  ></lightning-button>
</template>

生成的 HTML 为：

<lightning-button>
  <button title="Log In" label="Submit" aria-label="Submit" aria-pressed="true"></button>
</lightning-button>

而且，如果未提供值，则会显示默认值。aria-label

<!-- parent.html -->
<template>
  <lightning-button title="Log In" label="Log In" onclick={login}></lightning-button>
</template>

生成的 HTML 为：

<lightning-button>
  <button title="Log In" label="Log In" onclick={login} aria-label="Log In"></button>
</lightning-button>

静态值

如果您创建自定义组件并且不希望属性的值发生更改，该怎么办？一个很好的例子是属性。您不希望组件使用者更改为 。按钮就是按钮。rolebuttontab

您始终希望生成的 HTML 具有 be ，如本例所示。rolebutton

<lightning-button>
  <div title="Log In" label="Log In" onclick={login} role="button"></div>
</lightning-button>

为了防止使用者更改属性的值，只需返回一个字符串。此示例始终返回该值。"button"role

// lightning-button.js
import { LightningElement, api } from "lwc";
export default class LightningButton extends LightningElement {
  set role(value) {}

  @api
  get role() {
    return "button";
  }
}

来自不同模板的链接 ID 和 ARIA 属性

同一模板中的 ID 和 ARIA 属性会自动链接。如果属性位于不同的模板中，则必须手动链接它们。

在本机影子 DOM 中，您无法在单独模板中的元素之间链接 ID 和 ARIA 属性。

要使用 ID 和 ARIA 属性将两个元素链接在一起，请使用 light DOM 将它们放置在同一个阴影根中。请参阅 Light DOM 中的辅助功能部分。

处理焦点

要使残障人士能够访问您的组件，请对它们进行编程，以处理哪个元素具有焦点并可以接收输入。

Web 浏览器可通过键盘使用 Tab 键进行完全导航。出于辅助功能目的，依赖键盘导航的用户需要视觉提示来查看哪个元素具有焦点。视力低下的人也使用屏幕阅读器来浏览网页。屏幕阅读器大声朗读页面上的元素，包括具有焦点的元素。作为开发人员，您需要确保当用户按 Tab 键浏览页面时，浏览器会将焦点移到下一个逻辑元素。

当用户按 Tab 键浏览页面时，交互元素（如 、 、 和 接收）会自动获得焦点。本机不可聚焦的元素（如 或 ）可用于接收键盘焦点。<a><button><input><textarea><div><span>tabindex="0"

注意

仅支持 和 tabindex 值。分配意味着元素聚焦在标准顺序键盘导航中。分配它会从顺序键盘导航中删除该元素。有关详细信息，请参阅键盘辅助功能。0-1tabindex="0"tabindex="-1"

选项卡导航期间的焦点行为

对于自定义组件，焦点会跳过组件容器并移动到组件内部的元素。

让我们看一些代码。

在此示例中，当用户按 Tab 键时，焦点会从 按钮元素移动到 中的输入元素，从而跳过自身。parentchildchild

<!-- parent.html -->
<template>
  <button>Button</button>
  <c-child></c-child>
</template>

<!-- child.html -->
<template>
  <span
    >Tabbing to the custom element moves focus to the input, skipping the component itself.</span
  >
  <br /><input type="text" />
</template>

将焦点应用于子组件

若要向自定义组件添加焦点，请使用该属性。在父模板中，我们将子组件设置为将子组件本身添加到导航序列中。tabindextabindex0

<!-- parent.html -->
<template>
  <button>Button</button>
  <c-child tabindex="0"></c-child>
</template>

<!-- child.html -->
<template>
  <span>Tabbing to the custom element moves focus to the whole component.</span>
  <br /><input type="text" />
</template>

// child.js
import { LightningElement } from "lwc";

export default class Child extends LightningElement {}

在自定义组件中委派焦点

创建包含可聚焦元素的自定义组件时，您可能会发现自己需要管理选项卡索引或手动将焦点设置在这些元素上。要自动管理焦点，请设置为 。delegatesFocustrue

假设我们有一个带有按钮的自定义组件，其行为类似于本机 HTML 按钮。

<!-- coolButton.html -->
<template>
  <button>Focus!</button>
</template>

// coolButton.js
import { LightningElement } from "lwc";

export default class CoolButton extends LightningElement {
  static delegatesFocus = true;
}

使用可实现以下情况。delegatesFocus

• 使用 将焦点添加到本机按钮 HTML 元素。coolButton.focus()
• 如果单击阴影 DOM 中的某个节点，并且该节点不是可聚焦区域，则第一个可聚焦区域将变为焦点。这类似于单击标签并将焦点跳转到输入时。
• 当影子 DOM 中的节点获得焦点时，除了焦点元素之外，CSS 选择器还会应用于主机。:focus

注意

不要使用 with，因为它会偏离焦点顺序。tabindexdelegatesFocus

移动就绪组件

Lightning Web 组件支持在桌面和移动设备上使用组件。在桌面上，支持各种 Web 浏览器。在移动设备上，支持的环境包括 Salesforce 分布式移动应用程序。这两种环境之间的差异不仅仅是屏幕尺寸;有新的限制，也有移动端的扩展功能。若要构建在移动体验中表现良好的组件，请遵循我们的移动就绪组件指南。

《移动和离线开发人员指南》中提供了完整的详细信息，该指南是执行移动开发时本指南的重要配套。

在组件的 JavaScript 类中声明字段。在组件的模板中引用它们以动态更新内容。

字段和属性几乎是可以互换的术语。组件作者声明类中的字段。类的实例具有属性。对于组件使用者来说，字段是属性。在 Lightning Web 组件中，只有组件作者用来修饰的字段才能作为对象属性公开提供给使用者。@api

属性和属性几乎是可以互换的术语，可能会造成混淆。一般来说，在 HTML 中我们谈论属性，在 JavaScript 中我们谈论属性。

提示

如果您已经开发过 Aura 组件，那么您就熟悉术语 attribute。在 Lightning Web 组件中，最接近 Aura 属性的是 JavaScript 属性。

反应

反应性是 Lightning Web 组件框架的核心系统。该框架观察字段和属性值的更改。当它观察到变化时，它会做出反应。它重新计算模板中使用的所有表达式，并重新呈现组件，从而显示新值。

字段和属性几乎是可以互换的术语。组件作者声明类中的字段。类的实例具有属性。对于组件使用者来说，字段是属性。在 Lightning Web 组件中，只有组件作者用来修饰的字段才能作为对象属性公开提供给使用者。@api

公共属性

若要公开公共属性，请使用 修饰字段。公共属性定义组件的 API。模板中使用的公共属性是反应式的。如果模板中使用的公共属性的值发生更改，则组件将重新呈现。@api

当组件重新渲染时，将重新计算模板中使用的表达式，并执行 renderedCallback（） 生命周期钩子。

@api装饰器

提示

装饰器是一种 JavaScript 语言功能。@api装饰器是 Lightning Web 组件独有的。一个字段只能有一个修饰器。

从 导入装饰器。此代码将字段公开为公共属性。@apilwcitemName

// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  @api itemName = "New Item";
}

在模板中显示的值。itemName

<!-- todoItem.html -->
<template>
  <div class="view">
    <label>{itemName}</label>
  </div>
</template>

此 JavaScript 类和 HTML 模板定义组件，其中是命名空间。使用该组件的组件可以设置该属性。c-todo-itemcc-todo-itemitemName

注意

JavaScript 中的属性名称采用驼峰大小写，而 HTML 属性名称采用烤肉串大小写（破折号分隔）以匹配 HTML 标准。在 中，标记中的属性映射到 的 JavaScript 属性。todoApp.htmlitem-nameitemNamec-todo-item

<!-- todoApp.html -->
<template>
  <div class="listing">
    <c-todo-item item-name="Milk"></c-todo-item>
    <c-todo-item item-name="Bread"></c-todo-item>
  </div>
</template>

在其标记中使用组件的所有者组件可以通过 DOM 属性访问组件的公共属性。DOM 属性是在类中声明的公共字段。它们可以通过带有点表示法的 DOM 元素访问。在此示例中，该组件将一个公共字段声明为 ，其值可通过 （DOM 元素）实例上的 DOM 属性访问。c-todo-item@api itemNamec-todo-item

// todoApp.js
myItem = this.template.querySelector("c-todo-item").itemName;

提示

请参阅存储库中的 CompositionBasics 示例。lwc-recipes

字段、对象和数组的反应性

如果字段的值发生更改，并且该字段在模板中使用或在模板中使用的属性的 getter 中使用，则组件将重新呈现并显示新值。如果为字段分配了对象或数组，则框架会观察到对象或数组内部的一些更改，例如在分配新值时。

当组件重新渲染时，将重新计算模板中使用的表达式，并执行 renderedCallback（） 生命周期钩子。

当您在“名字”或“姓氏”字段中输入值时，组件会将其转换为大写并显示。

<!-- helloExpressions.html -->

<template>
  <lightning-card title="HelloExpressions" icon-name="custom:custom14">
    <div class="slds-m-around_medium">
      <lightning-input
        name="firstName"
        label="First Name"
        onchange={handleChange}
      ></lightning-input>
      <lightning-input
        name="lastName"
        label="Last Name"
        onchange={handleChange}
      ></lightning-input>
      <p class="slds-m-top_medium">Uppercased Full Name: {uppercasedFullName}</p>
    </div>
  </lightning-card>
</template>

组件的类定义了 和 字段。由于它们在模板 （） 中使用的属性的 getter 中使用，因此当其值更改时，组件会重新呈现。firstNamelastNameuppercasedFullName

// helloExpressions.js

import { LightningElement } from "lwc";

export default class TrackExample extends LightningElement {
  firstName = "";
  lastName = "";

  handleChange(event) {
    const field = event.target.name;
    if (field === "firstName") {
      this.firstName = event.target.value;
    } else if (field === "lastName") {
      this.lastName = event.target.value;
    }
  }

  get uppercasedFullName() {
    return `${this.firstName} ${this.lastName}`.trim().toUpperCase();
  }
}

注意

字段是反应式的。Expando 属性是在运行时添加到对象的属性，不是响应式的。

提示

请参阅存储库中的 helloExpressions 组件。lwc-recipes

反应性注意事项

尽管字段是反应式的，但 LWC 引擎以浅层方式跟踪字段值更改。通过使用 比较值标识来将新值分配给字段时，将检测到更改。此方法适用于数字或布尔值等基元类型。===

import { LightningElement } from "lwc";

export default class ReactivityExample extends LightningElement {
  bool = true;
  number = 42;
  obj = { name: "John" };

  checkMutation() {
    this.bool = false; // Mutation detected

    this.number = 42; // No mutation detected: previous value is equal to the newly assigned value
    this.number = 43; // Mutation detected

    this.obj.name = "Bob"; // No mutation detect: `obj` field value is not reassigned
    this.obj = { name: "John" }; // Mutation detected - redefining the object with the same value creates a new object
    this.obj = { ...this.obj, title: "CEO" }; // Mutation detected
  }
}

在操作复杂类型（如对象和数组）时，必须创建一个新对象并将其分配给要检测更改的字段。

为了避免在处理复杂对象时出现此类问题，请使用修饰器深入跟踪对字段值所做的更改。@track

跟踪对象和数组内部的更改

若要观察对象属性或数组元素的更改，请使用 修饰字段。@track

当字段修饰有 时，Lightning Web 组件会跟踪对以下各项内部值的更改：@track

• 使用以下方式创建的普通对象{}
• 使用[]

该框架以递归方式观察对普通对象和数组的突变，包括嵌套对象、嵌套数组以及对象和数组的混合。还处理循环引用。

但是，该框架不会观察到对复杂对象（例如继承自 、类实例、 、 或 的对象）的突变。ObjectDateSetMap

@track装饰器

观察对象的属性

要告诉框架观察对象属性的变化，请使用 修饰字段。@track

注意

如前所述，在不使用 的情况下，框架会观察到为字段分配新值的更改。如果新值不是以前的值，则组件将重新呈现。@track===

例如，让我们稍微更改代码以声明字段，该字段包含一个具有两个属性的对象，以及 .该框架会观察到将新值分配给 的更改。fullNamefirstNamelastNamefullName

fullName = { firstName: "", lastName: "" };

此代码为字段分配一个新值，以便组件重新呈现。fullName

// Component rerenders.
this.fullName = { firstName: "John", lastName: "Doe" };

但是，如果我们为对象的某个属性分配一个新值，则组件不会重新呈现，因为不会观察到这些属性。

// Component doesn't rerender.
this.fullName.firstName = "John";

该框架会观察到为字段分配新值的更改。此代码不会执行此操作，而是为对象的属性分配一个新值。fullNamefirstNamefullName

要告诉框架观察对象属性的变化，请使用 修饰字段。现在，如果我们更改任一属性，组件就会重新渲染。fullName@track

// Component rerenders.
@track fullName = { firstName : '', lastName : ''};
this.fullName.firstName = 'John';

如果属性包含对象，若要跟踪对象属性的更改，请使用 注释该属性。为了理解，让我们修改我们的示例。我们的示例初始化 and 为空字符串，这些字符串是原始值，因此组件在它们更改时会重新呈现。@trackfirstNamelastName

使用新属性重新呈现对象

仅当更新了在上一个渲染周期中访问的属性时，组件才会重新渲染，即使对象使用 批注了 。这样可以防止组件过度重新渲染，@track

考虑这个跟踪对象和一个打印对象属性的 getter。

@track obj = {value1: 'Hello'};

get words() {
    return Object.entries(this.obj)
              .map(([key, value]) => ({key, value}));
  }

在第一个渲染周期中，框架会记录所访问的内容。任何不影响的突变都会被忽略，因为它不会影响呈现的内容。因此，更改 会触发重新呈现，但向 添加新属性或更改不会触发重新呈现。obj.value1objvalue1value1objvalue2

// Component rerenders.
setValue1(e) {
  this.obj.value1 = 'Hello World';
}

// Component doesn’t rerender.
setValue2(e) {
  this.obj.value2 = 'Hello LWC';
}

若要在添加新属性时重新呈现组件，请将该对象分配给具有这两个值的新对象。

setValue2(e) {
  this.obj = {
    ...this.obj,
      value2: 'Hello LWC'
  };
}

观察数组的元素

另一个用例是告诉框架观察数组元素的变化。@track

如果不使用 ，框架会观察到为字段分配新值的更改。@track

arr = ["a", "b"];

当您将新值分配给 时，组件将重新呈现。arr

// Component rerenders.
this.arr = ["x", "y", "z"];

但是，如果我们在数组中更新或添加元素，则该组件不会重新渲染。

// Component doesn’t rerender.
this.arr[0] = "x";
this.arr.push("c");

若要告诉框架观察数组元素的变化，请使用 此外，框架不会自动将数组转换为字符串以更新数组元素。要返回更新的字符串，请使用 getter 将数组的元素转换为字符串。arr@trackjoin()

@track arr = ['a','b'];

get computedArray() { return this.arr.join(','); }

update() {
  this.arr[0] = 'x';
  this.arr.push('c');
}

观察复杂物体

让我们看一个字段为 的组件，其类型为 。该模板有几个按钮，用于更改 的内部状态。此示例突出显示了创建对象，因为它不是普通的 JavaScript 对象，LWC 引擎不会观察到内部状态突变，即使代码使用 .xDatexnew Date()@track

// trackDate.js
import { LightningElement, track } from "lwc";
export default class TrackDate extends LightningElement {
  @track x = new Date();

  initDate() {
    this.x = new Date();
  }

  updateDate() {
    this.x.setHours(7); // No mutation detected
  }
}

与前面的示例类似，该模板有几个按钮可以更改 的内部状态。x

<!-- trackDate.html -->
<template>
  <p>Date: {x}</p>

  <button onclick={initDate}>Init</button>
  <button onclick={updateDate}>Update</button>
</template>

单击“初始化”按钮时，将观察到更改并重新呈现模板。Lightning Web Components 观察到它指向一个新对象。但是，单击“更新”时，不会重新呈现模板。Lightning Web 组件不会观察到对象值的变化。xDateDate

若要确保在值更改时重新呈现模板，请克隆现有日期并更新其值。

updateDate() {
  const cloned = new Date(this.x.getTime());
  cloned.setHours(7);

  // Assign the new date instance to rerender the component.
  this.x = cloned;
}

注意

将属性设置为无法跟踪的值时，将记录警告。如果尝试调试组件在更改时未重新呈现的方案，请查看浏览器控制台。在我们的示例中，浏览器控制台会记录以下有用的警告：

Property "x" of [object:vm TrackDate] is set to a non-trackable object, which means changes into that object cannot be observed.

属性和属性名称

JavaScript 中的属性名称采用驼峰大小写，而 HTML 属性名称采用烤肉串大小写（破折号分隔）以匹配 HTML 标准。

例如，名为 的 JavaScript 属性映射到名为 的 HTML 属性。itemNameitem-name

// child.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  @api itemName;
}

<!-- parent.html -->
<template>
  <c-child item-name="Child item"></c-child>
</template>

JavaScript 属性名称

不要以这些字符开头属性名称。

• on（例如，onClick)
• aria（例如，ariaDescribedby)
• data（例如，dataProperty)

不要将这些保留字用于属性名称。

• slot
• part
• is

HTML 属性名称

模板中的 HTML 属性不能包含大写字符。属性名称可以以以下字母开头：

• 小写字母字符
• 下划线 （_)
• 美元符号 （$)
• 可选连字符后跟字母字符（-a)

属性名称可以包含重复的下划线 （） 或下划线后跟连字符 （）。___-

如果连字符不是属性名称中的第一个字符，则允许使用连字符后跟下划线 （）。例如，这些是有效的属性名称：-_

• _myattribute
• $myattribute
• my_-attribute

如果 JavaScript 属性以大写字符开头，并且希望通过 HTML 属性进行设置，则必须使用特殊语法。属性名称的大写字符为小写，并以连字符 为前缀。前导连字符告诉引擎，属性名称中的第一个字母字符在 JavaScript 类中是用前导大写字符声明的。例如，JavaScript 属性对应于 HTML 属性。-upper@api Upperupper

在 JavaScript 中访问 HTML 全局属性

不建议使用 HTML 全局属性，这些属性类似于所有 HTML 元素，并且是所有 HTML 元素通用的属性。如果确实使用全局 HTML 属性，请使用 .classtitle@api

某些 HTML 全局属性不遵循 Lightning Web 组件驼峰大小写和烤肉串大小写约定。如果在 JavaScript 中为这些 HTML 全局属性之一创建 getter 或 setter，请使用此列表中的大小写。

例如，要访问 JavaScript 中的 HTML 属性，请使用 .maxlengthtextareamaxLength

此外，要从 JavaScript 访问 HTML 属性，请使用 .forhtmlFor

在 JavaScript 中访问 ARIA 属性

ARIA 属性支持辅助技术。要在 JavaScript 中访问这些属性，请使用驼峰大小写。例如，要访问 ，请使用 .要访问 ，请使用 .aria-checkedariaCheckedaria-errormessageariaErrorMessage

Web API 属性

Lightning Web 组件反映了许多 Web API 的属性。

元素

Lightning Web 组件反映了 Element 界面的这些属性。

children, classList, className, firstElementChild, getAttribute, getAttributeNS, getBoundingClientRect, getElementsByClassName, getElementsByTagName, hasAttribute, id, lastElementChild, querySelector, querySelectorAll, removeAttribute, removeAttributeNS, setAttributeNS, setAttribute, shadowRoot, slot

请参阅 Shadow DOM、访问组件拥有的元素以及将标记传递到插槽中。

在 Salesforce 组织中启用 Lightning Web Security 后，setAttributeNS、setAttribute 和 shadowRoot 会因失真而修改。

事件目标

Lightning Web 组件反映了 EventTarget 接口的这些属性。

addEventListener, dispatchEvent, removeEventListener

请参阅与事件通信。

HTMLElement

Lightning Web 组件反映了 HTMLElement 接口的这些属性。

accessKeyLabel, contentEditable, dataset, dir, hidden, isContentEditable, lang, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, title

在 Salesforce 组织中启用 Lightning Web Security 时，数据集会因失真而修改。

节点

Lightning Web 组件反映了 Node 界面的这些属性。

childNodes, firstChild, isConnected, lastChild

请参见在 DOM 中插入或删除组件时运行代码。

WAI-ARIA 状态和属性

Lightning Web 组件反映了这些 WAI-ARIA 状态和属性。

ariaActiveDescendant, ariaAtomic, ariaAutoComplete, ariaBusy, ariaChecked, ariaColCount, ariaColIndex, ariaColSpan, ariaControls, ariaCurrent, ariaDescribedBy, ariaDetails, ariaDisabled, ariaErrorMessage, ariaExpanded, ariaFlowTo, ariaHasPopup, ariaHidden, ariaInvalid, ariaKeyShortcuts, ariaLabel, ariaLabelledBy, ariaLevel, ariaLive, ariaModal, ariaMultiLine, ariaMultiSelectable, ariaOrientation, ariaOwns, ariaPlaceholder, ariaPosInSet, ariaPressed, ariaReadOnly, ariaRelevant, ariaRequired, ariaRoleDescription, ariaRowCount, ariaRowIndex, ariaRowSpan, ariaSelected, ariaSetSize, ariaSort, ariaValueMax, ariaValueMin, ariaValueNow, ariaValueText

请参阅组件可访问性。

使用 getter 和 setter 修改数据

若要在每次设置公共属性时执行逻辑，请编写自定义 setter。

如果为公共属性编写 setter，则还必须编写 getter。用 注释 getter 或 setter，但不能同时注释两者。最佳做法是注释 getter。@api

若要将属性值保存在 getter 和 setter 中，请使用字段。此示例使用该属性，该属性以下划线为前缀，以指示该属性是私有的。_uppercaseItemName

此示例组件将字符串转换为大写。<c-todo-item>

<!-- todoItem.html -->
<template> {itemName} </template>

属性值通过 getter 提供给模板。

// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  _uppercaseItemName;

  @api
  get itemName() {
    return this._uppercaseItemName;
  }

  set itemName(value) {
    this._uppercaseItemName = value.toUpperCase();
  }
}

提示

有关使用 getter 和 setter 的另一个示例，请参阅 lwc-recipes 示例存储库中的 和 组件。apiSetterGettertodoList

Boolean 属性

标准 HTML 元素上的布尔属性是通过将属性添加到元素来设置的。如果缺少该属性，则该属性默认为 。因此，属性的默认值始终为 。Lightning Web 组件对布尔属性使用相同的原则。truefalsefalse

静态设置属性

始终将布尔公共属性的默认值设置为 。如果将默认值设置为 instead in ，则无法静态地将值切换为 in markup。falsetruebool.jsfalse

// bool.js
import { LightningElement, api } from "lwc";

export default class Bool extends LightningElement {
  @api show = false;
}

下面是 HTML 文件。

<!-- bool.html -->
<template>
  <p>show value: {show}</p>
</template>

父组件包括 ，它显示默认值 ，因为该属性未添加到 。c-boolfalseshow<c-bool>

重要

在标记中指定的唯一方法是省略 boolean 属性。在标记中设置的计算结果为 。falseshow="false"true

<!-- parent.html -->
<template>
  <c-bool></c-bool>
</template>

若要将属性设置为 ，请将具有空值的属性添加到标记中。此版本的 显示属性的值。showtrueshowc-parenttrueshow

<!-- parent.html -->
<template>
  <c-bool show></c-bool>
</template>

的值是，但属性不会反映在呈现的 HTML 中，除非您通过调用 来显式反映该属性。请参阅将 JavaScript 属性反映为 HTML 属性。showtrueshowsetAttribute

注意

当布尔属性的值为 时，呈现的 HTML 为 。true<my-component my-attribute>

动态设置属性

若要动态切换值，请从父组件传递动态计算值。例如：

<!-- parent.html -->
<template>
  <c-bool show={computedValue}></c-bool>
</template>

使用 JavaScript getter in 返回 的值。parent.js{computedValue}

将 JavaScript 属性反映为 HTML 属性

您可以控制公共 JavaScript 属性是否在 Lightning Web 组件的渲染 HTML 中显示为属性。在创建可访问的组件时，允许属性显示为属性尤为重要，因为屏幕阅读器和其他辅助技术使用 HTML 属性。

默认情况下，所有 HTML 属性都是响应式的。当组件 HTML 中的属性值发生更改时，将重新呈现该组件。

当您通过将某个属性公开为公共属性来控制该属性时，默认情况下，该属性将不再显示在 HTML 输出中。若要将值作为属性传递到呈现的 HTML（以反映属性），请为属性定义 getter 和 setter 并调用该方法。setAttribute()

您还可以在 setter 中执行操作。使用字段保存计算值。

此示例公开为公共属性。它将标题转换为大写，并使用该属性来保存标题的计算值。setter 调用以将属性的值反映到 HTML 属性。title_privateTitlesetAttribute()

// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  _privateTitle;

  @api
  get title() {
    return this._privateTitle;
  }

  set title(value) {
    this._privateTitle = value.toUpperCase();
    this.setAttribute("title", this._privateTitle);
  }
}

/* parent.html */
<template>
  <c-my-component title="Hover Over the Component to See Me"></c-my-component>
</template>

/* Generated HTML */
<c-my-component title="HOVER OVER THE COMPONENT TO SEE ME">
  <div>Reflecting Attributes Example</div>
</c-my-component>

要确保您了解 JavaScript 属性如何反映到 HTML 属性，请查看不调用 .生成的 HTML 不包含该属性。setAttribute()title

// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  _privateTitle;

  @api
  get title() {
    return this._privateTitle;
  }

  set title(value) {
    this._privateTitle = value.toUpperCase();
    // this.setAttribute('title', this._privateTitle);
  }
}

/* parent.html */
<template>
  <c-my-component title="Hover Over the Component to See Me"></c-my-component>
</template>

/* Generated HTML */
<c-my-component>
  <div>Reflecting Attributes Example</div>
</c-my-component>

在设置值之前，请检查使用者是否已经设置了该值。

// myComponent.js
import { LightningElement } from "lwc";

export default class MyComponent extends LightningElement {
  connectedCallback() {
    const tabindex = this.getAttribute("tabindex");

    // Set the tabindex to 0 if it hasn’t been set by the consumer.
    if (!tabindex) {
      this.setAttribute("tabindex", "0");
    }
  }
}

在此标记中设置 using 结果。tabindexthis.setAttribute()

<c-my-component tabindex="0"></c-my-component>

要设置这些属性，请使用 .setAttribute()

• for
• aria-activedescendant
• aria-controls
• aria-describedby
• aria-details
• aria-errormessage
• aria-flowto
• aria-labelledby
• aria-owns

要从呈现的 HTML 中隐藏 HTML 属性，请调用 .removeAttribute()

管理 Getter 中的属性依赖关系

HTML 中的属性变成了 JavaScript 中的属性赋值。在这两种情况下，都不能保证分配顺序。要检查是否存在其他属性，请使用 getter。

在模板中使用 getter 引用。不要使用 getter，也不要使用依赖于其他属性中的值的 setter。@api@api@api

假设我们有一个数据表组件，该组件在所选行上显示复选标记。我们有两个独立的属性和 ，它们依赖于另一个属性。rowsselectedRows

<template>
  <c-datatable selected-rows="1,2" rows="1,2,3,4"> </c-datatable>
</template>

由于无法保证接收属性的顺序，因此请使用 getter 来检查依赖关系。

export default class Datatable extends LightningElement {
  @track state = {};

  @api
  get rows() {
    return this.state.rows;
  }

  set rows(value) {
    this.state.rows = value;

    // Check to see if the rows have
    // been marked as selected.
    if (this.state.selectedRows && !this.selectedRowsSet) {
      this.markSelectedRows();
      this.selectedRowsSet = true;
    }
  }

  @api
  set selectedRows(value) {
    this.state.selectedRows = value;

    // If rows haven’t been set,
    // then we can't mark anything
    // as selected.
    if (!this.state.rows) {
      this.selectedRowsSet = false;
      return;
    }

    this.markSelectedRows();
  }

  get selectedRows() {
    return this.state.selectedRows;
  }

  markSelectedRows() {
    // Mark selected rows.
  }
}

使用 getter 和 setter 可确保公共 API 协定易于执行。组件不应更改用 批注的属性的值。@api

如果某些内容在设定的时间依赖于该值，则规范化 setter 中的数据，例如，以编程方式将 CSS 类附加到元素上。返回 getter 中的原始值。规范化也可以在 getter 中完成，这样即使使用者没有设置任何内容，模板也可以访问值。

@track state = {
    selected : false
};

privateSelected = 'false';

@api
get selected() {
    return this.privateSelected;
}
set selected(value) {
    this.privateSelected = value;
    this.state.selected = normalizeBoolean(value)
}

您可以在另一个组件的主体中添加组件。组合使您能够从更简单的构建块组件构建复杂的组件。

注意

允许继承，但不建议这样做，因为组合通常更有效。若要在组件之间共享逻辑，请使用仅包含逻辑的模块。请参阅其他 JavaScript 文件。如果您选择使用继承，请注意，它不适用于 Lightning Locker 下的命名空间。您必须启用 LWS 才能跨命名空间使用继承。不能在任一安全体系结构中扩展命名空间。lightning

Compose 组件

使用一组较小的组件组合应用和组件非常有用，以使代码更易于重用和维护。命名空间包含许多基本组件，例如 ，您可以使用这些组件来构建组件。lightninglightning-button

让我们看一个由组件组成的简单应用程序。标记是人为的，因为我们想说明所有者和容器的概念。在实际应用中，实例的数量是可变的，并在循环中动态填充。c-todo-itemfor:each

<!-- todoApp.html -->
<template>
  <c-todo-wrapper>
    <c-todo-item item-name="Milk"></c-todo-item>
    <c-todo-item item-name="Bread"></c-todo-item>
  </c-todo-wrapper>
  <template></template
></template>

所有者

所有者是拥有模板的组件。在此示例中，所有者是组件。所有者控制其包含的所有组合组件。所有者可以：c-todo-app

• 在组合组件上设置公共属性
• 在组合组件上调用方法
• 侦听组合组件触发的任何事件

容器

容器包含其他组件，但其本身包含在所有者组件中。在此示例中，是一个容器。容器不如所有者强大。容器可以：c-todo-wrapper

• 读取但不能更改包含组件中的公共属性
• 在组合组件上调用方法
• 侦听它所包含的组件冒泡的一些（但不一定是全部）事件。

父母和孩子

当一个组件包含另一个组件时，另一个组件又可以包含其他组件，我们有一个包含层次结构。在文档中，我们有时会讨论父组件和子组件。父组件包含子组件。父组件可以是所有者，也可以是容器。

设置子组件的属性

若要向下通信包含层次结构，所有者可以在子组件上设置属性。HTML 中的属性变成了 JavaScript 中的属性赋值。

父组件可以在子组件上设置基元值，如字符串或数字。但是，传递给组件的对象或数组等非原始值是只读的，您必须进行浅拷贝才能修改任何嵌套值。

在子组件上设置基元值

让我们看一下所有者 ， 如何在 的两个实例上设置公共属性。c-todo-appc-todo-item

看。修饰器将字段公开为公共属性。todoItem.js@apiitemName

// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  @api itemName;
}

若要设置公共属性，请在每个组件上设置该属性。itemNametodoApp.htmlitem-namec-todo-item

<!-- todoApp.html -->
<template>
  <c-todo-item item-name="Milk"></c-todo-item>
  <c-todo-item item-name="Bread"></c-todo-item>
</template>

JavaScript 中的属性名称采用驼峰大小写，而 HTML 属性名称采用烤肉串大小写（破折号分隔）以匹配 HTML 标准。在 中，标记中的属性映射到 的 JavaScript 属性。todoApp.htmlitem-nameitemNamec-todo-item

提示

此示例使用 和 的静态值，但实际组件通常会对所有者的 JavaScript 文件 .MilkBreadfor:eachtodoApp.js

有关稍微复杂的示例，请参阅 lwc-recipes 存储库中的组合基本配方。

您还可以在 lwc.dev 的 Playground 中使用类似的代码，这是 Lightning Web 组件：开源开发人员网站。

在子组件上设置非基元值

传递给组件的非基元值（如对象或数组）是只读的。若要更改数据，请创建要更改的对象的浅拷贝。

让我们看一个父组件，它将对象传递给子组件，然后让子组件更新其值。

<!-- parent.html -->
<template>
  <div>Parent: {serializedObj}</div>
  <c-child obj="{obj}"></c-child>
</template>

在 JavaScript 中设置值。

// parent.js
import { LightningElement } from "lwc";

export default class Parent extends LightningElement {
  obj = {
    msg: "hello",
  };

  get serializedObj() {
    return JSON.stringify(this.obj);
  }
}

反应式对象从父组件传递到子组件。子组件显示带有两个按钮的序列化对象字符串，这两个按钮通过更新原始对象或其浅表副本来更新对象值。obj

<!-- child.html -->
<template>
  <div>Child: {serializedObj}</div>

  <button onclick="{updateOriginal}">Update original</button>
  <button onclick="{updateShallow}">Update shallow</button>
</template>

该组件无法更改对象或数组的内容。当您尝试更新原始对象值时，会引发错误，因为子组件正在尝试改变对象上的属性。Uncaught Error: Invalid mutation: Cannot set "msg" on "[object Object]". "[object Object]" is read-only.

// child.js
import { LightningElement, api } from "lwc";

export default class Child extends LightningElement {
  @api obj;

  get serializedObj() {
    return JSON.stringify(this.obj);
  }

  updateOriginal() {
    this.obj.msg += "!!!"; // throws an invalid mutation error
  }

  updateShallow() {
    this.obj = { ...this.obj, msg: this.obj.msg + "!" };
  }
}

具有来自父组件的引用的非基元值（如 所示）包装在代理中，无法修改。但是，您可以通过创建非基元的浅拷贝来修改其内容。this.obj

当抛出无效的突变错误时，值赋值仅更新子组件上的值。父组件上的值不会更新。this.obj.msgthis.objupdateShallow(){serializedObj}{serializedObj}

数据流

为了防止代码复杂性和意外的副作用，数据应该沿一个方向流动，从父级流向子级。

当组件修饰字段以将其公开为公共属性时，它应该仅在初始化字段时设置该值。初始化字段后，只有所有者组件才能设置该值。组件应将传递给它的值视为只读。@api

若要触发所有者组件提供的属性值的突变，子组件可以向父组件发送事件。如果父级拥有数据，则父级可以更改属性值，该属性值通过单向数据绑定向下传播到子组件。

传递给组件的对象是只读的

传递给组件的非基元值（如对象或数组）是只读的。该组件无法更改对象或数组的内容。如果组件尝试更改内容，您会在浏览器控制台中看到错误：Uncaught Error: Invalid mutation: Cannot set "msg" on "[object Object]". "[object Object]" is read-only.

若要更改数据，请创建要更改的对象的浅拷贝。让我们看一下更新对象值的组件。

<!-- myCmp.html -->
<template>
  <p>{serializedObj}</p>
  <button onclick="{updateShallowCopy}">Update</button>
</template>

创建对象的浅拷贝，该拷贝仅复制顶级属性。不会复制嵌套对象的值。在此示例中，更新为单击按钮时。{"msg":"hello"}{"msg":"hello!"}

// myCmp.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  obj = {
    msg: "hello",
  };

  get serializedObj() {
    return JSON.stringify(this.obj);
  }

  updateShallowCopy() {
    this.obj = { ...this.obj, msg: this.obj.msg + "!" };
  }
}

也可以使用 重新分配对象的值。该组件拥有该字段，并且可以为该字段分配一个新值。相反，如果组件尝试使用 更改对象上的嵌套值，则会在 Web 控制台中收到无效的突变错误。this.obj = { msg: 'My new message' }myCmpobjthis.obj.msg = 'new value'

同样，具有来自父组件的引用的非基元值包装在代理中，并且无法修改。请参见设置子组件的属性。

若要触发所有者组件提供的属性值的突变，组件应向所有者发送事件。

对公共属性使用基元值

建议对属性使用基元数据类型，而不是使用对象数据类型。在更高级别的组件中对复杂的数据结构进行切片，并将基元值传递给组件后代。

最好使用基元值有几个原因。

• 基元值需要明确定义数据形状的特定属性。接受对象或数组需要文档来指定形状。如果对象形状发生变化，使用者就会中断。@api
• 标准 HTML 元素仅接受属性的基元值。当标准 HTML 元素需要复杂形状时，它使用子组件。例如，元素使用 和 元素。只能在 HTML 中定义基元类型。例如，在 HTML 中不是值，而是在 Lightning Web 组件中。tabletrtd<table data={...}>

在子组件上调用方法

若要公开公共方法，请使用 .公共方法是组件 API 的一部分。若要在包含层次结构中向下通信，所有者和父组件可以在子组件上调用 JavaScript 方法。@api

注意

若要在包含层次结构中向上通信，请在子组件中触发事件，并在所有者或容器组件中处理该事件。请参阅与事件通信。

查看 lwc-recipes 存储库中的组件（以前命名为 ），该组件在其子组件上调用方法。apiMethodapiFunctionclock

定义方法

此示例通过向组件中添加装饰器来公开属性和 和方法的 getter。包含的父组件可以读取属性并调用方法。下面是 JavaScript 文件。isPlayingplay()pause()c-video-player@apic-video-player

// videoPlayer.js
import { LightningElement, api } from "lwc";

export default class VideoPlayer extends LightningElement {
  @api videoUrl;

  @api
  get isPlaying() {
    const player = this.template.querySelector("video");
    return player !== null && player.paused === false;
  }

  @api
  play() {
    const player = this.template.querySelector("video");
    // the player might not be in the DOM just yet
    if (player) {
      player.play();
    }
  }

  @api
  pause() {
    const player = this.template.querySelector("video");
    if (player) {
      // the player might not be in the DOM just yet
      player.pause();
    }
  }

  // private getter for computed value
  get videoType() {
    return "video/" + this.videoUrl.split(".").pop();
  }
}

videoUrl是公共财产。装饰器可用于在组件上定义公共属性和公共 JavaScript 方法。公共属性是组件公共 API 的另一部分。@api

注意

若要访问模板拥有的元素，代码将使用 template 属性。

现在，让我们看一下定义 video 元素的 HTML 文件。

<!-- videoPlayer.html -->
<template>
  <div class="fancy-border">
    <video autoplay>
      <source src={videoUrl} type={videoType} />
    </video>
  </div>
</template>

在实际组件中，通常具有播放或暂停视频本身的控件。为了说明公共 API 的设计，此示例中控件位于调用公共方法的父组件中。c-video-player

调用方法

该组件包含并具有用于调用 中的 和 方法的按钮。下面是 HTML。c-method-callerc-video-playerplay()pause()c-video-player

<!-- methodCaller.html -->
<template>
  <div>
    <c-video-player video-url={video}></c-video-player>
    <button onclick={handlePlay}>Play</button>
    <button onclick={handlePause}>Pause</button>
  </div>
</template>

单击中的按钮将在我们连接 中的 和 方法后播放或暂停视频。c-method-callerc-video-playerhandlePlayhandlePausec-method-caller

下面是 的 JavaScript 文件。c-method-caller

// methodCaller.js
import { LightningElement } from "lwc";

export default class MethodCaller extends LightningElement {
  video = "https://www.w3schools.com/tags/movie.mp4";

  handlePlay() {
    this.template.querySelector("c-video-player").play();
  }

  handlePause() {
    this.template.querySelector("c-video-player").pause();
  }
}

中的函数调用元素中的方法。 返回 中的元素。该调用可用于访问子组件，以便可以在组件上调用方法。handlePlay()c-method-callerplay()c-video-playerthis.template.querySelector('c-video-player')c-video-playermethodCaller.htmlthis.template.querySelector()

中的函数调用元素中的方法。handlePause()c-method-callerpause()c-video-player

返回值

若要从 JavaScript 方法返回值，请使用该语句。例如，请参见中的方法。returnisPlaying()c-video-player

@api get isPlaying() {
    const player = this.template.querySelector('video');
    return player !== null && player.paused === false;
}

方法参数

若要将数据传递给 JavaScript 方法，请为该方法定义一个或多个参数。例如，您可以定义采用控制视频播放速度的参数的方法。play()speed

@api play(speed) { … }

查询选择器

该方法是一个标准的 DOM API，它返回与选择器匹配的第一个元素。querySelector()

如果要遍历数组，请考虑向元素添加一些其他属性，例如 或 value，并使用它来选择所需的元素。classdata-*

该方法返回一个 DOM 元素数组。querySelectorAll()

注意

不要将 传递给查询方法，例如 。呈现 HTML 模板时，可以将值转换为全局唯一值。如果在 JavaScript 中使用选择器，则它与转换后的 .idquerySelectorididid

有关详细信息，请参阅 developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll 和 developer.mozilla.org/en-US/docs/Web/API/Element/querySelector。

子组件上的 Spread 属性

使用指令将对象中的一组属性传递给子组件。 还使元素能够接受在运行时绑定为属性的对象。lwc:spreadlwc:spread

提示

lwc-recipes 存储库有一个演示指令的组件。apiSpreadlwc:spread

该指令接受一个对象。lwc:spread

<!-- app.html -->
<template>
  <c-child lwc:spread={childProps}></c-child>
</template>

使用具有键值对的对象，其中键是属性名称。

// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  childProps = { name: "James Smith", country: "USA" };
}

在子组件中，使用模板中的属性。

<!-- child.html -->
<template>
  <p>Name: {name}</p>
  <p>Country : {country}</p>
</template>

使用修饰器向父组件公开属性。@api

// child.js
import { LightningElement, api } from "lwc";

export default class Child extends LightningElement {
  @api name;
  @api country;
}

lwc:spread始终最后应用，因此它会覆盖模板中直接声明的任何属性。一个指令只能使用一个实例。lwc:spread

<!-- app.html -->
<template>
  <c-child name="lwc" lwc:spread={childProps}></c-child>
</template>

在此示例中，即使父组件传入，也要传递 。最终，子组件将采用该名称。c-childnameLightning Web Componentsname="lwc""lwc"

// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  childProps = { name: "Lightning Web Components" };
}

lwc:spread不将组件绑定到模板中定义的事件处理程序。例如，可以在对象中传入处理程序作为属性名称。onclick

<!-- app.html -->
<template>
  <c-child lwc:spread={simpleProps}></c-child>
</template>

在这里，作为 .单击 c-child 元素时，将替换为 。c-childnameLWCspreadClick()nameLightning Web Components

// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  simpleProps = { name: "LWC", onclick: this.spreadClick.bind(this) };
  spreadClick() {
    this.simpleProps = { name: "Lightning Web Components" };
  }
}

虽然我们没有包含在 中，但元素包含之前通过对象分配给它的元素。onclickspreadClick()onclicksimpleProps

在子组件上反映 HTML 属性

大多数 HTML 属性都反映为属性。例如，属性反映为属性。classclassName

假设您将属性传递给子组件。

<!-- app.html -->
<template>
  <c-child lwc:spread={spanProps}></c-child>
</template>

因此，该属性会导致元素呈现为 。spanProps<c-child class="spanclass" id="mySpan"></c-child>

// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  spanProps = { className: "spanclass", id: "myspan" };
}

将标记传递到插槽中

将槽添加到组件的 HTML 文件中，以便父组件可以将标记传递到组件中。一个组件可以有零个或多个插槽。

插槽 （） 是父组件传递到组件主体中的标记的占位符。<slot></slot>

重要

您无法将 Aura 组件传递到插槽中。如果将 Lightning Web 组件嵌套在 Aura 组件中，则也无法将其传递到插槽中。

未命名插槽

此示例有一个未命名的插槽。未命名的插槽使用该元素作为父组件传递到 主体中的任何标记的占位符。<slot>c-slot-demo

<!-- slotDemo.html -->
<template>
  <h1>Add content to slot</h1>
  <div>
    <slot></slot>
  </div>
</template>

下面是使用 .c-slot-demo

<!-- slotWrapper.html -->
<template>
  <c-slot-demo>
    <p>content from parent</p>
  </c-slot-demo>
</template>

呈现时，未命名的插槽将替换为传递到 正文中的标记。下面是 的渲染输出。c-slot-democ-slot-democ-slot-wrapper

<h1>Add content to slot</h1>
<div>
  <slot>
    <p>content from parent</p>
  </slot>
</div>

如果组件具有多个未命名槽，则传递到组件主体中的标记将插入到所有未命名槽中。但是，一个组件通常有零个或一个未命名的插槽。

命名插槽

此示例组件有两个命名槽和一个未命名槽。

<!-- namedSlots.html -->
<template>
  <p>First Name: <slot name="firstName">Default first name</slot></p>
  <p>Last Name: <slot name="lastName">Default last name</slot></p>
  <p>Description: <slot>Default description</slot></p>
</template>

您可以为 HTML 元素的属性设置动态值。在这里，该元素的属性设置为变量 。slot<span>slotdynamicName

<template>
  <c-item>
    <span slot={dynamicName}></span>
  </c-item>
</template>

传递到属性中的动态值被强制转换为字符串。例如，如果将数字 4 传递给属性，则该属性将转换为字符串 。如果传入无法转换为字符串的数据类型（如 ），则会引发 TypeError。slot"4"Symbol()

此更改不会影响元素的属性。例如，您仍然必须将静态字符串传递到元素的属性中。<slot>name<slot>

<template>
  <slot name="”staticName”"> </slot>
</template>

下面是使用 .c-named-slots

<!-- slotsWrapper.html -->
<template>
  <c-named-slots>
    <span slot="firstName">Willy</span>
    <span slot="lastName">Wonka</span>
    <span>Chocolatier</span>
  </c-named-slots>
</template>

该组件通过：c-slots-wrapper

• Willy进入插槽firstName
• Wonka进入插槽lastName
• Chocolatier进入未命名的插槽

下面是呈现的输出。

<c-named-slots>
  <p>
    First Name:
    <slot name="firstName"><span slot="firstName">Willy</span></slot>
  </p>
  <p>
    Last Name:
    <slot name="lastName"><span slot="lastName">Wonka</span></slot>
  </p>
  <p>
    Description:
    <slot><span>Chocolatier</span></slot>
  </p>
</c-named-slots>

通过插槽传递的访问元素

该元素是组件影子树的一部分。要访问其影子树中的元素，组件将调用 和 .<slot></slot>this.template.querySelector()this.template.querySelectorAll()

但是，传递到插槽中的 DOM 元素不是组件影子树的一部分。要访问通过插槽传递的元素，组件将调用 和 .this.querySelector()this.querySelectorAll()

此示例演示如何将 DOM 元素从子组件的上下文传递给子组件。为 和 提供选择器名称，例如元素。this.querySelector()this.querySelectorAll()

// namedSlots.js
import { LightningElement } from "lwc";

export default class NamedSlots extends LightningElement {
  renderedCallback() {
    this.querySelector("span"); // <span>push the green button.</span>
    this.querySelectorAll("span"); // [<span>push the green button</span>, <span>push the red button</span>]
  }
}

在此示例中，接受元素 .querySelectorspan

注意

不要将 传递给查询方法，例如 。呈现 HTML 模板时，可以将值转换为全局唯一值。如果在 JavaScript 中使用选择器，则它与转换后的 .idquerySelectorididid

有条件地渲染插槽

要有条件地呈现插槽，请使用 、 和/或指令将插槽嵌套在标记中。<template>lwc:iflwc:elselwc:elseif

<template>
  <template lwc:if={expression}>
    <div class="my-class">
      <slot></slot>
    </div>
  </template>
  <template lwc:else>
    <slot></slot>
  </template>
</template>

模板编译器将条件指令视为有效的用例，并且知道不会呈现两次。<slot>

如果使用 legacy 和 指令，编译器会警告你重复的插槽，因为不清楚是否只会呈现一次。例如，getter 每次的返回值都可能不一致。if:trueif:false<slot>expression

在 slotchange 上运行代码

所有元素都支持该事件。当元素中节点的直接子节点发生更改时，将触发该事件。例如，当追加或删除新内容时，会发生这种情况。只有元素支持此事件。<slot>slotchangeslotchange<slot><slot>

元素的子元素中的更改不会触发事件。<slot>slotchange

在此示例中，元素处理事件。<slot>slotchange

<!-- container.html -->
<template>
  <slot onslotchange={handleSlotChange}></slot>
</template>

// container.js
handleSlotChange (e) {
   console.log("New slotted content has been added or removed!");
}

元件被传递到插槽中。c-child

<c-container>
  <c-child></c-child>
  <template lwc:if={addOneMore}>
    <c-child></c-child>
  </template>
</c-container>

如果该标志设置为 True，则控制台将在首次呈现组件时打印。addOneMore

<!-- child.html -->
<template>
  <button onclick={handleClick}>Toggle Footer</button>
  <template lwc:if={showFooter}>
    <footer>Footer content</footer>
  </template>
</template>

即使为 true 并且追加了页脚元素，也不会触发该事件。slotchangeshowFooter

使用插槽与数据组合组件

创建包含其他组件的组件时，请考虑组件层次结构的生命周期，使用带有槽的声明性方法，或数据驱动方法，其中子组件对其父组件的数据更改做出反应。

以声明方式构建组件的常见模式如下所示。

<c-parent>
  <c-custom-child></c-custom-child>
  <c-custom-child></c-custom-child>
</c-parent>

此示例具有使用元素的组件。尽管对使用者来说很方便，但您必须管理通过元素传递的内容的生命周期。c-parentslotslot

有几种方法可以管理传递到槽中的内容。

• 使用 slotchange 事件。这是推荐的方法。 通过 DOM 向上冒泡，但不会越过阴影边界，从而使包含插槽的父组件能够对其做出反应。slotchange
• 使用自定义事件将子组件的更改通知父组件，这使您能够将要与之交互的组件上的方法设为私有。我们不再建议使用此方法，因为我们正在逐步迁移组件以使用本机影子，这会强制组件使用该事件。slotchange

将 slotchange 事件与插槽一起使用

使用带有槽的事件，可以管理父组件和子组件之间内容的生命周期。此模式的一个示例是具有子组件的基本组件。slotchangeslotlightning-button-grouplightning-button

<lightning-button-group>
  <lightning-button label="Refresh"></lightning-button>
  <lightning-button label="Edit"></lightning-button>
  <lightning-button label="Save"></lightning-button>
</lightning-button-group>

父组件包含一个带有事件的元素，用于管理传入内容的生命周期。lightning-button-groupslotonslotchange

<!-- buttonGroup.html -->
<template>
  <slot onslotchange={handleSlotChange}></slot>
</template>

注意

基本组件示例仅用于演示目的。基本组件内部结构可能会发生变化。我们记录了对组件功能和行为的更改，但不记录对其内部的更改。有关基本组件的公共属性和方法，请参阅组件参考。

当槽的内容发生更改时，处理程序将处理对槽元素的更新。在这种情况下，父组件根据子组件在组中的显示顺序（第一个、中间、最后一个，或者它是否是组中的唯一按钮）来确定子组件上的 CSS 类。slotchangelightning-button-grouplightning-button

// buttonGroup.js
handleSlotChange(event) {
  const slot = event.target;
  const children = slot.assignedElements() || [];

  // Loop through each child and
  // set the order value based on position in the group
  this.updateGroupOrder(children); }

使用 getter 修改按钮类。

<!-- button.html -->
<template>
  <button class={computedButtonClass} ...>{label}</button>
</template>

// button.js
get computedButtonClass() {
    return classSet('slds-button')
    .add({
        // Other button classes here
        'slds-button_first': this._order === 'first',
        'slds-button_middle': this._order === 'middle',
        'slds-button_last': this._order === 'last'
    })
    .toString();
}

触发寄存器事件，以便组件可以注册组件。lightning-button-grouplightning-button

// button.js
connectedCallback() {
  this._connected = true;
    const privatebuttonregister = new CustomEvent('privatebuttonregister', {
        bubbles: true,
        detail: {
            callbacks: {
                setOrder: this.setOrder.bind(this),
                setDeRegistrationCallback: (deRegistrationCallback) => {
                    this._deRegistrationCallback = deRegistrationCallback;
                }
            }
        }
    });

    this.dispatchEvent(privatebuttonregister);
}

当子组件不再可用时通知父组件。

// button.js
disconnectedCallback() {
  this._connected = false;
  if (this._deRegistrationCallback) {
      this._deRegistrationCallback();
  }
}

使用数据驱动型方法

使用数据驱动的方法，当数据发生变化时，组件会以反应性方式获取更改。

此示例使用数据驱动方法编写子组件。

<template>
  <div class="c-parent">
    <template for:each={itemsData} for:item="itemData">
      <c-child onclick={onItemSelect} id={itemData.id} key={itemData.id}> </c-child>
    </template>
  </div>
</template>

若要传入数据，请使用 JavaScript 对象。子组件仅对来自其父组件的数据更改做出反应。

itemsData = [
    {
        label : 'custom label 1',
        id : 'custom-id-1'
        selected : false
    },
    {
        label : 'custom label 2',
        id : 'custom-id-2'
        selected : false
    }
]

当您有复杂的用例时，建议采用数据驱动的方法。使用数据驱动方法创建的基本组件的一个示例是 lightning-datatable。

查看组件依赖关系

使用依赖项树查看器可查看组件使用的自定义组件和 Apex 类。您可以快速查看组件的结构并导航到其依赖项的源。

在“设置”的“快速查找”框中，输入 ，然后选择 Lightning 组件。Lightning Components

• 要在详细信息页面上查看 Lightning Web 组件的依赖关系，请单击其名称旁边的 V 形图标，展开 Lightning Web 组件行。
• 若要查看其中一个依赖项的详细信息，请单击“名称”列中的链接。

依赖关系树显示组件的最多三个级别的依赖关系。例如，您可以看到一个组件及其嵌套的子组件、孙子组件和曾孙子组件。若要查看更深层次的依赖项，请单击其中一个嵌套组件的“名称”列中的链接。