React应用中如何实现Shadow Root内内容的HTML可访问性？

问题背景 #

主React应用会注入另一个React开发的Web组件，该组件所有内容均位于open模式的Shadow Root内。当前核心问题是：Shadow Root内部元素的ARIA属性、文本内容无法被屏幕阅读器识别，主应用也无法访问这些内容。由于规则限制，无法编写/修改自定义HTMLElement，需寻找通用解决方案。

已尝试无效的方案：

• 在被注入组件内新增子元素，仅Shadow Root外的内容生效，内部元素的可访问性标记仍无效；
• 将元素移至Shadow Root外，通过aria-labelledby关联内部目标元素，同样无法被屏幕阅读器识别。

被注入组件的核心代码示例：

import { Button } from "@mui/material";
import ReactDOM from "react-dom";

export class WebComponent extends HTMLElement {
    connectedCallback() {
        const appContainer = document.createElement("div");
        const mountPoint = document.createElement("div");
        mountPoint.appendChild(appContainer);
        this.attachShadow({ mode: "open" }).appendChild(mountPoint);

        ReactDOM.render(
            <MainApp/>, appContainer
        )
    }
}

const MainApp = () => {
    // ARIA标签和文本内容无法被屏幕阅读器识别
    return (
        <Button aria-label="TEST">TestBtn</Button>
    )
}

customElements.define("web-component", WebComponent);

可行解决方案 #

1. 利用Open Shadow Root特性 + 宿主元素标记修正 #

Shadow Root设为open模式时，屏幕阅读器理论上可识别内部内容，若无法识别，大概率是宿主元素<web-component>缺少必要的可访问性标记。无需修改自定义HTMLElement代码，直接在主应用中操作：

// 主应用组件挂载后执行
useEffect(() => {
  const webComp = document.querySelector('web-component');
  if (!webComp) return;

  // 定位Shadow Root内的目标元素（建议用自定义data属性替代类名，提高稳定性）
  const innerBtn = webComp.shadowRoot?.querySelector('[data-accessible-target="main-button"]');
  if (innerBtn) {
    // 同步内部元素的ARIA属性到宿主
    webComp.setAttribute('aria-label', innerBtn.getAttribute('aria-label'));
    webComp.setAttribute('role', 'button');
    // 按需同步其他ARIA属性，如aria-disabled等
    webComp.setAttribute('aria-disabled', innerBtn.getAttribute('aria-disabled') || 'false');
  }
}, []);

同时给被注入组件的内部元素添加定位标记：

// 被注入组件的Button
<Button aria-label="TEST" data-accessible-target="main-button">TestBtn</Button>

2. 跨React应用通过自定义事件传递可访问性信息 #

利用自定义事件实现主应用与被注入组件的通信，无需直接操作DOM结构，也无需修改自定义HTMLElement：

被注入组件（Shadow Root内的React代码）

在组件挂载/更新时，向宿主元素发送包含可访问性信息的自定义事件：

const MainApp = () => {
  useEffect(() => {
    const hostEl = document.querySelector('web-component');
    if (!hostEl) return;

    hostEl.dispatchEvent(new CustomEvent('accessibility-update', {
      detail: {
        ariaLabel: 'TEST',
        role: 'button',
        textContent: 'TestBtn'
      },
      bubbles: true // 允许事件冒泡到主应用
    }));
  }, []);

  return <Button aria-label="TEST" data-accessible-target="main-button">TestBtn</Button>;
};

主应用代码

监听自定义事件，根据传递的信息设置宿主元素的可访问性属性：

function ParentApp() {
  useEffect(() => {
    const handleAccessibilityUpdate = (e) => {
      const { ariaLabel, role } = e.detail;
      const webComp = e.target;
      
      webComp.setAttribute('aria-label', ariaLabel);
      webComp.setAttribute('role', role);
    };

    document.addEventListener('accessibility-update', handleAccessibilityUpdate);
    return () => {
      document.removeEventListener('accessibility-update', handleAccessibilityUpdate);
    };
  }, []);

  return <web-component />;
}

3. 兼容性检查 #

部分旧版本屏幕阅读器（如旧版JAWS）或浏览器对Shadow DOM的ARIA支持存在缺陷，建议测试以下主流兼容组合：

• Chrome/Edge + NVDA
• Firefox + NVDA
• Safari + VoiceOver
  确保浏览器支持Shadow DOM v1，且屏幕阅读器为最新版本。

内容的提问来源于stack exchange，提问作者bartusko_