ShadowDOMdelegatesFocus优化表单体验

`delegatesFocus` 是 Shadow DOM 中一项关键的可访问性优化配置，通过在 `attachShadow` 时启用 `delegatesFocus: true`，能让键盘 Tab 导航自动将焦点从不可见的宿主元素“穿透”到 Shadow Root 内首个可聚焦子元素（如 ``），彻底解决表单组件中焦点卡死、操作断层的痛点；它虽仅在 `'open'` 模式下生效且需宿主可聚焦、内部元素真实可用、ARIA 语义完备等多重条件协同，却是打造健壮、无障碍、跨浏览器（Chrome/Edge/Firefox/Safari 16.4+）自定义表单体验不可或缺的一环——真正考验的不是代码开关，而是对焦点流全链路的精准掌控。

delegatesFocus 是什么，为什么它影响 Tab 导航

delegatesFocus 是 attachShadow 接收的配置项之一，类型为布尔值，默认 false。它不控制“是否能聚焦”，而是决定：当用户用键盘 Tab 切换焦点、且当前焦点落在 Shadow Host（宿主元素）上时，浏览器是否自动将焦点“委托”到 Shadow Root 内部第一个可聚焦子元素（如 、）。

没启用时，Tab 到宿主元素就停住，焦点卡在不可见的容器上，用户必须再按一次 Tab 或用鼠标点进去——这对表单组件极其不友好。

什么时候必须设为 true

以下场景中，delegatesFocus={true} 不是可选项，而是可访问性刚需：

• 自定义 、 等封装了原生控件的表单组件
• 模态框（）内含多个可聚焦元素，但宿主本身需参与 Tab 顺序
• 复合组件如带搜索框的下拉选择器（combobox），宿主是
  ，内部有 和

  注意：delegatesFocus 仅在 mode: 'open' 下生效；mode: 'closed' 时该字段被忽略，且无法通过 JS 访问 root，自然也无法委托焦点。

  React 中使用 delegatesFocus 的实操要点

  在 React 封装 Shadow DOM 组件时（例如基于 react-shadow 或手写 useLayoutEffect），关键不是“加个 prop”，而是确保整个焦点链路闭环：

  • 宿主元素必须本身可聚焦：添加 tabIndex={0} 或使用语义化标签（如

）作为宿主

delegatesFocus 要和 mode 一起传给 attachShadow，不能只设前者

Shadow Root 内部第一个可聚焦元素需真实存在、未被 disabled 或 hidden，且 tabindex 不为 -1

避免在 Shadow 内部用 focus() 手动抢焦点——这会打断浏览器原生委托逻辑，导致 Tab 顺序错乱

示例（简化版）：

function MyInput({ value, onChange }) {
  const ref = useRef(null);
  useLayoutEffect(() => {
    if (ref.current) {
      const root = ref.current.attachShadow({
        mode: 'open',
        delegatesFocus: true // ← 必须显式开启
      });
      root.innerHTML = `
        
      `;
      const input = root.querySelector('input');
      input.addEventListener('input', e => onChange?.(e.target.value));
    }
  }, []);

  return 
; // ← 宿主自身可聚焦
}

容易被忽略的兼容性与调试陷阱

delegatesFocus 表面简单，但实际落地常因细节失效：

• Chrome / Edge 110+、Firefox 106+ 支持良好；Safari 16.4+ 才开始支持，旧版 Safari 会静默忽略该参数
• DevTools 中检查焦点时，若看到焦点停在宿主上不动，先确认：宿主是否真有 tabIndex？Shadow Root 是否已挂载完成？内部 input 是否被 display: none 或 visibility: hidden 隐藏？
• 若组件内用了 slot 投影内容，delegatesFocus 不会委托到 slot 中的内容——它只作用于 Shadow Tree 原生子节点
• 配合 ARIA 使用时，role="combobox" 等复合角色必须配 aria-controls 或 aria-expanded，否则屏幕阅读器仍可能跳过宿主

真正难的不是设 true，而是让整个组件从 DOM 结构、属性设置、事件响应到 ARIA 语义全部对齐浏览器焦点委托的预期路径——少一环，Tab 就断在半路。

今天关于《ShadowDOMdelegatesFocus优化表单体验》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！