ElementSelectionOverlay

何时用

要做「点预览里的元素 → 定位到源码 / 打开属性面板 / 喂给 prompt」这类指向编辑能力时用它。它只负责选中并给出路径，编辑面板由你自己搭。

• 引导用户看某个已知元素，用 Tour（它是遮罩镂空 + 气泡卡，目标由你指定，不做拾取）。
• 只想给元素加注解气泡，用 Annotation。
• 只想要一层不可交互的贴图覆盖，用 Watermark。

导入

Props

Events

ElementSelectionDetail = { path, source: "marked" ｜ "structural", component, tagName, element, rect }。source 告诉你这条路径有多可靠：marked 读自标记属性（跨重排不失效），structural 是按 DOM 结构推的（DOM 一变可能失效）。

无障碍

• 叠加层 aria-hidden + pointer-events: none：不进无障碍树、不抢焦点、不挡目标交互。
• 不只靠颜色区分状态：hover 是虚线细框，选中是实线粗框，形态本身可分辨；标签再给出组件名/元素名。
• 键盘可达：目标内 Tab 到元素后按 Enter / 空格即选中，Esc 清除选中，不必依赖指针。
• 建议宿主再提供一条等价的键盘通路（如用 Tree 列出组件树），与 selectedPath 双向绑定 —— 对屏幕阅读器用户来说，「在画布上找元素」始终不如「在列表里选节点」。
• 标签自动避让视口上边缘（贴顶时翻到框内侧），不会被裁掉。

禁忌 / 坑

• 跨源 iframe 不支持，而且不会静默失效：读不到 contentDocument 时组件不渲染，并触发一次 onError({ code: "cross-origin" }) + 开发期告警。要跨源就只有三条路：换成同源预览（srcDoc / 同源代理域名）、或在被预览页里自己挂一份叠加层把 path 通过 postMessage 回传宿主、或放弃指向编辑。本组件不提供 postMessage 桥（那是另一套协议，不该藏在一个 UI 组件里）。
• 能打标记就打标记。structural 路径是按 DOM 结构推的，插一个兄弟节点、条件渲染一变就可能指到别处。把 data-hulian-path 打在组件根节点上，路径才跨重排稳定。
• iframe 内的元素跨 realm：它们不是宿主的 Element 实例，node instanceof Element 恒 false —— 自己处理目标事件时请用导出的 asElement()，别用 instanceof（这是同源 iframe 场景最容易踩的静默失效）。
• interceptClicks 默认 true，意味着选择模式下预览是不可交互的（点击被吞、mousedown 的默认行为被挡）。要让用户一边操作预览一边看高亮，传 interceptClicks={false}，或用 enabled 显式切换选择模式。
• 目标根自身不可选：target 那个元素（iframe 场景是其 body）hover 与点击都视为空白，点它触发 onClear。根若也带标记属性，所有元素会退化成同一条路径，所以标记查找刻意跳过根。
• jsdom 下 `getBoundingClientRect` 恒为 0，零面积一律判不可见 → 单测里默认一个框都不会渲染。要断言框的存在，先给 Element.prototype.getBoundingClientRect 打桩；但别断言坐标数值（坐标来自你的桩，等于自证）。坐标逻辑请测 toHostRect / computeLabelPosition 这两个纯函数。
• 目标是 document.body 时，本组件的 portal 层就落在目标内部；组件已过滤掉自身引起的 MutationObserver 记录（否则自触发死循环），你若另外挂了 observer 也要做同样的过滤。
• 客户端组件（要读 DOM、要挂监听），必须在 client 上下文用；SSR 期不渲染任何东西。

相关

Tour · Annotation · Watermark · Flow · Tree