如何在Shadow DOM内的Web组件中定位目标元素

问题场景 #

在普通DOM环境中使用wc-tooltip组件一切正常：

<div>
  You can use <span class="disk-space" id="help">20GB</span> of space.
  <wc-tooltip target="help">It works only if you are a vampire.</wc-tooltip>
</div>

但将组件放到Web组件的Shadow DOM内时，tooltip完全无法工作：

<Host>
  <span><slot/></span>
  { this.tip && 
    <>
      <wc-icon id="help" name="my/fantastic/help/icon" />
      <wc-tooltip target="help">{ this.tip }</wc-tooltip>
    </>
  }
</Host>

原因分析 #

问题出在wc-tooltip的核心查找逻辑上，当前代码直接用document.getElementById()在全局DOM中查找目标元素：

componentDidRender (): void {
  const caller = document.getElementById(this.target)
  if (caller) {
    this.caller = caller
    this.caller.addEventListener('mouseleave', this.handleVisibility.bind(this, false))
    this.caller.addEventListener('mouseenter', this.handleVisibility.bind(this, true))
    return
  }
  console.error('Warning: property target is undefined.')
}

Shadow DOM是封闭的独立DOM树，document无法访问其内部元素，自然找不到ID为help的wc-icon。

解决方案 #

方案1：支持直接传入元素引用（最可靠） #

修改wc-tooltip组件，新增一个element属性，允许直接传入目标元素的引用，跳过ID查找步骤：

componentDidRender (): void {
  // 优先使用传入的元素引用
  if (this.element) {
    this.caller = this.element;
  } else {
    // 降级为ID查找，但改用当前组件所在的根节点（支持Shadow DOM）
    const root = this.getRootNode();
    this.caller = root.getElementById(this.target);
  }

  if (this.caller) {
    this.caller.addEventListener('mouseleave', this.handleVisibility.bind(this, false));
    this.caller.addEventListener('mouseenter', this.handleVisibility.bind(this, true));
    return;
  }
  console.error('Warning: 未找到目标元素，请检查target或element属性');
}

在Shadow DOM中使用时，直接传递元素引用即可：

// 类式Web组件示例
class MyCustomComponent extends HTMLElement {
  connectedCallback() {
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <span><slot></slot></span>
      <wc-icon id="help" name="my/fantastic/help-icon"></wc-icon>
      <wc-tooltip></wc-tooltip>
    `;
    // 获取Shadow DOM内的元素引用
    const helpIcon = this.shadowRoot.getElementById('help');
    const tooltip = this.shadowRoot.querySelector('wc-tooltip');
    // 直接传入元素
    tooltip.element = helpIcon;
    tooltip.textContent = this.tip;
  }
}

方案2：自动适配Shadow DOM的ID查找 #

如果不想新增属性，也可以修改原有的ID查找逻辑，让组件从自身所在的根节点（而非全局document）查找元素：

componentDidRender (): void {
  // getRootNode()会返回当前组件所在的根，可能是ShadowRoot或document
  const root = this.getRootNode();
  const caller = root.getElementById(this.target);
  
  if (caller) {
    this.caller = caller;
    this.caller.addEventListener('mouseleave', this.handleVisibility.bind(this, false));
    this.caller.addEventListener('mouseenter', this.handleVisibility.bind(this, true));
    return;
  }
  console.error('Warning: property target is undefined.');
}

修改后，在Shadow DOM内使用原有的target属性即可正常工作，无需额外改动业务代码。

方案3：支持CSS选择器定位 #

如果需要更灵活的定位方式，可以将target属性改为支持CSS选择器，然后从组件的父级上下文查找：

componentDidRender (): void {
  // 从父元素上下文查找匹配选择器的元素
  const caller = this.parentElement.querySelector(this.target);
  
  if (caller) {
    this.caller = caller;
    this.caller.addEventListener('mouseleave', this.handleVisibility.bind(this, false));
    this.caller.addEventListener('mouseenter', this.handleVisibility.bind(this, true));
    return;
  }
  console.error('Warning: 未找到匹配target选择器的元素');
}

使用时可以直接传入类选择器或其他CSS规则：

<wc-icon class="help-icon" name="my/fantastic/help-icon"></wc-icon>
<wc-tooltip target=".help-icon">{ this.tip }</wc-tooltip>

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