组件可访问性

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

我们建议您在创建自定义组件时遵循 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 分布式移动应用程序。这两种环境之间的差异不仅仅是屏幕尺寸;有新的限制，也有移动端的扩展功能。若要构建在移动体验中表现良好的组件，请遵循我们的移动就绪组件指南。

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