delegatesfocus 是解决 shadow dom 中焦点进入后去向问题的属性，需宿主可聚焦、shadow root 为 open 模式且内部存在有效可聚焦元素三者同时满足才生效。

delegatesFocus 不是“让组件能被 Tab 到”的开关，而是解决“Tab 进去之后焦点去哪儿”这个关键问题的属性。它只在 Shadow DOM 已存在、且内部有可聚焦元素的前提下起作用；如果组件本身不参与 Tab 顺序（比如 IsTabStop=false 或 tabIndex=-1），设置它毫无意义。

为什么默认 false 会导致键盘用户卡住

当自定义组件（如 <app-sidebar></app-sidebar> 或 <custom-dialog></custom-dialog>）用 Shadow DOM 封装了 <input>、<button></button> 等元素，但没设 delegatesFocus=true 时：用户按 Tab 进入该组件宿主元素（比如 <app-sidebar></app-sidebar> 自身），焦点就停在宿主上——而宿主通常不可交互、无语义、也不渲染视觉反馈。键盘用户无法继续往下 Tab，只能靠 Shift+Tab 回退，体验断裂。

根本原因在于：Shadow DOM 边界阻断了浏览器原生的焦点冒泡与委托逻辑。浏览器不知道该把焦点“递进”到内部哪个元素。

必须同时满足的三个条件才能生效

delegatesFocus 要真正起效，以下三点缺一不可：

• 宿主元素本身得能被 Tab 到：确保它有 tabIndex="0"，或本身是原生可聚焦元素（如 <button></button>），且 IsEnabled=true、IsTabStop=true（在 ArkTS 或 WinUI 等框架中需显式检查）
• Shadow Root 必须用 { mode: 'open' } 创建（'closed' 模式下浏览器连内部结构都看不到，更别说委托焦点）
• Shadow 内部至少有一个满足“可聚焦”条件的元素：比如 <input>、<button></button>、tabIndex="0" 的 <div>，且未被 <code>disabled 或 aria-hidden="true"

  实际写法与常见踩坑

  错误写法：shadowRoot = host.attachShadow({ mode: 'open' }) 后直接渲染内容，却忘了加 delegatesFocus 参数——它不是 ShadowRoot 的属性，而是 attachShadow() 的配置项之一。

  

  Openclaw Gateway Guardian

  OpenClaw网关守护 - 自动监控、保护与重启OpenClaw网关服务，防止网关停止、崩溃或消失。

  下载

  正确写法示例（标准 Web Components）：

  const host = document.createElement('app-modal');
  host.tabIndex = 0; // 让宿主可被 Tab 到
  const shadowRoot = host.attachShadow({
    mode: 'open',
    delegatesFocus: true // ✅ 关键：必须在这里传入
  });
  shadowRoot.innerHTML = `
    <div class="overlay">
      <button id="close-btn">Close</button>
      <input placeholder="Type something...">
  </div>
  `;

  容易被忽略的点：

  • React 中用 createShadowRoot 或第三方库（如 react-shadow）时，delegatesFocus 往往不被透传，需手动 patch 或换用原生 attachShadow
  • 在 Chromium 120+ 中，若 Shadow 内部第一个可聚焦元素是 <input type="hidden"> 或 tabIndex="-1"，委托会失败，浏览器 fallback 到聚焦宿主——务必检查内部元素的实际聚焦能力
  • 部分 UI 框架（如早期版本的 Lit）默认禁用此行为，需在 createRenderRoot() 中显式启用

  和 aria-describedby / tabindex 配合才完整

  delegatesFocus=true 只解决“焦点进哪”，不解决“进来了用户知道这是啥”。必须配合：

  • 给宿主加 role="dialog" 或 role="navigation" 等语义角色
  • 用 aria-labelledby 指向内部标题，或 aria-label 直接描述用途
  • 若内部有多个逻辑区块（如侧边栏含菜单+搜索+用户头像），考虑用 roving tabindex 模式管理子项焦点流，而非依赖单次委托

  真正麻烦的从来不是加一个布尔值，而是确认整个焦点链路——从页面 Tab 顺序起点，到宿主，再到 Shadow 内部首个可聚焦节点，再到后续可操作控件——每一步都有状态、语义、样式反馈的耦合。漏掉任意一环，delegatesFocus 就只是个摆设。