跳至主要内容

其他

辅助功能警告

在 GitHub 上编辑此页面

辅助功能(缩写为 a11y)并不总是容易实现,但如果你编写了不可访问的标记,Svelte 将在编译时向你发出警告,以提供帮助。但是,请记住,许多辅助功能问题只能在运行时使用其他自动化工具和通过手动测试应用程序才能识别出来。

在你的具体用例中,有些警告可能是错误的。你可以通过在导致警告的行上方放置 <!-- svelte-ignore a11y-<code> --> 注释来禁用此类误报。示例

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

以下是 Svelte 将为你执行的辅助功能检查列表。

a11y-accesskey

强制元素上没有 accesskey。访问键是 HTML 属性,允许 Web 开发人员为元素分配键盘快捷键。键盘快捷键与屏幕阅读器和仅键盘用户使用的键盘命令之间的不一致会造成无障碍方面的复杂性。为了避免复杂性,不应使用访问键。

<!-- 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 角色、状态和属性。这通常是因为它们不可见,例如 metahtmlscriptstyle。此规则强制这些 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> 元素。这些元素在语义上更有意义,并且将具有内置的键处理功能。例如,空格键Enter 键 将触发 <button>Enter 键 将触发 <a> 元素。

如果需要非交互式元素,则 on:click 应附带一个 on:keyupon: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 元素播报为图像。无需使用诸如 imagephoto 和/或 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 属性使用正确类型的 value。例如,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 角色、状态和属性。这通常是因为它们不可见,例如 metahtmlscriptstyle。此规则强制执行这些 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

强制标题元素(h1h2 等)和锚点具有内容,并且内容可供屏幕阅读器访问

<!-- 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:mouseoveron:mouseout 分别与 on:focuson: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 角色包括 articlebannercomplementaryimglistitemmainregiontooltip

<!-- 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 角色 包括 articlebannercomplementaryimglistitemmainregiontooltip

<!-- `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 角色包括 buttonlinkcheckboxmenuitemmenuitemcheckboxmenuitemradiooptionradiosearchboxswitchtextbox

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

a11y-no-noninteractive-tabindex

标签键导航应仅限于页面上可以交互的元素。

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

a11y-no-static-element-interactions

具有交互处理程序(如 click)的元素(如 <div>)必须具有 ARIA 角色。

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

a11y-positive-tabindex

避免使用正的 tabindex 属性值。这会将元素移出预期的标签顺序,给键盘用户带来混乱的体验。

<!-- 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" />
上一个 常见问题
下一个 TypeScript