气泡确认框
概述
基于 Popper 的确认框组件，用于轻量级的二次确认操作。SPopconfirm 组合 Aria PopconfirmCompact（构建于 popper 基础组件之上）与 popconfirmVariants 样式配方（13 个槽、6 种尺寸 × 4 种类型）。
适用于触发器旁快速的内联确认（删除、破坏性操作）。更丰富的阻塞性确认请用 dialog；不打扰的提示请用 tooltip。
用法
特性
- 🧩 基于
Popper— 继承定位、箭头、portal、可关闭与焦点行为 - 🎨 4 种类型 —
type="error"/"success"/"warning"/"info"驱动前导图标与颜色 - 🏷️ 标题 + 描述 + 内容 —
title/description/contentprop 或对应插槽 - 🔘 确认/取消 —
confirmText/cancelText（取自dialog.confirm/dialog.cancel本地化消息）；showCancel默认onlyWarning - 🖼️ 图标开关 —
showIcon渲染类型图标；showArrow渲染 popper 箭头 - 📐 6 种尺寸 — xs–2xl
size；逐槽ui覆盖 - ♿ 无障碍 — 弹层暴露由触发器标注的
role="dialog"、焦点管理、浏览器 e2e 中axe-core零违规 - 🔒 禁用 —
disabled阻止触发器打开气泡确认框
组件家族
SPopconfirm（样式层）— 入口包装组件；popconfirmVariants配方配合动态插槽转发PopconfirmCompact（Aria）— 构建于PopperRoot/PopperTrigger/PopperPositioner/PopperPopup之上的聚合组件PopconfirmHeader/PopconfirmContent/PopconfirmFooter（Aria）— 布局分区PopconfirmTitle/PopconfirmDescription（Aria）— 标题/描述PopconfirmConfirm/PopconfirmCancel（Aria）— 底部<button>，发出confirm/cancel
演示
基础
100%
API
Aria 层
17Popconfirm
31 属性10 事件6 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 弹出窗口类 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<PopconfirmUi> | — | 该组件的按槽类重写。 |
type | PopconfirmType | — | 类型。 |
placement | Placement | — | 位置。 |
title | string | — | 由组件渲染的标题文本。 |
description | string | — | 由组件渲染的描述文本。 |
content | string | — | 内容。 |
showArrow | boolean | true | 是否显示箭头。 |
showIcon | boolean | true | 是否显示图标。 |
confirmText | string | — | 确认按钮的文本。
默认采用来自 `ConfigProvider` 的本地化 `dialog.confirm` 消息。 |
cancelText | string | — | “取消”按钮的文本。
默认采用来自 `ConfigProvider` 的本地化 `dialog.cancel` 消息。 |
showCancel | boolean | 'onlyWarning' | 'onlyWarning' | 决定是否显示“取消”按钮。 |
triggerProps | PopconfirmTriggerProps | — | 转发给触发元素的属性。 |
portalProps | PopperPortalProps | — | 转发给 portal 元素的属性。 |
positionerProps | PopconfirmPositionerProps | — | 转发给定位器元素的属性。 |
popupProps | PopconfirmPopupProps | — | 转发给弹出窗口元素的属性。 |
arrowProps | PopperArrowProps | — | 转发给箭头元素的属性。 |
closeProps | PopconfirmCloseProps | — | 转发至 close 元素的属性。 |
headerProps | PopconfirmHeaderProps | — | 转发至 header 元素的属性。 |
titleProps | PopconfirmTitleProps | — | 传递给 title 元素的属性。 |
descriptionProps | PopconfirmDescriptionProps | — | 已将属性转发至 description 元素。 |
contentProps | PopconfirmContentProps | — | 转发给内容元素的属性。 |
footerProps | PopconfirmFooterProps | — | 转发至页脚元素的属性。 |
confirmProps | PopconfirmConfirmProps | — | 转发给 confirm 元素的属性。 |
cancelProps | PopconfirmCancelProps | — | 转发给 cancel 元素的属性。 |
dir | Direction | — | — |
open | boolean | — | — |
defaultOpen | boolean | — | — |
modal | boolean | — | — |
disabled | boolean | — | — |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:open | boolean, reason: PopperOpenChangeReason | — |
escapeKeyDown | KeyboardEvent | 当 Esc 键被按下时触发的事件处理程序。可被阻止。 |
pointerDownOutside | PointerDownOutsideEvent | 当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。 |
focusOutside | FocusOutsideEvent | 当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。 |
interactOutside | PointerDownOutsideEvent | FocusOutsideEvent | 当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown`
事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。 |
openAutoFocus | Event | 在打开页面时自动聚焦时触发的事件处理程序。可被阻止。 |
closeAutoFocus | Event | 在关闭时自动聚焦时触发的事件处理程序。可被阻止。 |
placed | — | — |
confirm | PointerEvent | 在发生确认时触发。 |
cancel | PointerEvent | 在发生取消时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
default | PopconfirmCompactBaseSlotProps | 默认插槽的自定义内容。 |
trigger | PopconfirmCompactBaseSlotProps | 触发槽的自定义内容。 |
title | PopconfirmCompactBaseSlotProps | 标题槽位的自定义内容。 |
description | PopconfirmCompactBaseSlotProps | 描述字段的自定义内容。 |
footer | PopconfirmCompactBaseSlotProps | 页脚位置的自定义内容。 |
close | PopconfirmCompactBaseSlotProps | close 插槽的自定义内容。 |
PopconfirmAnchor
3 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
reference | ReferenceElement | — | — |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
PopconfirmArrow
PopconfirmCancel
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
cancel | PointerEvent | 在发生取消时触发。 |
PopconfirmClose
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
close | PointerEvent | 在关闭时触发。 |
PopconfirmCompact
28 属性10 事件6 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | PopconfirmType | — | 类型。 |
placement | Placement | — | 位置。 |
title | string | — | 由组件渲染的标题文本。 |
description | string | — | 由组件渲染的描述文本。 |
content | string | — | 内容。 |
showArrow | boolean | true | 是否显示箭头。 |
showIcon | boolean | true | 是否显示图标。 |
confirmText | string | — | 确认按钮的文本。
默认采用来自 `ConfigProvider` 的本地化 `dialog.confirm` 消息。 |
cancelText | string | — | “取消”按钮的文本。
默认采用来自 `ConfigProvider` 的本地化 `dialog.cancel` 消息。 |
showCancel | boolean | 'onlyWarning' | 'onlyWarning' | 决定是否显示“取消”按钮。 |
triggerProps | PopconfirmTriggerProps | — | 转发给触发元素的属性。 |
portalProps | PopperPortalProps | — | 转发给 portal 元素的属性。 |
positionerProps | PopconfirmPositionerProps | — | 转发给定位器元素的属性。 |
popupProps | PopconfirmPopupProps | — | 转发给弹出窗口元素的属性。 |
arrowProps | PopperArrowProps | — | 转发给箭头元素的属性。 |
closeProps | PopconfirmCloseProps | — | 转发至 close 元素的属性。 |
headerProps | PopconfirmHeaderProps | — | 转发至 header 元素的属性。 |
titleProps | PopconfirmTitleProps | — | 传递给 title 元素的属性。 |
descriptionProps | PopconfirmDescriptionProps | — | 已将属性转发至 description 元素。 |
contentProps | PopconfirmContentProps | — | 转发给内容元素的属性。 |
footerProps | PopconfirmFooterProps | — | 转发至页脚元素的属性。 |
confirmProps | PopconfirmConfirmProps | — | 转发给 confirm 元素的属性。 |
cancelProps | PopconfirmCancelProps | — | 转发给 cancel 元素的属性。 |
dir | Direction | — | — |
open | boolean | — | — |
defaultOpen | boolean | — | — |
modal | boolean | — | — |
disabled | boolean | — | — |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:open | boolean, reason: PopperOpenChangeReason | — |
escapeKeyDown | KeyboardEvent | 当 Esc 键被按下时触发的事件处理程序。可被阻止。 |
pointerDownOutside | PointerDownOutsideEvent | 当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。 |
focusOutside | FocusOutsideEvent | 当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。 |
interactOutside | PointerDownOutsideEvent | FocusOutsideEvent | 当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown`
事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。 |
openAutoFocus | Event | 在打开页面时自动聚焦时触发的事件处理程序。可被阻止。 |
closeAutoFocus | Event | 在关闭时自动聚焦时触发的事件处理程序。可被阻止。 |
placed | — | — |
confirm | PointerEvent | 在发生确认时触发。 |
cancel | PointerEvent | 在发生取消时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
default | PopconfirmCompactBaseSlotProps | 默认插槽的自定义内容。 |
trigger | PopconfirmCompactBaseSlotProps | 触发槽的自定义内容。 |
title | PopconfirmCompactBaseSlotProps | 标题槽位的自定义内容。 |
description | PopconfirmCompactBaseSlotProps | 描述字段的自定义内容。 |
footer | PopconfirmCompactBaseSlotProps | 页脚位置的自定义内容。 |
close | PopconfirmCompactBaseSlotProps | close 插槽的自定义内容。 |
PopconfirmConfirm
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
confirm | PointerEvent | 在发生确认时触发。 |
PopconfirmContent
PopconfirmDescription
PopconfirmFooter
PopconfirmHeader
PopconfirmPopup
PopconfirmPortal
PopconfirmPositioner
23 属性7 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
placement | Placement | undefined | 浮动元素的位置。
若使用该属性，它将覆盖 `side` 和 `align` 属性。 |
side | Side | 'bottom' | 打开时优先渲染的触发器一侧。当发生碰撞且
enableAvoidCollisions 启用时，该方向将被反转。 |
sideOffset | number | 0 | 距触发器的像素距离。 |
sideFlip | boolean | true | 遇到边界时，请翻转至另一侧。 |
align | Align | 'center' | 首选与触发条件保持一致。若发生冲突，则可能调整。 |
alignOffset | number | 0 | 相对于 `start` 或 `end` 对齐选项的像素偏移量。 |
alignFlip | boolean | true | 当与边界发生冲突时，翻转对齐方式。
此情况仅在 `prioritizePosition` 为 true 时才会发生。 |
avoidCollisions | boolean | true | 当值为 `true` 时，将覆盖“侧边”和“对齐”首选项，以避免与边界边缘发生冲突。 |
collisionBoundary | Element | (Element | null)[] | null | [ ] | 用作碰撞边界的元素。默认情况下，该边界为视口，但您可以提供额外的
元素以纳入此检查范围。 |
collisionPadding | Padding | 0 | 从边界边缘开始，碰撞检测应发生的距离（以像素为单位）。接受一个数字（
所有边均相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。 |
arrowPadding | number | 0 | 箭头与内容边缘之间的间距。如果您的内容使用了 border-radius，这将防止内容
溢出到角落。 |
hideShiftedArrow | boolean | true | 当值为 `true` 时，若无法将箭头居中对齐
到引用元素上，则隐藏该箭头。 |
sticky | 'partial' | 'always' | 'partial' | 在对齐轴上的“粘附”行为。`partial` 会在触发器至少部分位于边界内时将内容保留在边界内，而
“always” 则无论触发器是否位于边界内，都会将内容保留在边界内。 |
hideWhenDetached | boolean | false | 当触发器被完全遮挡时，是否隐藏内容。 |
positionStrategy | 'fixed' | 'absolute' | 'fixed' | 要使用的 CSS `position` 属性的类型。 |
updatePositionStrategy | 'always' | 'optimized' | 'optimized' | 在每个动画帧中更新浮动元素位置的策略。 |
disableUpdateOnLayoutShift | boolean | false | 当布局发生变化时，是否禁用内容的更新位置。 |
prioritizePosition | boolean | false | 强制内容位于视口内。可能会与参考元素重叠，这可能并非预期效果。 |
reference | ReferenceElement | — | 将作为浮动元素定位参考点的自定义元素或虚拟元素。如果
提供了该元素，它将替换默认的锚点元素。 |
trapFocus | boolean | modal | 弹出窗口打开时，焦点是否被困在其中（Tab 键在层内循环，且
模态层的页面滚动被锁定）。 |
disableHoverableContent | boolean | false | 当设置为 `true` 时，鼠标悬停会关闭弹出窗口而非保持其打开状态（宽限区域已禁用，
因此离开触发区域会立即关闭该层）。 |
onGracePointerExit | (() => void) | — | 当指针最终离开宽限区域时触发的回调。允许上层组件（例如
Tooltip）在无需注册自己的第二个宽限区域的情况下，执行区域范围内的关闭逻辑。 |
forceMount | boolean | — | 用于在需要更多控制时强制挂载。
在使用 Vue 动画库控制动画时非常有用。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
escapeKeyDown | KeyboardEvent | 当 Esc 键被按下时触发的事件处理程序。可被阻止。 |
pointerDownOutside | PointerDownOutsideEvent | 当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。 |
focusOutside | FocusOutsideEvent | 当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。 |
interactOutside | PointerDownOutsideEvent | FocusOutsideEvent | 当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown`
事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。 |
openAutoFocus | Event | 在打开页面时自动聚焦时触发的事件处理程序。可被阻止。 |
closeAutoFocus | Event | 在关闭时自动聚焦时触发的事件处理程序。可被阻止。 |
placed | — | — |
PopconfirmRoot
5 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
dir | Direction | — | — |
open | boolean | — | — |
defaultOpen | boolean | — | — |
modal | boolean | — | — |
disabled | boolean | — | — |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:open | boolean, reason: PopperOpenChangeReason | — |
PopconfirmTitle
PopconfirmTrigger
14 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
trigger | PopperTriggerType | — | — |
reference | ReferenceElement | — | — |
openDelay | number | — | — |
closeDelay | number | — | — |
skipDelayDuration | number | — | — |
pressOpenDelay | number | — | — |
openOnFocus | boolean | — | — |
focusOpenDelay | number | inherit from `openDelay` | 对焦点驱动的打开操作应用打开延迟。默认值为 `openDelay`；设置为 `0` 则在获得焦点时
立即打开（工具提示语义）。 |
focusVisibleOnly | boolean | false | 当设置为 `true` 时，基于焦点的展开仅响应键盘/程序化的焦点
(`:focus-visible`)，忽略由指针引发的焦点。 |
ariaMode | PopperTriggerAriaMode | 'controls' | 触发器如何为辅助技术引用其弹出窗口。
- `controls`：`aria-expanded` + `aria-controls`（可展开控件：弹出框/菜单）
- `describedby`：展开时使用 `aria-describedby`（类似工具提示的描述）
- `none`：无弹出窗口引用属性 |
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
注意事项
架构与对标差异
PopconfirmCompact 组合 popper 触发器/定位器/弹层与确认式头部、内容、底部，所有基础组件保持零样式，仅由 UI 包装组件注入 popconfirmVariants 类。这与 radix-ui/shadcn-ui 的 headless 分离一致。Ant Design、Element Plus、Mantine、Naive UI 提供带 title/description/okText/cancelText/onConfirm prop 的单一样式化气泡确认框；VeanUI 额外暴露逐槽 *Props、size 尺寸体系、type 颜色/图标系统与本地化操作标签。
| 能力 | VeanUI | shadcn/ui | Ant Design Popconfirm | Element Plus Popconfirm | Mantine Popconfirm | Naive UI Popconfirm |
|---|---|---|---|---|---|---|
| 基于 Popper | ✅ | ✅ | — | — | — | — |
| Aria/样式分离 | ✅ | ✅ | — | — | — | — |
| 类型图标 + 颜色 | ✅ | — | — | ✅ | — | — |
| 标题 + 描述 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 本地化确认/取消 | ✅ | — | — | — | — | — |
| 尺寸（6） | ✅ | — | — | — | — | — |
| 定位（popper） | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
— = 不支持或采用不同交互模型。
运行时注意
modal默认false（与 dialog 不同），因此不阻塞外部交互、不锁定 body 滚动。showCancel默认'onlyWarning'— 仅type="warning"时显示取消按钮。传显式布尔值可覆盖。confirmText/cancelText默认取dialog.confirm/dialog.cancel的本地化消息；可按实例覆盖。- 弹层渲染
role="dialog"并由触发器标注；请提供title以使对话框有清晰的可访问名称。 - 确认/取消发出
confirm/cancel事件；任一操作后弹层关闭（受父级自己的beforeClose处理影响）。
Roadmap
不适用——popconfirm 对当前对标集已功能完备。
FAQ
如何显示标题、描述与内容？
传入 title/description/content prop 或对应插槽：
<SPopconfirm title="删除该项？" description="此操作无法撤销。" content="请先确认再继续。">
<template #trigger><SButton danger>删除</SButton></template>
</SPopconfirm>如何设置类型与图标？
使用 type（error/success/warning/info）并切换 show-icon：
<SPopconfirm type="warning" title="请注意">
<template #trigger><SButton>删除</SButton></template>
</SPopconfirm>如何自定义操作标签？
设置 confirm-text/cancel-text，并用 show-cancel 控制取消按钮：
<SPopconfirm confirm-text="删除" cancel-text="保留" :show-cancel="true" title="确认">
<template #trigger><SButton>删除</SButton></template>
</SPopconfirm>如何控制打开状态？
用 v-model 绑定 open 或使用 defaultOpen：
<SPopconfirm v-model:open="open" title="确认">
<template #trigger><SButton>删除</SButton></template>
</SPopconfirm>如何禁用触发器？
设置 disabled 以阻止打开：
<SPopconfirm disabled title="确认">
<template #trigger><SButton>删除</SButton></template>
</SPopconfirm>