反馈类 · Popconfirm
气泡确认框
目标元素的操作需要用户进一步的确认时使用。与 Popover 相比它内置了一系列可配置的操作按钮,与 Modal 相比它不强制全屏居中显示,交互也更轻量

代码演示

如何引入

基本使用

Popconfirm 底层基于 Tooltip 封装,Children 支持类型同 Tooltip,注意事项详情可查阅 Tooltip注意事项

类型搭配

开发者可以基于场景使用 okType/cancelType/icon 等参数搭配出不同风格的气泡式确认框。

延时关闭

onOk、onCancel 可以通过 return Promise 实现点击后延时关闭 (v2.19后支持)
onCancel、onOk 被触发时,对应的 Button 会自动切换为 loading: true, promise solve 会关闭气泡确认框, promise reject时气泡依然保留,同时 button loading 自动切换为 false

初始化弹出层焦点位置

okButtonProps 和 cancelButtonProps 支持传入 autoFocus 参数,传入后打开面板时会自动聚焦在该位置。2.30.0 版本支持。
content 支持传入函数,它的入参是一个对象,将 initialFocusRef 绑定在可聚焦 DOM 或组件上,打开面板时会自动聚焦在该位置。2.30.0 版本支持。

搭配 Tooltip 或 Popover 使用

请参考搭配使用

API 参考

属性说明类型默认值版本
arrowPointAtCenter“小三角”是否指向元素中心,需要同时传入"showArrow=true"booleanfalse
cancelText取消按钮文字string"取消"
cancelButtonProps取消按钮的 propsobject0.29.0
cancelType取消按钮类型string"tertiary"
closeOnEsc在 trigger 聚焦时或在弹出层内聚焦元素上按 Esc 键是否关闭面板,受控时不生效booleantrue2.8.0
content显示的内容(函数类型,2.10.0 版本支持)ReactNode|({ initialFocusRef }) => ReactNode
defaultVisible气泡框默认是否展示boolean
disabled点击 Popconfirm 子元素是否弹出气泡确认框booleanfalse
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义时容器需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。Function():HTMLElement() => document.body
guardFocus当焦点处于弹出层内时,切换 Tab 是否让焦点在弹出层内循环booleantrue2.8.0
icon自定义弹出气泡 Icon 图标ReactNode
motion下拉列表出现/隐藏时,是否有动画booleantrue
okText确认按钮文字string"确认"
okType确认按钮类型string"primary"
okButtonProps确认按钮的 propsobject
position方向,可选值:top,topLeft,topRight,left,leftTop,leftBottom,
right,rightTop,rightBottom,bottom,bottomLeft,bottomRight
string"bottomLeft"
returnFocusOnClose按下 Esc 键后,焦点是否回到 trigger 上,只有设置 trigger 为 click 时生效booleantrue2.8.0
showArrow是否显示箭头三角形booleanfalse
stopPropagation是否阻止弹层上的点击事件冒泡booleantrue
title显示的标题ReactNode
trigger触发展示的时机,可选值:hover / focus / click / customstring'click'
visible气泡框是否展示的受控属性boolean
zIndex浮层 z-index 值number1030
onConfirm点击确认按钮回调Function(e)
onCancel点击取消按钮回调Function(e)
onClickOutSide当弹出层处于展示状态,点击非 Children、非浮层内部区域时的回调Function(e)2.1.0
onEscKeyDown在 trigger 或弹出层按 Esc 键时调用Function(e:event)2.8.0
onVisibleChange气泡框切换显示隐藏的回调Function(visible: boolean): void() => {}

Accessibility

ARIA

语义化请参考 Popover

键盘和焦点

  • Popconfirm 必须带有触发器,触发器可被聚焦,使用 Enter 键打开 Popconfirm
  • Popconfirm 激活后,按下方向键 ⬇️ 将焦点移动到 Popconfirm 上。Popconfirm 的初始焦点应当遵循以下几个原则:
    • 如果 Popconfirm 内包含一个不可逆转过程的最后一个步骤,比如:删除数据等,那么这个初始焦点最好放在破坏性最小的可交互元素上,如:关闭按钮 ( 通过向对象 cancelButtonProps 中传入 autoFocus 实现)
    • 如果 Popconfirm 内仅为阅读文本,那么建议将初始焦点设置在最可能常用的交互元素上,如:确定按钮 ( 通过向对象 okButtonProps 中传入 autoFocus 实现)
  • 键盘用户能够通过按 Esc 关闭 Popconfirm,并且焦点应该返回到触发器上。用户通过 Popconfirm 内的交互元素关闭该 Pop 后,焦点也应当返回到触发器上(仅当 trigger 为 click 时)
  • 打开的情况下,用户点击 Popconfirm 内的空白处 Esc 后,焦点也会回到触发器上 (仅当 trigger 为 click 时)

设计变量

FAQ

  • 为什么 Popconfirm 浮层在靠近屏幕边界宽度不够时,丢失宽度意外换行?
    在 chromium 104 后 对于屏幕边界文本宽度不够时的换行渲染策略发生变化,详细原因可查看 issue #1022,semi侧已经在v2.17.0版本修复了这个问题。