SuperAPI AI 工具集

accessibility-guide

前端与建站

查看项目

更新于 10-16 04:18

技能介绍

用途

本技能是 SAP fundamental-styles 组件库的无障碍编写指南,适用于以下场景:为组件文档编写 HTML 示例、创建新的组件演示、审查组件的无障碍性、修复示例中的无障碍问题,以及解答关于 ARIA 角色与属性的疑问。

核心原则

1. 语义化 HTML 优先

在可能的情况下,始终优先使用原生 HTML 元素而非 ARIA 角色。原生元素自带键盘支持、焦点管理和语义,无需 JavaScript。例如应使用 <button>、<nav>、<header>、<input type="checkbox" />,而不是 <div role="button">、<div role="navigation">、<div role="banner">、<div role="checkbox">。

2. 标签必须正确关联

每个表单控件都必须有可访问的标签。推荐使用 for 与 id 关联,也可使用嵌套 label,或对复杂标签使用 aria-labelledby。避免标签与控件之间缺少连接,或引用不存在的 ID。

3. ID 引用必须有效

使用 aria-labelledby、aria-describedby 或 for 属性时,被引用的 ID 必须存在于 DOM 中。校验清单包括:每个 for 指向存在的 id;每个 aria-labelledby、aria-describedby、aria-controls 引用存在的 ID;ID 在页面内唯一。

ARIA 角色要求

需要配套属性的角色

  • 范围控件(slider、spinbutton、progressbar、scrollbar):必须包含 aria-valuenow、aria-valuemin、aria-valuemax;可选推荐 aria-valuetext。
  • 可选中控件(checkbox、radio、switch、option、menuitemcheckbox、menuitemradio、tab):checkbox、radio、switch、menuitemcheckbox、menuitemradio 必须包含 aria-checked;option、tab 必须包含 aria-selected。
  • 可展开控件(combobox、disclosure、带子菜单的 menu):必须包含 aria-expanded,展开时为 "true",折叠时为 "false"。
  • 弹窗触发器(combobox、菜单按钮):必须包含 aria-haspopup,取值为 "menu"、"listbox"、"tree"、"grid"、"dialog" 或 "true"。
  • 集合位置属性(aria-posinset、aria-setsize):当并非所有项都在 DOM 中时(如虚拟滚动、懒加载)必须成对使用;若总数未知可设 aria-setsize="-1"。
  • 方向(menu、menubar、toolbar、listbox、slider、tablist、tree):部分角色有隐式方向,需要时显式覆盖。menu 隐式为 vertical,menubar 隐式为 horizontal,slider 隐式为 horizontal,tablist 隐式为 horizontal。
  • 模态对话框:必须包含 aria-modal="true"(非模态为 "false"),以及 aria-labelledby 或 aria-label 为对话框命名。

复合组件的容器要求

  • 单选组:radiogroup 必须包含 radio 元素;组内只能有一个 aria-checked="true";组内所有 radio 都应有 tabindex。
  • 标签页界面:tablist 必须包含 tab 元素;每个 tab 应有 aria-controls 指向其 tabpanel;每个 tabpanel 应有 aria-labelledby 指向其 tab;同一时间只有一个 tab 的 aria-selected="true";选中的 tab 为 tabindex="0",其余为 tabindex="-1"。
  • 菜单/菜单栏:menu 或 menubar 必须包含 menuitem、menuitemcheckbox 或 menuitemradio 元素;role="separator" 允许但不计入集合大小。
  • 列表框:listbox 必须包含 option 元素。
  • 树:tree 必须包含 treeitem 元素;父级 treeitem 需要 aria-expanded,推荐 aria-level。
  • 网格/表格:grid 或 table 必须包含 row,其中包含 gridcell 或 cell;优先使用原生 HTML <table>。

常见组件模式

  • 带标签和错误消息的表单:for 与 id 连接标签与输入;aria-invalid="true" 表示错误状态;aria-describedby 指向错误消息 ID;required 用于校验。
  • 带图标的按钮:仅图标按钮必须有 aria-label 或 aria-labelledby;装饰性图标应设 aria-hidden="true";不能仅靠图标传达含义。
  • 选择/下拉:可使用原生 <select>,或自定义 combobox 模式,其中 combobox 具有 aria-expanded、aria-haspopup="listbox"、aria-owns,listbox 具有匹配 id,option 具有 aria-selected,按钮为 tabindex="-1"。
  • 复选框组:使用 <fieldset> 和 <legend> 分组;每个复选框有唯一 id 和匹配的 for;装饰性勾选元素设 aria-hidden="true"。
  • 对话框/模态:role="dialog" 配合 aria-modal="true";aria-labelledby 指向标题 ID;关闭按钮有 aria-label;激活时焦点应被限制在对话框内;打开时第一个可聚焦元素应获得焦点。
  • 标签页:tablist 包含 tab,每个 tab 有 aria-selected、aria-controls、id 和 tabindex。

限制

资料未提供该技能的安装命令、收费方式、支持平台或具体版本信息,这些内容暂未提供。