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

我们建议您在创建自定义组件时遵循 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 组件行。
• 若要查看其中一个依赖项的详细信息，请单击“名称”列中的链接。

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