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 角色