ARIA: textbox 角色

描述

当元素具有 textbox 角色时，浏览器会将可访问的 textbox 事件发送到辅助技术，然后辅助技术可以通知用户。

默认情况下是单行输入，按 Return 或 Enter 会提交表单；在这种情况下，最好使用 HTML <input> 并设置 type="text"。要创建支持换行的多行文本框，如 HTML <textarea>，请设置 aria-multiline="true"。包含 HTML contenteditable 属性可确保文本节点可编辑。

<!-- Text input field -->
<div id="txtboxLabel">Enter your five-digit zip code</div>
<div
  role="textbox"
  contenteditable="true"
  aria-placeholder="5-digit zip code"
  aria-labelledby="txtboxLabel"></div>

<!-- Multi-line text area -->
<div id="txtboxMultilineLabel">Enter the tags for the article</div>
<div
  role="textbox"
  contenteditable="true"
  aria-multiline="true"
  aria-labelledby="txtboxMultilineLabel"
  aria-required="true"></div>

语义化元素更简洁，并且不需要 JavaScript 来支持 textbox 功能。

<label for="txtbox">Enter your five-digit zip code</label>
<input type="text" placeholder="5-digit zip code" id="txtbox" />

<!-- Multi-line text area -->
<label for="txtboxMultiline">Enter the tags for the article</label>
<textarea id="txtboxMultiline" required></textarea>

当文本字段是只读的时，请通过在元素上设置 aria-readonly="true" 来指示。

相关的 ARIA 属性

aria-activedescendant 属性

以某个 ID 作为其值，该 ID 指向的元素要么是具有 DOM 焦点之元素的后代，要么是通过 aria-owns 属性指示的逻辑后代。它指示了当元素获得焦点时，它作为复合控件（如 combobox）的一部分。例如，在 combobox 中，焦点可以保留在 textbox 上，同时 textbox 元素上的 aria-activedescendant 属性引用了由 textbox 控制的弹出列表框的后代。作为焦点变化，此属性必须以编程方式更新。

aria-autocomplete 属性

指示用户在字段中的输入是否以及如何触发预期值预测的显示。它支持以下值：

• inline：预测文本会插入到插入符号之后。
• list：预测文本会作为一组值显示。
• both：预测文本会作为一组值显示，用于完成一个值的文本会插入到插入符号之后。
• none（默认）：不提供预测文本。

如果设置了 list 或 both，还应包含 aria-controls 和 aria-haspopup 属性。aria-controls 的值是要包含建议值列表的元素的 ID。此外，textbox 或具有 combobox 角色的包含元素必须有一个 aria-haspopup 值，该值与包含建议值列表的元素的角色匹配。

aria-multiline 属性

如果设置了 aria-multiline="true"，则辅助技术会告知用户该 textbox 支持多行输入，并期望按 Enter 或 Return 会换行而不是提交表单。ARIA 不会改变元素的行为；此功能必须由开发人员控制。如果设置为 false，或省略该属性默认为 false，则用户期望该控件是单行文本框，按 Enter 或 Return 会提交表单。

aria-placeholder 属性

表示一个提示（单词或短语），用于告知用户在文本字段中输入什么。提示应为示例值或预期的格式的简要描述。此信息不应作为标签的替代：标签是可聚焦的、永久的、指示预期信息的类型，并增加了焦点设置到控件的命中区域，而占位符文本只是关于预期值的临时提示，如果实现不当可能会降低可访问性。当控件的值为空字符串时（例如，当控件首次获得焦点时，以及当用户删除先前输入的值时），占位符应可见。与其使用 aria-placeholder，不如使用具有 placeholder 属性的语义化 <input type="text"> 或 <textarea>。

aria-readonly 属性

指示用户无法修改文本字段的值。与其使用 aria-readonly，不如使用具有 readonly 属性的语义化 <input type="text"> 或 <textarea>。

aria-required 属性

指示在提交之前必须为该字段提供值。与其使用 aria-required，不如使用具有 required 属性的语义化 <input type="text"> 或 <textarea>。

键盘交互

在单行使用中（当 aria-multiline 为 false 或未使用时），按 Return 或 Enter 键会提交表单。在多行使用中（当 aria-multiline 为 true 时），按 Return 或 Enter 键会插入换行符。

JavaScript 功能

所有与任何属性和状态相关的功能都必须得到维护，并且需要处理 Enter 或 Return 键在单行文本框上的表单提交。

焦点事件处理程序和 aria-activedescendant 属性

如果您正在实现一个复合控件，例如由文本框和列表框组成的 combobox，您需要使用处理程序来管理 aria-activedescendant 属性。在使用此技术之前，请确保您需要定位的浏览器当前支持它。有关 aria-descendant 的更多信息，请参阅 aria-descendant 规范。

对用户代理和辅助技术的可能影响

当 textbox 角色被添加到元素上，或者此类元素变得可见时，用户代理应执行以下操作：

• 在操作系统辅助功能 API 中将元素公开为具有 textbox 角色。
• 如果操作系统辅助功能 API 支持，则使用该 API 触发一个可访问的 textbox 事件。

辅助技术产品应监听此类事件并相应地通知用户。

• 屏幕阅读器应在焦点首次落入 textbox 时宣布其标签和角色。如果它还包含内容，则应像普通 textbox 一样宣布。
• 屏幕放大器可能会放大 textbox。

示例

示例 1：在 HTML 代码中为单行输入添加角色

下面的代码片段展示了如何将 textbox 角色直接添加到 HTML 源代码中。

<div role="textbox" contenteditable="true"></div>

示例 2：在 HTML 代码中为多行输入添加角色

下面的代码片段展示了如何将 textbox 角色直接添加到 HTML 源代码中。

<div role="textbox" contenteditable="true" aria-multiline="true"></div>

最佳实践

请务必将 contenteditable="true" 属性添加到应用了此角色的 HTML 元素。即使您将 aria-readonly 设置为 true，也要这样做；这样，您就可以传达内容在非只读时是可编辑的。

另见

• ARIA: search 角色