ARIA：文字框角色

textbox 角色用於標識允許輸入自由格式文字的元素。在可能的情況下，不要使用此角色，而是使用帶有 <input> 元素 type="text"（用於單行輸入）或 <textarea> 元素（用於多行輸入）。

描述

當元素具有 textbox 角色時，瀏覽器會向輔助技術傳送可訪問的文字框事件，然後輔助技術可以向用戶通知該事件。

預設情況下為單行輸入，其中 Return 或 Enter 提交表單；在這種情況下，最好使用 HTML <input> 並設定 type="text"。要建立支援換行的多行文字框（如 HTML <textarea> 中），請設定 aria-multiline="true"。包含 HTML contenteditable 屬性可確保文字節點可編輯。

html

<!-- Simple text input field -->
<div id="txtboxLabel">Enter your five-digit zipcode</div>
<div
  role="textbox"
  contenteditable="true"
  aria-placeholder="5-digit zipcode"
  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 來支援文字框功能。

html

<label for="txtbox">Enter your five-digit zipcode</label>
<input type="text" placeholder="5-digit zipcode" 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，它要麼是具有 DOM 焦點的元素的後代，要麼是 aria-owns 屬性指示的邏輯後代，它指示該元素何時獲得焦點，何時是組合元件（如 combobox）的一部分。例如，在組合框中，焦點可能保留在文字框上，而文字框元素上的 aria-activedescendant 值則引用文字框控制的彈出列表框的後代。此屬性必須在焦點更改時以程式設計方式更新。

aria-autocomplete 屬性

指示使用者在欄位中輸入的內容是否以及如何觸發對預期值的預測顯示。它支援以下值

inline：預測文字插入在插入符號之後。
list：預測文字顯示為值的集合。
both：預測文字顯示為值的集合，並在插入符號之後插入完成一個值所需的文字。
none（預設值）：不提供預測文字。

如果設定了 list 或 both，則還應包含 aria-controls 和 aria-haspopup 屬性。aria-controls 的值為包含建議值列表的元素的 ID。此外，文字框或具有角色 combobox 的包含元素的值與包含建議值列表的元素的角色相匹配，用於 aria-haspopup。

aria-multiline 屬性

如果設定了 aria-multiline="true"，則 AT 會通知使用者文字框支援多行輸入，並期望 Enter 或 Return 建立換行符而不是提交表單。ARIA 不會更改元素的行為；相反，此功能必須由開發人員控制。如果設定為 false，或者屬性被省略並預設為 false，則使用者期望控制元件為單行文字框，並且 Enter 或 Return 提交表單。

aria-placeholder 屬性

表示一個提示（單詞或短語），提示使用者在文字欄位中輸入什麼內容。提示應該是一個示例值或預期格式的簡要描述。此資訊不應替代標籤：標籤可聚焦、永久存在、指示期望的資訊型別，並增加設定控制元件焦點的點選區域，而佔位符文字只是關於預期值的臨時提示，如果實現不正確，可能會降低可訪問性。當控制元件的值為空字串時，例如控制元件首次獲得焦點時以及使用者刪除之前輸入的值時，佔位符應可見。不要使用aria-placeholder，而是使用語義化的<input type="text">或<textarea>以及placeholder屬性。

aria-readonly 屬性

指示使用者無法修改文字欄位的值。不要使用aria-readonly，而是使用語義化的<input type="text">或<textarea>以及readonly屬性。

aria-required 屬性

指示在提交欄位之前必須為此欄位提供值。不要使用aria-required，而是使用語義化的<input type="text">或<textarea>以及required屬性。

鍵盤互動

在單行使用中（當aria-multiline為false或未使用時），Return或Enter鍵提交表單。在多行使用中（當aria-multiline為true時），Return或Enter鍵插入換行符。

JavaScript 功能

必須維護與任何和所有屬性和狀態關聯的所有功能，並且需要處理單行文字框中回車或 Enter 鍵的表單提交。

焦點事件處理程式和 aria-activedescendant 屬性: 如果您正在實現複合小部件，例如由文字框和列表框組成的組合框，則需要使用處理程式管理aria-activedescendant屬性。在使用此技術之前，請確保您需要定位的瀏覽器當前支援它。有關更多資訊，請參閱aria-descendant 的規範。

注意：最佳實踐是使用型別為“text”的<input>元素或<textarea>元素，而不是 ARIA 文字框角色。當使用任一語義元素時，ARIA 文字框角色是不必要的。請參閱在 HTML 中使用 ARIA 的說明。

對使用者代理和輔助技術的可能影響

當textbox角色新增到元素或此類元素變得可見時，使用者代理應執行以下操作

將元素公開為在作業系統可訪問性 API 中具有文字框角色。
如果作業系統可訪問性 API 支援，則使用作業系統可訪問性 API 觸發可訪問文字框事件。

輔助技術產品應偵聽此類事件並相應地通知使用者

螢幕閱讀器應在焦點首次落在文字框上時宣佈其標籤和角色。如果它還包含內容，則應像普通文字框一樣宣佈。
螢幕放大鏡可以放大文字框。

注意：關於輔助技術如何處理此技術的觀點可能存在差異。上面提供的資訊是這些觀點之一，並且體驗可能會有所不同。

示例

示例 1：在 HTML 程式碼中新增單行輸入的角色

以下程式碼段顯示瞭如何將文字框角色直接新增到 HTML 原始碼中。

html

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

示例 2：在 HTML 程式碼中新增多行輸入的角色

以下程式碼段顯示瞭如何將文字框角色直接新增到 HTML 原始碼中。

html

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

最佳實踐

請務必將contenteditable="true"屬性新增到應用此角色的 HTML 元素。即使您將aria-readonly設定為true，也應這樣做；這樣，您可以傳達如果內容不是隻讀，則內容將是可編輯的。

另請參閱

ARIA：搜尋角色