無障礙警告

在 GitHub 上編輯此頁面

無障礙性（簡稱為 a11y）並不容易做到，但 Svelte 會在編譯時發出警告，如果你寫出無法存取的標記。不過，請記住，許多無障礙性問題只能在執行時使用其他自動化工具和手動測試應用程式時才能識別。

在你的具體使用案例中，某些警告可能是錯誤的。你可以透過在導致警告的行上方放置 <!-- svelte-ignore a11y-<code> --> 註解來停用這些誤報。範例

<!-- svelte-ignore a11y-autofocus -->
<input autofocus />

以下列出 Svelte 將為你執行的無障礙性檢查。

a11y-accesskey永久連結

強制元素上沒有 accesskey。存取鍵是 HTML 屬性，允許網路開發人員將鍵盤快速鍵指派給元素。鍵盤快速鍵與螢幕閱讀器和僅使用鍵盤的使用者所使用的鍵盤命令之間的不一致會造成無障礙性問題。為了避免問題，不應使用存取鍵。

<!-- A11y: Avoid using accesskey -->
<div accessKey="z" />

a11y-aria-activedescendant-has-tabindex永久連結

具有 aria-activedescendant 的元素必須可以按 Tab 鍵，因此它必須具有內在的 tabindex 或將 tabindex 宣告為屬性。

<!-- A11y: Elements with attribute aria-activedescendant should have tabindex value -->
<div aria-activedescendant="some-id" />

a11y-aria-attributes永久連結

某些保留的 DOM 元素不支援 ARIA 角色、狀態和屬性。這通常是因為它們不可見，例如 meta、html、script、style。此規則強制這些 DOM 元素不包含 aria-* 屬性。

<!-- A11y: <meta> should not have aria-* attributes -->
<meta aria-hidden="false" />

a11y-autofocus永久連結

強制元素上不使用 autofocus。自動對焦元素可能會對視力和非視力使用者造成可用性問題。

<!-- A11y: Avoid using autofocus -->
<input autofocus />

a11y-click-events-have-key-events永久連結

強制具有 on:click 事件的可見非互動元素附帶鍵盤事件處理常式。

使用者應首先考慮互動式元素是否更合適，例如動作的 <button type="button"> 元素或導覽的 <a> 元素。這些元素在語意上更有意義，且會內建鍵盤處理功能。例如，Space 和 Enter 會觸發 <button>，而 Enter 會觸發 <a> 元素。

如果需要非互動式元素，則 on:click 應搭配 on:keyup 或 on:keydown 處理常式，讓使用者能透過鍵盤執行等效動作。為了讓使用者能觸發按鍵，元素也需要透過新增 tabindex 來設定焦點。雖然 on:keypress 處理常式也會消除此警告，但請注意 keypress 事件已不建議使用。

<!-- A11y: visible, non-interactive elements with an on:click event must be accompanied by a keyboard event handler. -->
<div on:click={() => {}} />

鍵盤編碼對於無法使用滑鼠的身障人士、AT 相容性以及螢幕閱讀器使用者非常重要。

a11y-distracting-elements永久連結

強制執行不使用任何干擾元素。視覺上干擾的元素會導致視障使用者產生無障礙問題。此類元素很可能已不建議使用，應避免使用。

以下元素在視覺上會造成干擾：<marquee> 和 <blink>。

<!-- A11y: Avoid <marquee> elements -->
<marquee />

a11y-hidden永久連結

某些 DOM 元素對螢幕閱讀器導覽很有用，不應隱藏。

<!-- A11y: <h2> element should not be hidden -->
<h2 aria-hidden="true">invisible header</h2>

a11y-img-redundant-alt永久連結

強制執行 img alt 屬性不包含字詞 image、picture 或 photo。螢幕閱讀器已將 img 元素宣告為影像。無需使用例如 image、photo 和/或 picture 等字詞。

<img src="foo" alt="Foo eating a sandwich." />

<!-- aria-hidden, won't be announced by screen reader -->
<img src="bar" aria-hidden="true" alt="Picture of me taking a photo of an image" />

<!-- A11y: Screen readers already announce <img> elements as an image. -->
<img src="foo" alt="Photo of foo being weird." />

<!-- A11y: Screen readers already announce <img> elements as an image. -->
<img src="bar" alt="Image of me at a bar!" />

<!-- A11y: Screen readers already announce <img> elements as an image. -->
<img src="foo" alt="Picture of baz fixing a bug." />

a11y-incorrect-aria-attribute-type永久連結

強制執行只對 aria 屬性使用正確類型的值。例如，aria-hidden 應只接收布林值。

<!-- A11y: The value of 'aria-hidden' must be exactly one of true or false -->
<div aria-hidden="yes" />

a11y-invalid-attribute永久連結

強制執行對無障礙性很重要的屬性具有有效值。例如，href 不應為空、'#' 或 javascript:。

<!-- A11y: '' is not a valid href attribute -->
<a href="">invalid</a>

a11y-interactive-supports-focus永久連結

強制執行具有互動式角色和互動式處理常式 (滑鼠或按鍵) 的元素必須可聚焦或可使用 Tab 鍵。

<!-- A11y: Elements with the 'button' interactive role must have a tabindex value. -->
<div role="button" on:keypress={() => {}} />

a11y-label-has-associated-control永久連結

強制執行標籤標籤具有文字標籤和關聯控制項。

有兩種支援的方式可將標籤與控制項關聯

• 將控制項包覆在標籤標籤中。
• 將 for 新增至標籤，並將其指定給頁面上輸入項目的 ID。

<label for="id">B</label>

<label>C <input type="text" /></label>

<!-- A11y: A form label must be associated with a control. -->
<label>A</label>

a11y-media-has-caption永久連結

提供媒體字幕對於失聰使用者來說非常重要，可讓他們理解內容。字幕應為對話、音效、相關音樂提示和其他相關音訊資訊的轉錄或翻譯。這不僅對無障礙性很重要，而且在媒體無法使用的情況下，對所有使用者來說也很有用 (類似於影像無法載入時影像上的 alt 文字)。

字幕應包含所有重要且相關的資訊，以了解對應的媒體。這表示字幕可能不是媒體內容中對話的 1:1 對應。但是，具有 muted 屬性的影片元件不需要字幕。

<video><track kind="captions" /></video>

<audio muted />

<!-- A11y: Media elements must have a <track kind=\"captions\"> -->
<video />

<!-- A11y: Media elements must have a <track kind=\"captions\"> -->
<video><track /></video>

a11y-misplaced-role永久連結

某些保留的 DOM 元素不支援 ARIA 角色、狀態和屬性。這通常是因為它們不可見，例如 meta、html、script、style。此規則強制執行這些 DOM 元素不包含 role 屬性。

<!-- A11y: <meta> should not have role attribute -->
<meta role="tooltip" />

a11y-misplaced-scope永久連結

scope 屬性只能用於 <th> 元素。

<!-- A11y: The scope attribute should only be used with <th> elements -->
<div scope="row" />

a11y-missing-attribute永久連結

強制要求元素具備無障礙存取所需的屬性。這包括以下檢查

• <a> 應具有 href（除非它是 定義片段的標籤）
• <area> 應具有 alt、aria-label 或 aria-labelledby
• <html> 應具有 lang
• <iframe> 應具有 title
• <img> 應具有 alt
• <object> 應具有 title、aria-label 或 aria-labelledby
• <input type="image"> 應具有 alt、aria-label 或 aria-labelledby

<!-- A11y: <input type=\"image\"> element should have an alt, aria-label or aria-labelledby attribute -->
<input type="image" />

<!-- A11y: <html> element should have a lang attribute -->
<html />

<!-- A11y: <a> element should have an href attribute -->
<a>text</a>

a11y-missing-content永久連結

強制要求標題元素（h1、h2 等）和錨點具有內容，且內容可供螢幕閱讀器存取

<!-- A11y: <a> element should have child content -->
<a href="/foo" />

<!-- A11y: <h1> element should have child content -->
<h1 />

a11y-mouse-events-have-key-events永久連結

強制要求 on:mouseover 和 on:mouseout 分別伴隨著 on:focus 和 on:blur。這有助於確保由這些滑鼠事件觸發的任何功能也都能讓鍵盤使用者存取。

<!-- A11y: on:mouseover must be accompanied by on:focus -->
<div on:mouseover={handleMouseover} />

<!-- A11y: on:mouseout must be accompanied by on:blur -->
<div on:mouseout={handleMouseout} />

a11y-no-redundant-roles永久連結

有些 HTML 元素具有預設的 ARIA 角色。為這些元素指定瀏覽器已設定的 ARIA 角色 沒有作用，而且是多餘的。

<!-- A11y: Redundant role 'button' -->
<button role="button" />

<!-- A11y: Redundant role 'img' -->
<img role="img" src="foo.jpg" />

a11y-no-interactive-element-to-noninteractive-role永久連結

WAI-ARIA 角色不應被用於將互動式元素轉換為非互動式元素。非互動式 ARIA 角色包括 article、banner、complementary、img、listitem、main、region 和 tooltip。

<!-- A11y: <textarea> cannot have role 'listitem' -->
<textarea role="listitem" />

a11y-no-noninteractive-element-interactions永久連結

非互動元素不支援事件處理常式（滑鼠和鍵盤處理常式）。非互動元素包括 <main>、<area>、<h1>（<h2> 等）、<p>、<img>、<li>、<ul> 和 <ol>。非互動 WAI-ARIA 角色 包括 article、banner、complementary、img、listitem、main、region 和 tooltip。

<!-- `A11y: Non-interactive element <li> should not be assigned mouse or keyboard event listeners.` -->
<li on:click={() => {}} />

<!-- `A11y: Non-interactive element <div> should not be assigned mouse or keyboard event listeners.` -->
<div role="listitem" on:click={() => {}} />

a11y-no-noninteractive-element-to-interactive-role永久連結

WAI-ARIA 角色不應使用於將非互動元素轉換為互動元素。互動式 ARIA 角色包括 button、link、checkbox、menuitem、menuitemcheckbox、menuitemradio、option、radio、searchbox、switch 和 textbox。

<!-- A11y: Non-interactive element <h3> cannot have interactive role 'searchbox' -->
<h3 role="searchbox">Button</h3>

a11y-no-noninteractive-tabindex永久連結

Tab 鍵導覽應限制在頁面上可以互動的元素。

<!-- A11y: noninteractive element cannot have nonnegative tabIndex value -->
<div tabindex="0" />

a11y-no-static-element-interactions永久連結

具有互動處理常式的元素，例如 <div>（例如 click），必須具有 ARIA 角色。

<!-- A11y: <div> with click handler must have an ARIA role -->
<div on:click={() => ''} />

a11y-positive-tabindex永久連結

避免正向 tabindex 屬性值。這會將元素移出預期的 Tab 順序，對鍵盤使用者造成混淆的體驗。

<!-- A11y: avoid tabindex values above zero -->
<div tabindex="1" />

a11y-role-has-required-aria-props永久連結

具有 ARIA 角色的元素必須具備該角色所需的所有屬性。

<!-- A11y: A11y: Elements with the ARIA role "checkbox" must have the following attributes defined: "aria-checked" -->
<span role="checkbox" aria-labelledby="foo" tabindex="0" />

a11y-role-supports-aria-props永久連結

定義明確或隱含角色的元素僅包含該角色支援的 aria-* 屬性。

<!-- A11y: The attribute 'aria-multiline' is not supported by the role 'link'. -->
<div role="link" aria-multiline />

<!-- A11y: The attribute 'aria-required' is not supported by the role 'listitem'. This role is implicit on the element <li>. -->
<li aria-required />

a11y-structure永久連結

強制執行某些 DOM 元素具有正確的結構。

<!-- A11y: <figcaption> must be an immediate child of <figure> -->
<div>
	<figcaption>Image caption</figcaption>
</div>

a11y-unknown-aria-attribute永久連結

強制執行僅使用已知的 ARIA 屬性。這是根據 WAI-ARIA 狀態和屬性規範 制定的。

<!-- A11y: Unknown aria attribute 'aria-labeledby' (did you mean 'labelledby'?) -->
<input type="image" aria-labeledby="foo" />

a11y-unknown-role永久連結

具有 ARIA 角色的元素必須使用有效的、非抽象的 ARIA 角色。可以在 WAI-ARIA 網站找到角色定義的參考。

<!-- A11y: Unknown role 'toooltip' (did you mean 'tooltip'?) -->
<div role="toooltip" />