在 React 中使用 aria-label 为屏幕阅读器提供替代文本时，需注意：NVDA 仅在元素无可见可读文本内容时才采纳 aria-label；若同时存在显示文本，需用 aria-hidden="true" 隐藏其可访问性树暴露，才能使 aria-label 生效。
在 react 中使用 `aria-label` 为屏幕阅读器提供替代文本时，需注意：nvda 仅在元素**无可见可读文本内容**时才采纳 `aria-label`；若同时存在显示文本，需用 `aria-hidden="true"` 隐藏其可访问性树暴露，才能使 `aria-label` 生效。
在构建无障碍 Web 应用时，确保屏幕阅读器（如 NVDA）播报语义准确、上下文清晰的提示至关重要。然而，一个常见误区是直接在含可见文本的组件（如 @fluentui/react 的 <label></label>）上设置 aria-label，却期望它覆盖默认播报内容——这在 NVDA 中不会生效，因为 NVDA 优先采用元素的“可访问名称计算规则”（Accessible Name Computation），而当元素内存在未隐藏的文本节点时，aria-label 会被忽略。
✅ 正确做法是：保留视觉文本以服务 sighted 用户，同时通过 aria-hidden="true" 将其从可访问性树中移除，从而让 aria-label 成为唯一的可访问名称来源。
以下为推荐实现方式（适配 Fluent UI 的 Label 组件）：
react-modernization
下载
将 React 应用升级到最新版本，从类组件迁移到 Hooks，并采用并发特性。用于现代化改造 React 代码库、迁移到 React Hooks 或升级到最新
import React from 'react';
import { Label } from '@fluentui/react';
const MyComponent = () => {
return (
<div>
{/* ✅ 正确：span 包裹显示文本并隐藏其可访问性暴露 */}
<Label aria-label="Enter your username">
<span aria-hidden="true">Username</span>
</Label>
<input type="text" id="username" />
</div>
);
};
export default MyComponent;⚠️ 注意事项：
- 不要使用
display: none或visibility: hidden隐藏文本——它们会同时移除视觉和可访问性内容，导致 sighted 用户也看不到标签； -
aria-hidden="true"仅影响辅助技术对该元素及其子树的读取，不影响 CSS 渲染，因此视觉表现完全保留； - 确保
<input>与<label></label>正确关联（推荐显式htmlFor/id配对，或嵌套结构），以保障焦点管理与点击行为无障碍； - 若需支持多语言或动态文案，可将
aria-label和span内容分别绑定变量，但务必保持二者语义一致且上下文匹配。
? 扩展建议：对于更复杂的场景（如图标+文字标签），也可结合 role="presentation" 或 <visuallyhidden></visuallyhidden> 工具组件封装逻辑，提升复用性与可维护性。最终目标是——视觉呈现与听觉体验协同一致，而非相互冲突。
