Popover
在触发对象附近展示补充内容。中文惯用名：气泡卡片。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.popover |
| 名称 | Popover |
| 二级分类 | 反馈（feedback） |
| 用途 | 在触发对象附近展示补充内容 |
| 描述 | 中文惯用名：气泡卡片。 |
预览
静态结构：经 Base UI Popover 原语渲染——children（触发元素）以 <span data-slot="popover-trigger-wrap"> 包装接入 PopoverTrigger，DSL 子树渲染其中，点击切换浮层；浮层经 Portal + Positioner 定位（side=bottom、align=center、sideOffset=4，默认吸附触发元素下方居中），内容面板 data-slot="popover-content"（w-72、rounded-md + 边框 + 阴影、p-4，data-open / data-closed 驱动淡入缩放动画）；content 为 DSL 子树对象时经 renderChildren 渲染，为字符串时直接渲染文本。点击外部、按 Escape 或再次点击触发元素即关闭。
DSL 结构
{
"type": "Popover",
"props": {
"content": {
"type": "Text",
"props": {
"text": "浮层内容：可放任意 DSL 子树，点击外部关闭。"
}
}
},
"children": [
{
"type": "Button",
"props": {
"text": "打开浮层",
"variant": "default"
}
}
]
}何时用
何时使用
- 在触发对象附近展示补充内容：字段说明、术语解释、快捷设置面板、附带的小表单片段。
- 内容可含交互元素（链接、按钮、少量控件），且需要点击外部才关闭的场景。
- 内容比 Tooltip 长、比 Dialog 轻：无需阻断当前流程。
何时不用
- 纯短文本说明或不可见标签的补充：使用 Tooltip（hover 触发，更轻且不可交互）。
- 需要用户确认后继续的操作：使用 Popconfirm；需要阻断流程：使用 Dialog。
- 承载大表单或长详情：使用 Drawer / Dialog，固定宽度的浮层放不下。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| DSL 子树内容 | content 传 DslNode 对象，经 Renderer 渲染 | 需要结构化内容或交互控件 |
| 纯文本内容 | content 传字符串，直接渲染文本 | 一段补充说明或术语定义 |
| Button 触发 | children 为 Button 子树（span 包装接入 Trigger） | 「打开浮层」式的显式入口 |
| 文字链 / 图标触发 | children 为 Link / Icon 等轻量元素 | 字段说明、术语解释的就近锚点 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | `DslNode | string` | — |
children | ReactNode | — | 触发元素（DSL 子树，经 Renderer children 机制渲染，外层以 span 包装接入 Trigger） |
className / style | string / CSSProperties | — | 通用：浮层内容根节点 class 合并 / 内联样式 |
使用规范
- 触发元素由 children 提供（Button / 文字链 / 图标）：Popover 自身不提供触发样式，需要显式可点击的锚点。
- 浮层宽度固定：只放少量字段或一段说明，超出内容改用 Drawer / Dialog。
- 需要确认的内容不要塞进 Popover：确认语义用 Popconfirm，阻断语义用 Dialog。
- 浮层随点击外部关闭：不要用它承载必须被看到或必须留存的信息。
- 与 Tooltip 的边界：Tooltip 只做 hover 级短说明、不可交互；含交互元素的内容一律用 Popover。
正例
- ✓ 字段旁的「?」图标触发：content 为 Text，说明该字段的口径与取值范围。
- ✓ 快捷设置面板：content 传 DslNode 子树（少量开关 / 输入），点击外部即收起。
- ✓ 表格单元格内文字链触发：展示该条记录的补充备注。
反例
- ✕ 用 Popover 承载需要确认的删除操作（应使用 Popconfirm）。
- ✕ content 塞入长表单或大段图文（固定宽度放不下，应使用 Drawer / Dialog）。
- ✕ 用 Popover 替代 Tooltip 做纯 hover 提示（hover 场景应使用 Tooltip）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。