ARIA: document 角色

描述

document 角色用於包含輔助技術使用者可能希望以閱讀模式瀏覽的內容的頂級容器。僅在複雜複合 小部件 或 應用程式 中可獲得焦點的（focusable）部分內才有用，document 角色會通知輔助技術將讀取上下文切換回閱讀模式：document 角色告知具有閱讀或瀏覽模式的輔助技術使用文件模式來讀取此元素包含的內容。

<div role="dialog">
  …
  <div id="InfoText" role="document" tabindex="0">
    <p>Some informational text goes here.</p>
  </div>
  …
  <button>Close</button>
</div>

此示例顯示了一個 對話方塊，這是一個複雜複合小部件角色，其中包含一些控制元件和一個包含一些資訊文字的部分，輔助技術使用者在選項卡（Tab）到該部分時可以進入閱讀模式。

預設情況下，網頁被視為文件；輔助技術（AT）在進入新網頁時會進入瀏覽或閱讀模式。此模式可以透過各種角色進行更改，包括小部件（widget）角色和應用程式（application）角色。document 角色會將輔助技術帶回瀏覽或閱讀模式。

通常放置在應用程式角色或其他互動式小部件角色內，document 角色用於指示覆雜複合小部件中輔助技術使用者應使用其瀏覽或虛擬閱讀模式（如果可用）來閱讀的部分。

由於具有閱讀模式的輔助技術預設對除具有小部件或應用程式角色設定的所有元素都採用該模式，因此 document 角色僅對小部件或應用程式內應作為靜態富文字讀取的可獲取焦點元素有用。透過向包含小部件內文字的元素新增 role="document" 和 tabindex="0"，螢幕閱讀器使用者可以透過按 Tab 鍵將焦點設定在 document 元素上，並使用螢幕閱讀器的閱讀游標讀取文字。

輔助技術應將上下文切換回文件模式，可能從為父級的動態上下文重新配置的控制元件中攔截，重新啟用標準輸入事件，例如 Up 或 Down 箭頭鍵盤事件，以控制閱讀游標。

與 article 角色不同，document 角色與具有 document 角色的其他元素沒有任何關聯，它僅僅與包含它的複合小部件有關。文章（article）可以有關聯的文章。

關聯的 WAI-ARIA 角色、狀態和屬性

aria-expanded

如果 document 元素是可摺疊的，則包含 true 或 false 的值，以指示 document 當前是展開還是摺疊。其他值包括預設的 undefined，表示 document 不可摺疊。

tabindex="0"

用於使其可獲得焦點，以便輔助技術使用者可以選項卡（Tab）到它並立即開始閱讀。

鍵盤互動

應透過在該元素上設定 tabindex="0" 屬性/值對使其可獲得焦點。這樣，使用者就可以選項卡（Tab）到它，閱讀模式會自動呼叫，並且內容可以立即被讀取。

所需的 JavaScript 功能

無，除非任何屬性需要。例如，如果 document 是可摺疊的，那麼 aria-expanded 的狀態和值必須被維護。

示例

一個例子是 Gmail 和單個對話檢視。GMail 是一個 Web 應用程式。在 Gmail 中，大多數使用者代理互動都被應用程式劫持。但是，當鍵盤焦點設定在包含對話主題的單個對話的起始標題上時，螢幕閱讀器使用者可以使用閱讀模式命令來閱讀訊息，展開或摺疊它們，並進行操作。一旦焦點透過啟用“後退”按鈕或按下關聯的鍵盤快捷鍵返回到訊息列表，就會再次呼叫直接應用程式互動模式，並且使用者可以使用 箭頭 鍵將焦點移到列表中的其他對話。

最佳實踐

始終確保具有 document 角色的項可獲得焦點，透過設定值為 0 的 tabindex 屬性。這也會將其包含在選項卡（Tab）順序中。

新增優勢

document 角色是一種透過明確說明這是使用者應使用標準螢幕閱讀器命令閱讀的內容來間接控制輔助技術行為的簡便方法。

規範

另見

• ARIA: widget 角色
• ARIA: application 角色