aria-disabled

适用场景

当按钮、链接、输入框或复合控件当前不可操作，但仍应出现在 Tab 顺序中以便用户发现并了解其禁用原因时，设置 aria-disabled="true" 并在视觉上清晰标示禁用状态。

与相关属性的对比：

• HTML disabled（用于 <button>、<input>、<select>、<textarea>、<fieldset>）——将控件完全从 Tab 顺序中移除，忽略点击，且不提交控件值。当用户对该控件无任何操作可执行时使用此属性。
• aria-disabled="true"——屏幕阅读器播报”已变暗”或”不可用”，但元素仍可聚焦。必须同时阻止点击处理程序执行。适用于自定义控件、不支持 disabled 的 <a> 标签，或禁用状态需要提示框说明原因的场景。
• aria-readonly——值不可更改，但控件仍可操作且可聚焦。用户可复制其值，表单仍会提交该值。
• aria-hidden——将元素完全从无障碍树中移除，目的不同：隐藏而非禁用。

保持同步

有效值为 "true" 和 "false"。控件启用时默认值为 "false" 或省略——无需在每个活动控件上都渲染 aria-disabled="false"。

当 aria-disabled="true" 时：

• 阻止点击处理程序执行。该属性本身不会拦截事件。
• 阻止默认键盘激活（Enter、Space）。
• 确保视觉样式能清晰传达禁用状态；检查其是否仍符合 WCAG 1.4.11 非文本对比度要求（禁用外观明确豁免，但清晰的视觉提示仍是更佳实践）。

常见错误

• 使用 aria-disabled="true" 但未阻止点击处理程序——元素看起来变暗，但仍会触发操作。
• 在同一元素上同时使用 disabled 和 aria-disabled。原生属性已暴露该状态，重复设置是冗余的。
• 在 <a> 上使用 aria-disabled 时未同时移除 href 或阻止默认行为——链接仍会跳转。
• 禁用控件时未说明原因。WCAG 3.3.1 要求提供错误提示或使用说明。
• 将 aria-disabled 与 aria-hidden 混淆。禁用的元素仍保留在无障碍树中；隐藏的元素则从树中消失。

示例

<button type="submit" aria-disabled="true" aria-describedby="submit-help">
  Submit order
</button>
<p id="submit-help">Add at least one item to your cart to enable submit.</p>