月度归档： 2024 年 1 月

若要显示记录数据的行和列，请使用该组件。若要在具有结构层次结构的表中显示数据，例如客户记录和关联的联系人，请使用该组件。lightning-datatablelightning-tree-grid

比较和用于数据显示lightning-datatable lightning-tree-grid

这些组件类似，但有一个 V 形按钮，用于展开和折叠具有子记录的行。lightning-tree-grid

lightning-datatable使用 Salesforce Lightning Design System （SLDS） 中的数据表蓝图，并提供一种在桌面上显示记录数据的简单方法。

lightning-tree-grid使用 SLDS 中的树网格蓝图，使您能够显示分层数据，将记录分组到父子关系中。

提示

Lightning Design System 文档提供了每个组件处于不同状态的示例。

以下是 和 支持的功能列表。lightning-datatablelightning-tree-grid

特征	lightning-datatable	lightning-tree-grid
按数据类型设置列格式
标头操作
行操作
调整列大小
选择行
换行或剪裁列内容
行号
列排序		–
内联编辑		–
无限滚动		–
可扩展行	–

注意

lightning-datatable并且不受移动设备支持。lightning-tree-grid

使用内联编辑在表格中显示数据

要在表中显示 Salesforce 数据，请使用该组件。该组件支持内联编辑，使用户无需导航到记录即可更新字段值。lightning-datatable

若要加载记录列表，请使用 getListUi（已弃用）线路适配器或在 Apex 方法中使用 SOQL。请参阅数据指南。

此示例在 Apex 方法中使用 SOQL 在客户记录中加载联系人。

public with sharing class ContactController {

    @AuraEnabled(cacheable=true)
    public static List<Contact> getContacts(String accId) {
        return [
            SELECT AccountId, Id, FirstName, LastName, Title, Phone, Email
            FROM Contact
            WHERE AccountId = :accId
            WITH SECURITY_ENFORCED
        ];
    }
}

注释将方法公开给 Lightning 组件，并在客户端上缓存联系人列表。该参数筛选给定客户记录的联系人。@AuraEnabled(cacheable=true)accId

如果 Apex 方法返回数据，则 HTML 模板将显示具有可编辑名字和姓氏字段 （1） 的组件。编辑字段时，将显示“保存”按钮，您可以单击该按钮以更新联系人记录。成功更新联系人记录还会更新相关列表 （2） 中的记录数据，以及页面上由 Lightning 数据服务管理的其他组件。lightning-datatable

实现内联编辑

提示

此示例基于 lwc-recipes 存储库中的组件。此版本略有不同，以便能够在记录页面上使用数据表。datatableInlineEditWithUiApi

若要启用内联编辑，请按以下模板所示配置组件。lightning-datatableapexContactsForAccount

<!-- apexContactsForAccount.html -->
<template>
  <lightning-card title="Datatable Example" icon-name="custom:custom63">
    <div class="slds-m-around_medium">
      <template lwc:if={contacts.data}>
        <lightning-datatable
          key-field="Id"
          data={contacts.data}
          columns={columns}
          onsave={handleSave}
          draft-values={draftValues}
        >
        </lightning-datatable>
      </template>
      <template lwc:if={contacts.error}>
        <!-- Handle Apex error -->
      </template>
    </div>
  </lightning-card>
</template>

required 属性将每一行与联系人记录相关联。该属性保存通过线路服务从 Apex 方法或线路适配器检索的数据。该属性为每列分配一个记录字段，并自定义列的行为。当用户编辑单元格时，更新后的值将存储在 中。key-fielddatacolumnsdraft-values

单击“保存”按钮将触发该事件。使用事件处理程序将更改保留在数据表中。在此示例中，事件处理程序调用 updateRecord（recordInput， clientOptions） 来保存记录更改。saveonsaveonsave

注意

有关属性和支持的功能的列表，请参阅 lightning-datatable。

在列中启用内联编辑

一行数据对应于一条记录，每列显示该记录的其中一个字段的值。若要启用内联编辑，请通过在列定义中设置来指定可编辑的字段。在此示例中，“名字”和“姓氏”字段是可编辑的。由于联系人的“姓名”字段是复合字段，因此必须分别使用“名字”和“姓氏”字段。editable: true

// apexContactsForAccount.js

import { LightningElement, wire, api } from "lwc";
import getContacts from "@salesforce/apex/ContactController.getContactList";
import { refreshApex } from "@salesforce/apex";
import { updateRecord } from "lightning/uiRecordApi";

import { ShowToastEvent } from "lightning/platformShowToastEvent";
import FIRSTNAME_FIELD from "@salesforce/schema/Contact.FirstName";
import LASTNAME_FIELD from "@salesforce/schema/Contact.LastName";
import TITLE_FIELD from "@salesforce/schema/Contact.Title";
import PHONE_FIELD from "@salesforce/schema/Contact.Phone";
import EMAIL_FIELD from "@salesforce/schema/Contact.Email";
import ID_FIELD from "@salesforce/schema/Contact.Id";

const COLS = [
  {
    label: "First Name",
    fieldName: FIRSTNAME_FIELD.fieldApiName,
    editable: true,
  },
  {
    label: "Last Name",
    fieldName: LASTNAME_FIELD.fieldApiName,
    editable: true,
  },
  { label: "Title", fieldName: TITLE_FIELD.fieldApiName, editable: true },
  {
    label: "Phone",
    fieldName: PHONE_FIELD.fieldApiName,
    type: "phone",
    editable: true,
  },
  {
    label: "Email",
    fieldName: EMAIL_FIELD.fieldApiName,
    type: "email",
    editable: true,
  },
];
export default class DatatableInlineEditWithUiApi extends LightningElement {
  @api recordId;
  columns = COLS;
  draftValues = [];

  @wire(getContacts, { accId: "$recordId" })
  contacts;

  async handleSave(event) {
    // Convert datatable draft values into record objects
    const records = event.detail.draftValues.slice().map((draftValue) => {
      const fields = Object.assign({}, draftValue);
      return { fields };
    });

    // Clear all datatable draft values
    this.draftValues = [];

    try {
      // Update all records in parallel thanks to the UI API
      const recordUpdatePromises = records.map((record) => updateRecord(record));
      await Promise.all(recordUpdatePromises);

      // Report success with a toast
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Success",
          message: "Contacts updated",
          variant: "success",
        }),
      );

      // Display fresh data in the datatable
      await refreshApex(this.contacts);
    } catch (error) {
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Error updating or reloading contacts",
          message: error.body.message,
          variant: "error",
        }),
      );
    }
  }
}

@wire(getContacts)将数据提供给 ，并将记录 ID 提供给 。contacts.dataaccId

编辑字段时，将编辑的字段值和记录存储为对象数组。event.detail.draftValuesId

[
  {
    FirstName: "Sean",
    Id: "003R0000002J2wHIAS",
  },
  {
    FirstName: "Jack",
    Id: "003R0000002J2wIIAS",
  },
];

在进行更改后按 Tab 键或单击单元格外部时，将显示数据表页脚，其中包含“取消”和“保存”按钮。若要隐藏数据表页脚，请清除该属性。将值复制到记录对象中后，事件处理程序将清除。draftValuesonsavedraftValues

调用 updateRecord（recordInput， clientOptions） 将新字段值保存到记录中。

updateRecord()只需要一条记录。为要更新其字段的每条记录传入一个对象。在此示例中，该参数包含一个对象，该对象具有多个记录的更新字段。若要同时更新多条记录，请将参数传递给 进行处理。recordInputrecordupdateRecord()

成功保存后，事件处理程序将调度事件以显示成功 Toast 消息。onsaveShowToastEvent

更新记录后，刷新 Apex 方法中的联系人列表，以便数据表始终显示最新数据。refreshApex(this.contacts)

注意

对于单个事务中的批量记录更新，我们建议使用 Apex。请参阅使用 Apex 启用内联编辑部分。

使用 Apex 启用内联编辑

对于批量记录更新，请将记录更改传递给调用数据操作语言 （DML） 操作的 Apex 控制器。在此示例中，编辑后的字段值将传递到 Apex 控制器。由于记录是由 Apex 更新的，因此您必须使用 notifyRecordUpdateAvailable（recordIds） 函数通知 Lightning 数据服务 （LDS），以便刷新 Lightning 数据服务缓存和线路。updateupdateContacts

注意

此示例基于 github.com/trailheadapps/lwc-recipes 存储库中的组件。此版本略有不同，使用不带 LDS 的 Apex。datatableInlineEditWithApex

在上一示例中创建的文件中，导入 Apex 控制器和函数。apexContactsForAccount.jsnotifyRecordUpdateAvailable

import updateContacts from "@salesforce/apex/ContactController.updateContacts";
import { notifyRecordUpdateAvailable } from "lightning/uiRecordApi";

更新函数以处理编辑的值。若要确保在通过 Apex 更新记录后调用该记录，请使用 / 模式或 Promise 链。此示例使用 /。handleSave()notifyRecordUpdateAvailable()asyncawaitasyncawait

async handleSave(event) {
    const updatedFields = event.detail.draftValues;

    // Prepare the record IDs for notifyRecordUpdateAvailable()
    const notifyChangeIds = updatedFields.map(row => { return { "recordId": row.Id } });

    try {
        // Pass edited fields to the updateContacts Apex controller
        const result = await updateContacts({data: updatedFields});
        console.log(JSON.stringify("Apex update result: "+ result));
        this.dispatchEvent(
            new ShowToastEvent({
                title: 'Success',
                message: 'Contact updated',
                variant: 'success'
            })
        );

        // Refresh LDS cache and wires
        notifyRecordUpdateAvailable(notifyChangeIds);

        // Display fresh data in the datatable
        await refreshApex(this.contacts);
            // Clear all draft values in the datatable
            this.draftValues = [];
        }
   } catch(error) {
           this.dispatchEvent(
               new ShowToastEvent({
                   title: 'Error updating or refreshing records',
                   message: error.body.message,
                   variant: 'error'
               })
         );
    };
}

Apex 控制器将包含更新字段的 JSON 字符串反序列化为 Contact 对象。它使用 DML 操作更新已更改的记录。updateContactsupdate

@AuraEnabled
public static string updateContacts(Object data) {
    List<Contact> contactsForUpdate = (List<Contact>) JSON.deserialize(
         JSON.serialize(data),
         List<Contact>.class
    );
    try {
        update contactsForUpdate;
        return 'Success: contacts updated successfully';
    }
    catch (Exception e) {
        return 'The following exception has occurred: ' + e.getMessage();
    }
}

创建自定义数据类型
组件根据您为列指定的类型设置数据格式。lightning-datatable

在创建自己的数据类型之前，请检查标准数据类型，看看是否满足您的要求。可以使用类型属性自定义多种类型的输出。标准数据类型包括：

action
boolean
button
button-icon
currency
date
date-local
email
location
number
percent
phone
text（默认）
url
有关标准数据类型及其类型属性的更多信息，请参阅 lightning-datatable 参考文档。

此外，在创建自己的数据类型之前，请考虑 SLDS 样式挂钩。SLDS 样式钩子可帮助您在影子 DOM 中自定义支持的数据类型。例如，可以使用 SLDS 样式挂钩在数据类型上应用不同的颜色。button

注意

自定义数据类型不支持调度自定义事件。

通过扩展 LightningDatatable 定义自定义类型

创建自己的数据类型来实现自定义单元格，例如删除行按钮或图像，甚至是自定义文本或数字显示。还可以为自定义数据类型上的每一行应用自定义类。

若要定义和使用自定义数据类型，请在新组件中扩展组件的类。LightningDatatablelightning-datatable

注意

您可以从 only 扩展到创建具有自定义数据类型的数据表。在所有其他情况下，不支持扩展除创建 Lightning Web 组件之外的任何类。LightningDatatableLightningElement

创建一个 Lightning Web 组件，并在组件文件夹的 HTML 模板中定义您的类型。该模板可以包含不需要 JavaScript 的简单数据类型的完整 UI。该模板还可以嵌入您在另一个文件夹中定义的组件。例如，如果要包含确定要显示的内容的逻辑，请使用单独的组件。

让我们看一下组件的文件夹结构，它定义了两种自定义类型。myCustomTypeDatatable

myCustomTypeDatatable
   ├──customName.html
   ├──customNumber.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml
在 JavaScript 文件中，扩展类并指定类型的名称和模板文件。此示例使用 和 模板创建自定义名称类型和自定义数字类型。myCustomTypeDatatable.jsLightningDatatablecustomName.htmlcustomNumber.html

注意

类型和模板的名称不必匹配。该示例同时使用类型名称和模板文件名。我们建议您导入具有不同名称的模板，以便明确指定类型名称和模板名称的位置。customName

//myCustomTypeDatatable.js
import LightningDatatable from "lightning/datatable";
import customNameTemplate from "./customName.html";
import customNumberTemplate from "./customNumber.html";

export default class MyCustomTypeDatatable extends LightningDatatable {
  static customTypes = {
    customName: {
      template: customNameTemplate,
      standardCellLayout: true,
      typeAttributes: ["accountName"],
    },
    customNumber: {
      template: customNumberTemplate,
      standardCellLayout: false,
      typeAttributes: ["status"],
    },
    // Other types here
  };
}
注意

您可以从 only 扩展到创建自定义数据类型。LightningDatatable

将以下属性传递给对象。customTypes

自定义类型属性	类型	描述
template	字符串	键入的导入 HTML 模板的名称。
typeAttributes	数组	要传递给自定义数据模板的属性的逗号分隔列表。使用语法访问数据。typeAttributes.attributeName
standardCellLayout	布尔	指定是否使用标准布局。默认值为 false。所有标准数据类型都使用标准布局。自定义数据类型的默认布局是裸布局。请参阅自定义数据类型布局和样式。您可以使用自定义数据类型的单元格样式，使其看起来与标准数据类型相似。还支持辅助功能和键盘导航。standardCellLayoutstandardCellLayout
创建自定义数据模板

在自定义数据模板中，添加数据类型的标记。此示例创建一个自定义类型，该类型使用组件呈现文本标签。customName.htmllightning-badge

<!--customName.html-->
<template>
  <lightning-badge label={typeAttributes.accountName} icon-name="standard:account">
  </lightning-badge>
</template>
该模板使用默认的裸布局，因为 设置为 .您可以添加自己的样式。以下示例在单元格周围添加一个小填充，并将数字浮动到右侧。如果数字与数据定义中指定的条件匹配，则会显示一个图标。customNumber.htmlmyCustomTypeDatatable.jsstandardCellLayout: falsecustomNumber

<!--customNumber.html-->
<template>
  <div class="slds-p-around_x-small">
    <lightning-formatted-number
      value={value}
      class="slds-float_right"
    ></lightning-formatted-number>
    <lightning-icon
      icon-name={typeAttributes.status}
      alternative-text="Employer Status"
    ></lightning-icon>
  </div>
</template>
提示

这些示例自定义数据类型很简单，只能用 HTML 表示。如果自定义类型更复杂，请使用 JavaScript、HTML 模板和 XML 配置文件创建单独的组件。使用自定义数据 HTML 模板作为组件的容器。自定义数据类型的编辑模板示例中使用了一个单独的组件。

使用自定义类型实现数据表

让我们实现一个使用自定义类型的数据表。第一列使用我们在上一节中创建的自定义类型显示帐户名称。该属性与帐户对象上的字段匹配。fieldNameName

使用自定义类型记录数据表中显示的数据

使用 Apex 控制器在数据表中显示 10 条帐户记录。

public with sharing class AccountController {
    @AuraEnabled(cacheable=true)
    public static List<Account> getAccountList() {
        return [SELECT Id, Name, Industry, NumberOfEmployees FROM Account WITH SECURITY_ENFORCED LIMIT 10];
    }
}
要实现自定义类型 datatable，请创建一个包装组件以包含扩展的 datatable 组件，定义数据表的列，然后获取数据。这里我们用作包装器。myDatatable

定义列时，可以使用该属性传入 SLDS 实用程序类或您自己的类。cellAttributes

/* myDatatable.js */
import { LightningElement, wire, track } from "lwc";
import getAccountList from "@salesforce/apex/AccountController.getAccountList";

const COLS = [
  {
    label: "Account Name",
    type: "customName",
    typeAttributes: {
      accountName: { fieldName: "Name" },
    },
  },
  {
    label: "Industry",
    fieldName: "Industry",
    cellAttributes: {
      class: { fieldName: "industryColor" },
    },
  },
  {
    label: "Employees",
    type: "customNumber",
    fieldName: "NumberOfEmployees",
    typeAttributes: {
      status: { fieldName: "status" },
    },
    cellAttributes: {
      class: "slds-theme_alert-texture",
    },
  },
];

export default class MyDatatable extends LightningElement {
  columns = COLS;
  @track accounts = [];

  @wire(getAccountList)
  wiredAccounts({ error, data }) {
    if (error) {
      // Handle error
    } else if (data) {
      // Process record data
      this.accounts = data.map((record) => {
        let industryColor = record.Industry === "Energy" ? "slds-text-color_success" : "";
        let status = record.NumberOfEmployees > 10000 ? "utility:ribbon" : "";
        return { ...record, industryColor: industryColor, status: status };
      });
    }
  }
}
myDatatable.js演示了在自定义单元格上应用样式的几种方法。仅当字段值匹配时，该列才使用该类。该列在该列的所有行上使用该类。此外，用于列的类型包括直接在标记中实现的布局和填充类。Industryslds-text-color_successEnergyNumberOfEmployeesslds-theme_alert-texturecustomNumberNumberOfEmployeescustomNumber.html

接下来，将 Apex 控制器返回的数据传递给自定义类型 datatable 组件中的属性。getAccountListdata

<!--myDatatable.html-->
<template>
  <c-my-custom-type-datatable
    key-field="Id"
    data={accounts}
    columns={columns}
    show-row-number-column
  >
  </c-my-custom-type-datatable>
</template>
提示

lwc-recipes 存储库中的组件为 创建自定义数据类型。datatableCustomDataTypelightning-datatable

自定义数据类型布局和样式

您可以自定义使用自定义数据类型的单元格的外观。lightning-datatable

使用自定义数据类型的布局

自定义单元格可以使用标准布局或裸布局。

标准布局：

• 将内容均匀地分布在单元格中，第一个项目与左边框齐平，最后一个项目与右边框齐平
• 将文本向左对齐，垂直向中对齐
• 在内容的左侧和右侧添加一个小填充
• 支持可编辑类型的辅助功能和键盘导航

裸布局，这是自定义单元格的默认布局：

• 将文本向左对齐，垂直向中对齐
• 删除内容左侧和右侧的填充
• 不支持可编辑类型的辅助功能和键盘导航

所有支持的标准数据类型都使用标准布局。lightning-datatable

若要使用标准布局，请指定定义自定义类型的时间。standardCellLayout: true

static customTypes = { customName: { template: customNameTemplate, standardCellLayout: true,
typeAttributes: ['accountName'], }, // Other types here }

请参阅创建自定义数据类型。

创建自定义数据类型并使用默认裸布局时，可以应用自己的样式、对齐列中的内容、配置文本换行和剪辑。

在列上应用样式

若要将样式应用于列中的所有行，请在列配置中将 CSS 类传递给。cellAttributes

const COLS = [
  {
    label: "Employees",
    type: "number",
    fieldName: "NumberOfEmployees",
    cellAttributes: {
      class: "slds-theme_shade slds-theme_alert-texture",
    },
  },
];

若要将样式应用于特定行，请使用该属性将 CSS 类连接到数据定义。此示例使用该属性将蓝色文本应用于“能源”行业的行。fieldNamefieldNameindustryClass

/* myDatatable.js */
import { LightningElement, wire, track } from 'lwc';
import getAccountList from '@salesforce/apex/AccountController.getAccountList';

const COLS = [{
    label: 'Industry', fieldName: 'Industry',
    cellAttributes: {
        class: { fieldName: 'industryClass' },
    }
}, // Other columns here
];

export default class MyDatatable extends LightningElement {
    columns = COLS;
    @track accounts = [];

    @wire(getAccountList)
    wiredAccounts({error, data}) {
        if (error) {
            // Handle error
        } else if (data) {
            // Process record data
            this.accounts = data.map((record) => {
                let industryClass = record.Industry === 'Energy' ? 'blueText': 'defaultText';
                return {...record, 'industryClass: industryClass}
            });

        }
    }

对齐自定义单元格中的内容

您可以对齐使用自定义数据类型标准布局的列中的内容。在定义中，传入属性。cellAttributesalignment

const COLS = [
  {
    label: "Account Name",
    type: "customName",
    fieldName: "Name",
    cellAttributes: {
      alignment: "right",
    },
  },
];

支持的值为 、 和 。alignmentleftcenterright

默认情况下，标准数字类型向右对齐。标准数字类型包括 、 和 数据类型。currencynumberpercent

文本换行和剪裁

创建自定义数据类型时，请使用 SLDS 实用程序类和 实现文本换行和剪裁。这些类使自定义数据单元格能够在用户更改数据表列标题中的自动换行选择时正确显示。文本换行会垂直展开行以显示更多内容。文本剪裁会将内容截断为列中的一行。slds-hyphenateslds-truncate

假设您有一个显示帐户名称的自定义数据类型模板。默认情况下，该列显示的文本被剪裁，这会截断带有尾随省略号的内容。

<template>
  <template lwc:if={wrapText}>
    <div class="slds-hyphenate">{typeAttributes.accountName}</div>
  </template>
  <template lwc:else>
    <div class="slds-truncate">{typeAttributes.accountName}</div>
  </template>
</template>

您还可以创建一个 getter，该 getter 根据该值返回 SLDS 实用程序类。wrapText

若要显示换行文本，请从列标题的下拉菜单中选择换行文本。

或者，若要在加载数据表时在列上显示换行文本，请传入列定义。wrapText: true

const COLS = [
  {
    label: "Account Name",
    type: "customText",
    wrapText: true,
    typeAttributes: {
      accountName: { fieldName: "Name" },
    },
  },
];

您可以控制换行列内容时显示的行数。在扩展数据表组件中设置，以在隐藏其余行之前显示多行。数据表应用行位以允许多行文本截断。wrap-text-max-lines

<template>
  <c-my-custom-type-datatable
    key-field="id"
    data={accounts}
    columns={columns}
    wrap-text-max-lines="2"
  >
  </c-my-custom-type-datatable>
</template>

注意

wrap-text-max-linesInternet Explorer 11 不支持。如果为 true，则显示列中的整个文本。wrapText

使自定义数据类型可编辑

若要使自定义数据类型可在 中编辑，请创建一个附加模板来实现用于内联编辑数据类型的 UI。lightning-datatable

这些高级步骤增加了内联编辑功能。

1. 创建编辑模板。
2. 将编辑模板添加到自定义类型定义中。
3. 使自定义类型在列定义中可编辑。

让我们通过扩展 LightningDatatable 定义自定义类型中的示例中的类型实现内联编辑。customNumber

创建编辑模板

在定义自定义类型模板的同一文件夹中，创建用于编辑自定义类型的模板。customNumberEdit.htmlcustomNumber.html

myCustomTypeDatatable
   ├──customName.html
   ├──customNumber.html
   ├──customNumberEdit.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml

自定义类型的编辑模板使用与自定义类型模板中的输出组件匹配的输入组件。建议使用该组件。在示例中，输出组件在模板中使用，因此我们在其编辑模板中使用。该组件使用户能够更改自定义类型单元格中的数字。lightning-inputlightning-formatted-numbercustomNumberlightning-input type="number"lightning-input type="number"

提示

有关可在编辑模板中使用的组件的信息，请参阅本页后面的自定义类型的内联编辑注意事项。

<!--customNumberEdit.html-->
<template>
  <div class="slds-p-around_x-small">
    <lightning-input
      type="number"
      value={editedValue}
      required={required}
      label={columnLabel}
      min={typeAttributes.min}
      data-inputable="true"
      class="slds-float_right"
    >
    </lightning-input>
  </div>
</template>

使用这些属性在输入组件和扩展数据表组件之间传递值。

该示例设置该属性，以确保用户在内联编辑自定义数字时输入非负数。在下一节中，将添加到自定义类型定义中。minmin

该属性对于标准单元格布局中的辅助功能支持是必需的。data-inputable="true"

将编辑模板添加到自定义类型定义

导入 中的编辑模板，并在对象的定义中添加属性。该属性指定用于自定义类型的内联编辑的模板。myCustomTypeDatatable.jseditTemplate: customNumberEditTemplatecustomNumbercustomTypeseditTemplate

//myCustomTypeDatatable.js
import LightningDatatable from "lightning/datatable";
import customNameTemplate from "./customName.html";
import customNumberTemplate from "./customNumber.html";
import customNumberEditTemplate from "./customNumberEdit.html";

export default class MyCustomTypeDatatable extends LightningDatatable {
  static customTypes = {
    customName: {
      template: customNameTemplate,
      standardCellLayout: true,
      typeAttributes: ["accountName"],
    },
    customNumber: {
      template: customNumberTemplate,
      editTemplate: customNumberEditTemplate,
      standardCellLayout: true,
      typeAttributes: ["status", "min"],
    },
    // Other types here
  };
}

将值更改为 true 以支持辅助功能和键盘导航。有关详细信息，请参阅本页后面的可编辑自定义类型的辅助功能。standardCellLayout

在类型定义中添加属性。mintypeAttributes

使自定义类型在列定义中可编辑

在数据表的列定义中，将属性添加到自定义类型。editable: true

在这里，我们展示了创建自定义数据类型中的使用自定义类型实现数据表的示例，该数据类型将属性应用于 Employees 列，该列使用 type .myDatatable.jseditable: truecustomNumber

/* myDatatable.js */
import { LightningElement, wire, track } from 'lwc';
import getAccountList from '@salesforce/apex/AccountController.getAccountList';

const COLS = [
    { label: 'Account Name', type: 'customName',
     typeAttributes: {
        accountName: { fieldName: 'Name' }
    },
    },
    { label: 'Industry', fieldName: 'Industry',
     cellAttributes: {
        class: {fieldName: 'industryColor'},
    }
    },
    { label: 'Employees', type: 'customNumber', fieldName: 'NumberOfEmployees', editable: true,
     typeAttributes: {
            status: {fieldName: 'status'},
            min: 0
    },
    cellAttributes: {
        class: 'slds-theme_alert-texture'
    }
}];

如果在编辑模板中向输入组件添加属性，请将它们也添加到列定义中。在这里，我们为 Employees 列添加了属性。mintypeAttributes

处理自定义类型的更改值

与标准数据类型一样，自定义类型的编辑字段以黄色突出显示显示。单元格的更改值临时存储在属性中。editedValue

使用 action 和 attribute 保留数据表中更改的值，就像对标准类型所做的那样。请参阅 lightning-datatable 参考文档中的使用内联编辑在表中显示数据和使用内联编辑部分。onsavedraft-values

可编辑自定义类型的辅助功能

要支持辅助功能，例如可编辑自定义数据类型的键盘导航，请执行以下操作：

• 将属性添加到编辑模板中的输入组件。data-inputable="true"
• 为 中的自定义类型定义设置。standardCellLayout: truecustomTypes

这些属性使数据表的操作模式和导航模式能够处理您的自定义数据类型。通过在显示可编辑的自定义数据类型的单元格上按 Enter 键或空格键进入操作模式。在导航模式下，当您在数据表中按 Tab 键时，您可以导航到显示可编辑自定义数据类型的单元格，因为它们是可操作的。

该属性使用该属性的值应用于输入组件。aria-labellabel

自定义类型的已编辑单元格的验证和错误处理

该组件为您处理基本的客户端输入验证。例如，如果为数字输入指定 、 或属性，则组件会根据这些属性值验证输入，如果输入无效，则返回错误。还可以对自定义类型执行更复杂的客户端验证。lightning-inputstepminmax

若要在客户端上进一步验证自定义类型的用户输入，请在自定义编辑模板中使用子组件。

在输入组件上设置，并在其 JS 中包含 getter，以公开输入组件的有效性 API。data-inputable="true"validity()

@api
get validity() {
    return this.customInput.validity;
}

在编辑模板中公开输入组件中的方法，以便自定义数据类型可以在更改的数据无效时显示自定义消息。showHelpMessageifInvalid()

@api
showHelpMessageIfInvalid() {
    this.customInput.showHelpMessageIfInvalid()
}

有关详细信息，请参阅 lightning-input 的参考文档。

自定义类型的内联编辑注意事项

• 在自定义编辑模板中，仅支持将具有单个输入字段的 Lightning 基本组件作为输入组件。还支持具有多个输入的组件，其 API 计算结果为单个输入。lightning-input type="datetime"
• 该组件仅设计用于数据表，不支持在数据表中使用。请改用。lightning-input-fieldlightning-record-edit-formlightning-input
• 自定义数据类型尚不支持服务器端验证规则。

自定义数据类型的编辑模板示例

此示例显示了一个自定义数据类型，其模板包含组件而不是简单的标记。

注意

lwc-recipes 存储库具有多个组件，用于演示使用 Apex 和模块进行内联编辑。查找名称以 开头的组件。lightning/uiRecordApidatatableInline

此示例创建一个具有 Amount 自定义数据类型的数据表。

这是初始加载时的数据表。

该组件包含定义自定义类型的扩展数据表组件。myDatatableWrapper

/* myDatatableWrapper.html */

<template>
  <c-my-custom-type-datatable columns={COLS} key-field="id" data={data}>
  </c-my-custom-type-datatable>
</template>

// myDatatableWrapper.js

import { LightningElement } from 'lwc';
export default class MyDatatableWrapper extends LightningElement {
    COLS = [
        { label: 'Account', type: 'text', fieldName: 'account', editable: false, displayReadOnlyIcon: true},
        { label: 'Stage', type: 'text', fieldName: 'stage', editable: false, displayReadOnlyIcon: true},
        { label: 'Amount', type: 'customNumber', fieldName: 'amount', editable: true,
            typeAttributes: {
                status: {fieldName: 'status'},
                step: {fieldName: 'step'}
            }
        },
        { label: 'Due Date', type: 'date', fieldName: 'date', editable: false, displayReadOnlyIcon: true}
    ];

    data = [
        {account: 'Acme Corp.', amount: '200.00', status: 'action:user',
            step: '0.01', stage:'Value Proposition', date: '2022-02-10T00:00:00Z'},
        {account: 'Norwood Inc.', amount: '500000.00', status: 'action:user',
            step: '0.01', stage:'Closed Won', date: '2022-01-20T00:00:00Z'},
        {account: 'Edge Communications', amount: '800000.00', status: 'action:user',
            step: '0.01', stage:'Closed Won', date: '2022-02-18T00:00:00Z'},
        {account: 'Pyramid Construction Inc.', amount: '50000.00', status: 'action:user',
            step: '0.01', stage:'Closed ', date: '2022-03-10T00:00:00Z'},
        {account: 'GenePoint', amount: '30000', status: 'action:user',
            step: '0.01', stage:'Negotiation/Review	', date: '2022-05-28T00:00:00Z'},
        {account: 'Dickenson plc', amount: '1550000.00', status: 'action:user',
            step: '0.01', stage:'Closed Won', date: '2022-03-16T00:00:00Z'}
    ]

下面是具有可编辑自定义类型的扩展数据表的文件夹。

myCustomTypeDatatable
   ├──customNumber.html
   ├──customNumberEdit.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml

编辑模板包含另一个定义内联编辑 UI 的组件。

/*customNumber.html*/
<template>
  <c-my-fancy-number value={value}> </c-my-fancy-number>
</template>

子组件定义数据类型的显示，并包含用于确定应用于数据的样式的逻辑。

该组件评估数据以应用类、图标和图标样式。myFancyNumber

/* myFancyNumber.html */

<template>
  <div class={computedClass}>
    <lightning-formatted-number format-style="currency" value={value}>
    </lightning-formatted-number>
    <lightning-icon
      class="slds-p-horizontal_xx-small"
      icon-name={computedIcon}
      size="xx-small"
      variant={iconVariant}
    >
    </lightning-icon>
    ({range})
  </div>
</template>

// myFancyNumber.js

import { LightningElement, api, track, wire } from "lwc";

export default class MyFancyNumber extends LightningElement {
  @api value;
  get range() {
    return this.value > 50000 ? "High" : "Low";
  }
  get computedClass() {
    return this.value > 50000 ? "slds-text-color_success" : "slds-text-color_error";
  }

  get computedIcon() {
    return this.value > 50000 ? "utility:arrowup" : "utility:arrowdown";
  }

  get iconVariant() {
    return this.value > 50000 ? "success" : "error";
  }
}

该模板使用带有 的组件。customNumberEdit.htmllightning-inputtype="number"

/* customNumberEdit.html */
<template>
  <lightning-input
    type="number"
    value={editedValue}
    label={columnLabel}
    required={required}
    step={typeAttributes.step}
    data-inputable="true"
  >
  </lightning-input>
</template>

下面是在保存表之前编辑自定义数字类型字段后的数据表。编辑后的字段以黄色突出显示。

有关保存已更改数据的信息，请参阅使用内联编辑在表中显示数据。

创建记录数据的分层表

该组件显示可展开以显示子记录的数据行。lightning-tree-grid

该组件基于并支持其功能的子集。请参阅在表格中显示记录数据，以比较每个组件提供的功能。lightning-tree-gridlightning-datatable

显示记录和子记录

让我们创建一个表来显示具有关联案例的帐户。每个行级操作都允许您使用导航服务编辑客户或案例记录。

让我们使用 Apex 获取数据。在此示例中，包含一个 SOQL 语句，该语句返回帐户名称和状态为 的所有关联事例。CaseController.clsNew

//CaseController.cls
public with sharing class CaseController {
    @AuraEnabled(cacheable=true)
    public static list<Account> getNewCasesForAccounts(){
        return [SELECT Name, (
                SELECT Id, CaseNumber, Status FROM Cases WHERE toLabel(Status) = 'New')
                FROM Account WHERE Id IN (SELECT AccountId FROM Case)];
    }
}

在 JavaScript 文件中，用于调用 Apex 方法。使用键定义包含子项的行。包含子项的行显示带有 V 形按钮，用于切换子项。myTreeGrid.js@wire_children

//myTreeGrid.js
import { LightningElement, wire, track } from "lwc";
import { NavigationMixin } from "lightning/navigation";

import getNewCases from "@salesforce/apex/CaseController.getNewCasesForAccounts";

const actions = [{ label: "Edit", name: "edit_record" }];

const COLS = [
  {
    fieldName: "Name",
    label: "Account Name",
  },
  {
    fieldName: "CaseNumber",
    label: "New Cases",
    cellAttributes: {
      iconName: { fieldName: "iconName" },
    },
  },
  {
    type: "action",
    label: "Edit Record",
    typeAttributes: {
      rowActions: actions,
      menuAlignment: "right",
    },
  },
];

export default class MyTreeGrid extends NavigationMixin(LightningElement) {
  @track myData = [];
  columns = COLS;
  error;

  @wire(getNewCases)
  wiredCases({ error, data }) {
    if (error) {
      // Handle error
      this.error = error;
    } else if (data) {
      // Process record data
      var strData = JSON.parse(JSON.stringify(data));

      strData.map((row, index) => {
        if (row["Cases"]) {
          row._children = row["Cases"]; //define rows with children
          delete row.Cases;

          let iconKey = "iconName";
          row[iconKey] = "standard:case";
        }
      });
      this.myData = strData;
    }
  }

  handleRowAction(event) {
    const action = event.detail.action;
    const row = event.detail.row;
    switch (action.name) {
      case "edit_record":
        this[NavigationMixin.Navigate]({
          type: "standard__objectPage",
          attributes: {
            objectApiName: "Case",
            actionName: "edit",
            recordId: row.Id,
          },
        });
        break;
    }
  }
}

使用 创建表。lightning-tree-grid

<!--myTreeGrid.html-->
<template>
  <lightning-tree-grid
    columns={columns}
    data={myData}
    key-field="Id"
    onrowaction={handleRowAction}
  >
  </lightning-tree-grid>
</template>

更改表单显示密度

在 Lightning Experience 中，显示密度设置决定了显示内容的密度和字段标签的位置。在“设置”中为组织控制显示密度，用户还可以从其配置文件菜单中根据自己的喜好设置显示密度。

组织的舒适设置将标签放在字段的顶部，并在页面元素之间添加更多空间。相比之下，紧凑视图是更密集的视图，标签与字段位于同一行上，行与行之间的间距更小。舒适的环境类似于紧凑，但线条之间有更多的空间。

您可以将表单设计为遵循显示密度设置，或设置表单密度以覆盖显示密度设置。通过覆盖显示密度，您可以更好地控制标签位置，但不会影响间距。此外，您可以将表单中的各个字段设置为使用更改字段标签位置的变体。

在表单中使用组织的默认显示密度

lightning-record-edit-form、 ，并根据组织的显示密度进行调整，或者在您设置 时进行调整。lightning-record-view-formlightning-record-formdensity="auto"

<lightning-card icon-name="standard:contact" title="record-edit-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the record-id with your own -->
        <lightning-record-edit-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="auto">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="FirstName"></lightning-input-field>
            <lightning-input-field field-name="LastName"></lightning-input-field>
            <lightning-input-field field-name="Email"></lightning-input-field>
            <lightning-input-field field-name="Phone"></lightning-input-field>
        </lightning-record-edit-form>
    </div>
</lightning-card>

覆盖组织的显示密度

要覆盖组织的显示密度，请指定 或 。该属性不支持该值。如果组织的显示密度设置为舒适，则默认情况下标签和字段位于同一行上。density="compact"density="comfy"cozydensity

下表列出了组织的显示密度设置，以及它们与 、 和 上的表单密度的关系。lightning-record-edit-formlightning-record-view-formlightning-record-form

减少标签和字段之间的空间

当表单密度为 时，标签和字段对于较大区域中的单个列表单来说可能显得太远。要在表单使用紧凑密度时减小标签和字段之间的间距，请使用 on 或 上的类。compactslds-form-element_1-collightning-input-fieldlightning-output-field

<lightning-card icon-name="standard:contact" title="record-edit-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the record-id with your own -->
        <lightning-record-edit-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="compact">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="FirstName" class="slds-form-element_1-col"></lightning-input-field>
            <lightning-input-field field-name="LastName" class="slds-form-element_1-col"></lightning-input-field>
            <lightning-input-field field-name="Email" class="slds-form-element_1-col"></lightning-input-field>
            <lightning-input-field field-name="Phone" class="slds-form-element_1-col"></lightning-input-field>

        </lightning-record-edit-form>
    </div>
</lightning-card>

在表单域上设置标签变体

如果您希望特定字段的标签和字段对齐方式与表单使用的标签和字段对齐方式不同，则可以设置变体。变体将覆盖该字段的显示密度。lightning-input-field

lightning-input-field支持以下变体：（默认）、、 和 。standardlabel-hiddenlabel-inlinelabel-stacked

此示例显示两个带有内联标签的输入字段，而其余字段的标签则由于表单密度舒适而显示在字段顶部。

<lightning-card icon-name="standard:contact" title="record-edit-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the recordId with your own -->
        <lightning-record-edit-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="comfy">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="FirstName" variant="label-inline"></lightning-input-field>
            <lightning-input-field field-name="LastName" variant="label-inline"></lightning-input-field>
            <lightning-input-field field-name="Email"></lightning-input-field>
            <lightning-input-field field-name="Phone"></lightning-input-field>
        </lightning-record-edit-form>
    </div>
</lightning-card>

lightning-output-field支持以下变体：（默认）和 .standardlabel-hidden

本示例在表单密度为 时显示不带标签的输出字段值。隐藏标签可用于辅助技术。comfy

<lightning-card icon-name="standard:contact" title="record-view-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the recordId with your own -->
        <lightning-record-view-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="comfy">
            <lightning-messages></lightning-messages>
            <lightning-output-field field-name="FirstName" variant="label-hidden"></lightning-output-field>
            <lightning-output-field field-name="LastName" variant="label-hidden"></lightning-output-field>
            <lightning-output-field field-name="Email" variant="label-hidden"></lightning-output-field>
            <lightning-output-field field-name="Phone" variant="label-hidden"></lightning-output-field>
        </lightning-record-view-form>
    </div>
</lightning-card>

此外，要在标签变体为 时减小标签和字段之间的间距，请使用 上的类。label-inlineslds-form-element_1-collightning-input-field

使用注意事项

管理员可以在“密度设置”设置页面上为组织设置默认显示密度。用户可以随时选择自己的显示密度。管理员无法覆盖用户的显示密度设置。组织的默认显示设置取决于 Salesforce 版本。密度更改不适用于 Salesforce Classic、Experience Cloud 站点或 Salesforce 移动应用程序。有关详细信息，请参阅配置用户界面设置。

使用记录的注意事项

使用基本组件处理记录后，您无需额外配置即可使用 Lightning 数据服务，但需要考虑一些自定义用例。

请考虑以下用例。

• 若要显示基于记录类型的记录窗体（包括基于记录类型的选择列表值），请获取记录类型 ID。
• 若要通知父组件记录提交成功，请调度和处理自定义事件。

获取记录类型 ID

选择列表字段根据您的记录类型显示值。使用 or 时，如果一个对象上有多个记录类型，并且没有默认记录类型，则必须提供记录类型 ID。否则，将使用默认记录类型 Id。lightning-record-formlightning-record-edit-form

若要检索记录类型信息，请使用 getObjectInfo 线路适配器。

例

示例：使用 record-type-id 属性

通过提供属性，根据记录类型显示记录创建表单。此示例显示可以放置在客户记录页上的窗体。表单显示字段，其中包括一个选择列表，其值基于给定的记录类型 ID。record-type-id

<template>
  <lightning-card title="Record Form with Record Type" icon-name="standard:account">
    <div lwc:if={objectInfo.data} class="slds-m-around_medium">
      <lightning-record-form
        object-api-name={objectApiName}
        record-type-id={recordTypeId}
        fields={fields}
      >
      </lightning-record-form>
    </div>
  </lightning-card>
</template>

导入模块和对帐户对象的引用。getter 返回与记录类型名称匹配的 Id。getObjectInforecordTypeIdSpecial Account

import { LightningElement, api, wire, track } from "lwc";
import { getObjectInfo } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import PHONE_FIELD from "@salesforce/schema/Account.Phone";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class RecordFormWithRecordType extends LightningElement {
  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;

  @track objectInfo;

  // Define fields to display in form
  // Industry field is a picklist
  fields = [NAME_FIELD, PHONE_FIELD, INDUSTRY_FIELD];

  @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
  objectInfo;

  get recordTypeId() {
    const rtis = this.objectInfo.data.recordTypeInfos;
    return Object.keys(rtis).find((rti) => rtis[rti].name === "Special Account");
  }
}

该属性返回组织中可用的记录类型 ID 的映射。recordTypeInfos

处理窗体上的自定义事件

、 和 组件通过 、 和 属性进行事件处理。要将表单数据传递到容器组件，请创建自定义事件。lightning-record-formlightning-record-edit-formlightning-record-view-formonsubmitonsuccessonerror

假设你有一个容器组件，并且你的表单在组件中。让我们将新记录的 Id 传递给容器组件。在 中，创建一个 的实例。c-wrapperc-account-creatorc-wrapperc-account-creator

<!-- wrapper.html -->
<template>
  <c-account-creator onnewrecord={handleNewRecord}></c-account-creator>
</template>

成功创建记录后，处理程序将调度该事件，然后该处理程序将调用具有记录 ID 的方法。newrecordonsuccesslightning-record-formhandleNewRecord

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

export default class Wrapper extends LightningElement {
  recordId;

  /**
   * Handles the new record event.
   */
  handleNewRecord(evt) {
    const recordId = evt.detail.data.id;
    this.recordId = recordId;
  }
}

在 中，该属性显示一条消息，其中包含新创建的记录的 ID。c-account-creatorcreateStatus

注意

该 ID 在事件中不可用。使用该事件返回 Id。submitsuccess

<!-- c-account-creator -->
<template>
  <lightning-record-form
    object-api-name={accountObject}
    fields={accountFields}
    mode="edit"
    onsuccess={handleAccountCreated}
  >
  </lightning-record-form>
  <span class="slds-m-around_small status">{createStatus}</span>
</template>

该方法处理事件。handleAccountCreatedsuccess

import { LightningElement } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import WEBSITE_FIELD from "@salesforce/schema/Account.Website";

/**
 * Creates Account records.
 */
export default class AccountCreator extends LightningElement {
  /** Status message when creating an Account. */
  createStatus = "";

  accountObject = ACCOUNT_OBJECT;

  accountFields = [NAME_FIELD, WEBSITE_FIELD];

  /** Handles successful Account creation. */
  handleAccountCreated(evt) {
    this.createStatus = `Account record created. Id is ${evt.detail.id}.`;

    const event = new CustomEvent("newrecord", {
      detail: { data: evt.detail },
    });
    this.dispatchEvent(event);
  }
}

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>