职责与结构
非模态浮层展示与触发器相关的补充说明和轻量操作；阻断式确认或复杂编辑使用原生模态 dialog。
具名按钮 + aria-controls / aria-haspopup=dialog / aria-expanded + 有名称的非模态 dialog 浮层 + 显式关闭按钮。
变体与 Tokens
| 项目 | 规范 |
|---|---|
| 说明与操作 | 打开后聚焦首个操作，没有操作时聚焦浮层容器。 |
| 长内容 | 保留视口内滚动，不遮住触发器且不撑出屏幕。 |
| 窄屏与模态内 | 固定定位并夹紧视口；支持浏览器 popover top layer，在不支持时留在所属原生 dialog 内。 |
复用 --surface-glass-strong、--glass-border、--radius-md、--shadow-2、--layer-popover、--space-*，不创建新的局部主题。
交互与状态示例
交互与无障碍
点击可用触发器打开/关闭；打开后进入首个操作。Esc 和显式关闭恢复触发器焦点，外点及焦点离开关闭并保留新焦点。嵌套 Tooltip 先响应自己的 Esc。Tab 不困在非模态浮层。触发器隐藏、禁用或移除，以及浮层被外部隐藏时，同步关闭状态；重复 open 不重复发送事件。滚动、视口和缩放变化重新定位；减少透明度及无 blur 时使用稳定表面。
接入约定
| 项目 | 规范 |
|---|---|
| data-ds-popover / aria-controls | 指向页面内唯一 panel ID；panel 提供 aria-labelledby 或 aria-label。 |
| data-ds-popover-close | 浮层内显式关闭按钮。初始化不会发送用户操作事件。 |
| popoverchange | 触发器冒泡事件 detail={open,id}。window.dsOverlays.bindPopover(trigger,panel) 提供 open/close/toggle/refresh。 |
查看最小使用示例
<button data-ds-popover aria-controls="canvas-info">说明</button>
<div id="canvas-info" aria-label="画布说明" hidden>
<p>当前画布的补充信息</p>
<button data-ds-popover-close type="button">关闭</button>
</div>维护位置：scripts/overlay-specimens.mjs；示例行为：scripts/overlay-behavior.js。组合应用见本页末尾引用。