aria-autocomplete

何时使用

在用户输入时提供建议的自定义 role="combobox" 或 role="textbox" 上使用。该属性告知辅助技术预期的自动完成行为类型，使用户能够预判应在输入框本身、弹出列表还是两者中查找内容。

不要将其放在没有建议机制的普通原生 <input type="text"> 上——没有任何内容需要播报。

该属性常与 HTML autocomplete 属性混淆，但两者无关。HTML autocomplete（如 "email"、"current-password"、"street-address" 等）告知浏览器如何填充字段；aria-autocomplete 告知辅助技术开发者实现了哪种界面交互模式。两者可同时出现在同一输入框上，互不冲突。

行为说明

接受四个标记值：

• "none" — 默认值。文本框不提供自动完成。通常无需显式设置。
• "inline" — 用户输入时，建议文本会追加到输入框本身，通常处于选中状态，以便下次按键可将其覆盖。
• "list" — 建议显示在单独的弹出框中（通常为 role="listbox"）。输入框的值不会自动更改。
• "both" — 两者兼有：弹出列表可见，同时最优建议内联插入输入框。

使用与实际实现相符的值。若组合框显示下拉选项但不在用户输入时修改输入框内容，则应使用 "list" 而非 "both"。

常见失误

• 与 HTML autocomplete 属性混淆。两者外观相似，功能不同，通常两者都需要使用。
• 设置 aria-autocomplete="list" 却未同时设置 aria-controls 指向列表框，也未设置 aria-expanded 跟踪展开/收起状态。
• 设置 aria-autocomplete="both" 而输入框实际上从不自动填充。用户听到该功能提示后等待内联建议，却始终没有出现。
• 将 aria-autocomplete 放在非文本框或组合框的控件上——例如按钮。该属性会被忽略。
• 忘记为列表中当前高亮选项管理 aria-activedescendant。用户听到建议存在，却无法得知哪个选项当前处于活动状态。
• 硬编码 aria-autocomplete="list" 而不检查屏幕阅读器输出。许多辅助技术的播报模式不一致，使用错误的标记值会产生令人困惑的表述。

示例

<label for="city">City</label>
<input
  id="city"
  role="combobox"
  type="text"
  autocomplete="address-level2"
  aria-autocomplete="list"
  aria-controls="city-listbox"
  aria-expanded="true"
  aria-activedescendant="city-opt-3"
>
<ul id="city-listbox" role="listbox">
  <li id="city-opt-1" role="option">Bristol</li>
  <li id="city-opt-2" role="option">Birmingham</li>
  <li id="city-opt-3" role="option">Brighton</li>
</ul>