Tooltip 工具提示框

用于辅助的文字提示，可代替 HTML 元素默认的 title 属性。

获取组件

MainIndividual
import { Tooltip, Whisper } from 'rsuite';
  • Tooltip 文字提示。
  • Whisper 监听触发器，包裹被监听对象的外面，触发事件后通知到 <Tooltip> 展示出来。

演示

默认

位置

  • left , top , right , bottom 是物理中的 4 个方向, 表示显示的位置。
  • leftStart , 在 left 后面加了一个 start, 这里的 start 是逻辑方式，表示对齐方式是 Y 轴的开始。

有关 start 和 end 的描述可参照 W3C 关于 CSS 逻辑属性和值（CSS Logical Properties and Values Level 1） 的首份工作草案（First Public Working Draft）

触发事件

Whisper 提供了一个 trigger 属性，用于在各种场景下控制 Tooltip 显示。属性值包括：

  • click: 当用户点击元素时会被触发，再点击会关闭。
  • contextMenu: 当用户点击鼠标右键时触发。
  • focus: 当用户点击或触摸元素或通过键盘的 tab 键选择它时会被触发。
  • hover: 鼠标悬停到元素上时触发，鼠标离开则关闭。
  • active: 激活元素时会被触发。
  • none: 无触发事件，一般用于需要通过方法触发时候使用。

注意: Safari ignoring tabindex

容器与防止溢出

禁用的元素

具有禁用属性的元素禁用后无法将鼠标悬停或单击它们来触发弹出 Tooltip。 解决方法是，您要可以通过包装 <div> 或 <span> 触发叠加层，同时在元素上覆盖 pointer-events 属性。

隐藏箭头

您可以通过设置 arrow 属性为 false 隐藏箭头指示器。

跟随光标

您可以通过设置 followCursor 属性为 true 来让 Tooltip 跟随光标移动。

Props

<Tooltip>

属性名称 类型 (默认值) 描述
arrow boolean (true) 是否显示箭头指示器
children * ReactNode 组件的内容
classPrefix string ('tooltip') 组件 CSS 类的前缀
visible boolean 组件默认可见的

<Whisper>

属性名称 类型 (默认值) 描述
container HTMLElement | (() => HTMLElement) 设置渲染的容器
controlId string 设置 id 到 <Overlay> 上，并且设置 aria-describedby 到 <Whisper> 上
defaultOpen boolean 默认是否显示浮层
delay number 交互延迟时间 (毫秒)
delayClose number 关闭延迟时间 (毫秒)
delayOpen number 打开延迟时间 (毫秒)
enterable boolean 当 trigger 为 hover 时，鼠标是否可以进入浮层内部
followCursor boolean 是否启用浮层跟随光标
onBlur () => void 失去焦点时的回调函数
onClick () => void 点击时的回调函数
onClose () => void 浮层关闭时的回调函数
onEnter () => void 浮层显示前过渡动画的回调函数
onEntered () => void 浮层显示后过渡动画完成的回调函数
onEntering () => void 浮层显示中过渡动画的回调函数
onExit () => void 浮层退出前过渡动画的回调函数
onExited () => void 浮层退出后过渡动画完成的回调函数
onExiting () => void 浮层退出中过渡动画的回调函数
onFocus () => void 获取焦点时的回调函数
onOpen () => void 浮层打开时的回调函数
open boolean 手动控制浮层是否显示
placement Placement ('right') 浮层显示位置
preventOverflow boolean 防止浮层溢出容器边界
speaker * Tooltip | Popover | ReactElement 要显示的浮层组件
trigger Trigger (['hover','focus']) 触发浮层显示的事件，支持数组配置多个事件

Whisper 方法

Whisper 提供了几个可以通过 ref 调用的方法，用于以编程方式控制浮层的显示和位置。这些方法在需要手动触发浮层操作时非常有用，例如：

  • 根据业务逻辑显示/隐藏提示
  • 在内容变化后更新浮层位置
  • 创建自定义的交互逻辑

通过 ref 获取组件实例：

const whisperRef = useRef();

<Whisper ref={whisperRef} {...}>
  <Button>悬停查看</Button>
</Whisper>
方法名 类型定义 说明
open (delay?: number) => void 手动打开浮层，可选的 delay 参数指定延迟时间（毫秒）
close (delay?: number) => void 手动关闭浮层，可选的 delay 参数指定延迟时间（毫秒）
updatePosition () => void 当内容变化导致布局改变时，手动更新浮层位置 
// 在按钮点击时打开浮层
<Button onClick={() => whisperRef.current?.open()}>显示提示</Button>;

// 在数据加载完成后显示浮层
useEffect(() => {
  if (dataLoaded) {
    whisperRef.current?.open(300); // 300ms 后显示
  }
}, [dataLoaded]);

// 内容变化后更新浮层位置
const handleResize = useCallback(() => {
  whisperRef.current?.updatePosition();
}, []);

类型定义

Trigger 

type Trigger =
  | Array<'click' | 'contextMenu' | 'hover' | 'focus' | 'active'>
  | 'click'
  | 'contextMenu'
  | 'hover'
  | 'focus'
  | 'active'
  | 'none';

Placement 

type Placement =
  | 'top'
  | 'bottom'
  | 'right'
  | 'left'
  | 'bottomStart'
  | 'bottomEnd'
  | 'topStart'
  | 'topEnd'
  | 'leftStart'
  | 'leftEnd'
  | 'rightStart'
  | 'rightEnd'
  | 'auto'
  | 'autoVerticalStart'
  | 'autoVerticalEnd'
  | 'autoHorizontalStart'
  | 'autoHorizontalEnd';