Balloon

气泡组件。

何时使用 #

  • 当用户与被说明对象（文字，图片，输入框等）发生交互行为的 action 开始时，即刻跟随动作出现一种辅助或帮助的提示信息。
  • 其中 Balloon.Tooltip 是简化版本，主要用于 hover 时显示简单文案

v2 版本更新指示 #

1.25 版本增加 v2 支持开启新版本弹，功能如下

  • 底层更换 v2 版本弹窗组件，可根据空间动态调整位置，解决页面滚动造成弹窗脱离的问题
  • 默认边缘对齐，增加 arrowPointToCenter 开启后箭头指向中间

如何使用 #

  • 对于 trigger 是自定义的 React Component 的情况，自定义的 React Component 需要透传 onMouseEnter/onMouseLeave/onClick 事件。
  • 若要使用无障碍的气泡提示，请传入 id。推荐简单提示使用<Tooltip>、复杂交互使用<Balloon triggerType="click"> 。 triggerType="focus"作为辅助状态用于组件内部，请用户不要直接使用此值。

代码演示 #

类型 #

常见气泡使用类型

三种触发方式 #

鼠标移入、聚集、点击。

位置 #

位置有十二个方向。

箭头指向中间 #

常见气泡使用类型

嵌套浮层问题 #

浮层中如果又有浮层，比如在Balloon中有DatePicker/Select的浮层, DatePicker选择时，Balloon浮层也会关闭。可以用 followTrigger解决。

Tooltip的方位 #

简化的Balloon, 只能设置align, trigger和children, 触发条件是hover.

Tooltip使用场景 #

一般用于文字超长溢出等场景

API #

Balloon V2 #

参数 说明 类型 默认值 是否必填 支持版本
v2 开启 v2 版本 true - 1.25
children 浮层的内容 ReactNode - -
type 样式类型 'normal' | 'primary' 'normal' 1.23
title 标题 ReactNode - 1.23
visible 弹层当前显示的状态 boolean - -
defaultVisible 弹层默认显示的状态 boolean false -
onVisibleChange 弹层在显示和隐藏触发的事件

签名:
参数:
visible: 弹层是否隐藏和显示
type: 触发弹层显示或隐藏的来源，closeClick 表示由自带的关闭按钮触发；fromTrigger 表示由 trigger 的点击触发；docClick 表示由 document 的点击触发		 (visible: boolean, type: string) => void - -
arrowPointToCenter [v2] 箭头是否指向目标元素的中心 boolean false 1.25
placementOffset [v2] 弹层偏离触发元素的像素值 number - -
closable 是否显示关闭按钮 boolean true -
align 弹出层位置 AlignType 'b' -
offset 弹层相对于 trigger 的定位的微调，接收数组 [hoz, ver], 表示弹层在 left / top 上的增量，e.g. [100, 100] 表示往右 (RTL 模式下是往左) 、下分布偏移 100px Array<number> [0, 0] -
trigger 触发元素 ReactElement | string -
triggerType 触发行为，鼠标悬浮，鼠标点击 ('hover','click') 或者它们组成的数组，如 ['hover', 'click'], 强烈不建议使用'focus'，若弹窗内容有复杂交互请使用 click 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')[] 'hover' -
onClose 任何 visible 为 false 时会触发的事件 () => void - -
autoAdjust [v2] 是否进行自动位置调整，默认自动开启 boolean - 1.25
delay 弹层在触发以后的延时显示，单位毫秒 ms number - -
afterClose 浮层关闭后触发的事件，如果有动画，则在动画结束后触发 () => void - -
autoFocus 弹层出现后是否自动 focus 到内部第一个元素 boolean true -
safeNode 安全节点：对于 triggetType 为 click 的浮层，会在点击除了浮层外的其它区域时关闭浮层.safeNode 用于添加不触发关闭的节点，值可以是 dom 节点的 id 或者是节点的 dom 对象 string | ReactNode - -
safeId 用来指定 safeNode 节点的 id，和 safeNode 配合使用 string null -
animation 配置动画的播放方式，格式是 { in: '', out: '' }，常用的动画 class 请查看 Animate 组件文档

签名:
参数:
in: 进场动画
out: 出场动画		 string | false | Record<'in' | 'out', string> { in: 'zoomIn zoomInBig', out: 'zoomOut zoomOutBig', } -
cache 弹层的 dom 节点关闭时是否删除 boolean false -
popupContainer 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。 PopupProps['container'] - -
popupStyle 弹层组件 style，透传给 Popup CSSProperties - -
popupClassName 弹层组件 className，透传给 Popup string - -
popupProps 弹层组件属性，透传给 Popup ComponentPropsWithRef<typeof Popup> - -
followTrigger 跟随滚动 boolean - -
id 弹层 id, 传入值才会支持无障碍 string - -

Balloon V1 #

参数 说明 类型 默认值 是否必填 支持版本
v2 开启 v2 版本 false | undefined - 1.25
children 浮层的内容 ReactNode - -
title 标题 ReactNode - 1.23
type 样式类型 'normal' | 'primary' 'normal' 1.23
visible 弹层当前显示的状态 boolean - -
defaultVisible 弹层默认显示的状态 boolean false -
onVisibleChange 弹层在显示和隐藏触发的事件

签名:
参数:
visible: 弹层是否隐藏和显示
type: 触发弹层显示或隐藏的来源，closeClick 表示由自带的关闭按钮触发；fromTrigger 表示由 trigger 的点击触发；docClick 表示由 document 的点击触发		 (visible: boolean, type: string) => void - -
closable 是否显示关闭按钮 boolean true -
align 弹出层位置 AlignType 'b' -
offset 弹层相对于 trigger 的定位的微调，接收数组 [hoz, ver], 表示弹层在 left / top 上的增量，e.g. [100, 100] 表示往右 (RTL 模式下是往左) 、下分布偏移 100px Array<number> [0, 0] -
trigger 触发元素 ReactElement | string -
triggerType 触发行为，鼠标悬浮，鼠标点击 ('hover','click') 或者它们组成的数组，如 ['hover', 'click'], 强烈不建议使用'focus'，若弹窗内容有复杂交互请使用 click 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')[] 'hover' -
onClose 任何 visible 为 false 时会触发的事件 () => void - -
delay 弹层在触发以后的延时显示，单位毫秒 ms number - -
afterClose 浮层关闭后触发的事件，如果有动画，则在动画结束后触发 () => void - -
autoFocus 弹层出现后是否自动 focus 到内部第一个元素 boolean true -
safeNode 安全节点：对于 triggetType 为 click 的浮层，会在点击除了浮层外的其它区域时关闭浮层.safeNode 用于添加不触发关闭的节点，值可以是 dom 节点的 id 或者是节点的 dom 对象 string | ReactNode - -
safeId 用来指定 safeNode 节点的 id，和 safeNode 配合使用 string null -
animation 配置动画的播放方式，格式是 { in: '', out: '' }，常用的动画 class 请查看 Animate 组件文档

签名:
参数:
in: 进场动画
out: 出场动画		 string | false | Record<'in' | 'out', string> { in: 'zoomIn zoomInBig', out: 'zoomOut zoomOutBig', } -
cache 弹层的 dom 节点关闭时是否删除 boolean false -
popupContainer 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。 PopupProps['container'] - -
popupStyle 弹层组件 style，透传给 Popup CSSProperties - -
popupClassName 弹层组件 className，透传给 Popup string - -
popupProps 弹层组件属性，透传给 Popup ComponentPropsWithRef<typeof Popup> - -
followTrigger 跟随滚动 boolean - -
id 弹层 id, 传入值才会支持无障碍 string - -

Balloon.Tooltip V2 #

参数 说明 类型 默认值 是否必填
v2 开启 v2 true -
children tooltip 的内容 ReactNode -
align 弹出层位置 AlignType 'b'
trigger 触发元素 ReactElement | string
triggerType 触发行为，鼠标悬浮，鼠标点击 ('hover', 'click') 或者它们组成的数组，如 ['hover', 'click'], 强烈不建议使用'focus'，若有复杂交互，推荐使用 triggerType 为 click 的 Balloon 组件 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')[] 'hover'
popupStyle 弹层组件 style，透传给 Popup CSSProperties -
popupClassName 弹层组件 className，透传给 Popup string -
popupProps 弹层组件属性，透传给 Popup ComponentPropsWithRef<typeof Popup> -
pure 是否 pure render boolean -
popupContainer 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。 PopupProps['container'] -
followTrigger 是否跟随滚动 boolean -
id 弹层 id, 传入值才会支持无障碍 string -
delay 如果需要让 Tooltip 内容可被点击，可以设置这个参数，例如 100px number 50
arrowPointToCenter [v2] 箭头是否指向目标元素的中心 boolean false

Balloon.Tooltip V1 #

参数 说明 类型 默认值 是否必填
v2 开启 v2 false | undefined -
children tooltip 的内容 ReactNode -
align 弹出层位置 AlignType 'b'
trigger 触发元素 ReactElement | string
triggerType 触发行为，鼠标悬浮，鼠标点击 ('hover', 'click') 或者它们组成的数组，如 ['hover', 'click'], 强烈不建议使用'focus'，若有复杂交互，推荐使用 triggerType 为 click 的 Balloon 组件 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')[] 'hover'
popupStyle 弹层组件 style，透传给 Popup CSSProperties -
popupClassName 弹层组件 className，透传给 Popup string -
popupProps 弹层组件属性，透传给 Popup ComponentPropsWithRef<typeof Popup> -
pure 是否 pure render boolean -
popupContainer 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。 PopupProps['container'] -
followTrigger 是否跟随滚动 boolean -
id 弹层 id, 传入值才会支持无障碍 string -
delay 如果需要让 Tooltip 内容可被点击，可以设置这个参数，例如 100px number 50

无障碍键盘操作指南 #

按键 说明
SPACE 当triggerType=‘click’时，点击会弹出提示
Enter 当triggerType=‘click’时，点击会弹出提示