完整的 API 参考、样式指南与高级示例请参阅 v3 Tooltip 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Tooltip 使用 content prop：

import { Tooltip, Button } from "@heroui/react";

export default function App() {
  return (
    <Tooltip content="I am a tooltip">
      <Button>Hover me</Button>
    </Tooltip>
  );
}

在 v3 中，Tooltip 需要复合组件：

import { Tooltip, Button } from "@heroui/react";

export default function App() {
  return (
    <Tooltip>
      <Tooltip.Trigger>
        <Button>Hover me</Button>
      </Tooltip.Trigger>
      <Tooltip.Content>
        I am a tooltip
      </Tooltip.Content>
    </Tooltip>
  );
}

主要变化

1. 组件结构

v2： 通过 content prop 与作为触发器的 children 使用 Tooltip
v3： 复合组件（Tooltip.Trigger、Tooltip.Content、Tooltip.Arrow）

2. Prop 变更

v2 prop	v3 位置	说明
`content`	—	请使用 `Tooltip.Content` 的 children
`showArrow`	`showArrow`（在 Content 上）	移至 `Tooltip.Content`
`placement`	`placement`（在 Content 上）	移至 `Tooltip.Content`
`offset`	`offset`（在 Content 上）	移至 `Tooltip.Content`
`color`	—	已移除（请使用 Tailwind CSS）
`size`	—	已移除（请使用 Tailwind CSS）
`radius`	—	已移除（请使用 Tailwind CSS）
`shadow`	—	已移除（请使用 Tailwind CSS）
`classNames`	—	请在各子组件上使用 `className`
`motionProps`	—	已移除（动画机制已不同）
`trigger`	`trigger`（在根上）	仍存在：`"hover"` \| `"focus"`（默认 `"hover"`）
`isDisabled`	`isDisabled`（在根上）	v3 新增：可完全禁用 Tooltip
`delay`	`delay`（在根上）	仍存在（默认由 `0` 改为 `700`）
`closeDelay`	`closeDelay`（在根上）	仍存在（默认 `0`）
`portalContainer`	—	不再对外暴露
`updatePositionDeps`	—	不再对外暴露
`containerPadding`, `crossOffset`	—	不再对外暴露
`shouldFlip`	—	自动处理
`triggerScaleOnOpen`	—	不可用
`isKeyboardDismissDisabled`	—	不可用
`isDismissable`	—	不可用
`shouldCloseOnBlur`	—	不可用
`shouldCloseOnInteractOutside`	—	不可用
`onClose`	—	请改用 `onOpenChange`

3. 移至 `Tooltip.Content` 的 prop

showArrow — 现位于 Tooltip.Content
placement — 现位于 Tooltip.Content
offset — 现位于 Tooltip.Content

迁移示例

内容配置

{/* With arrow */}
<Tooltip content="I am a tooltip" showArrow>
  <Button>Hover me</Button>
</Tooltip>

{/* With placement */}
<Tooltip content="Tooltip" placement="bottom">
  <Button>Hover me</Button>
</Tooltip>

{/* With offset */}
<Tooltip content="Tooltip" offset={12}>
  <Button>Hover me</Button>
</Tooltip>

{/* With arrow */}
<Tooltip delay={0}>
  <Tooltip.Trigger>
    <Button>Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content showArrow>
    <Tooltip.Arrow />
    <p>I am a tooltip</p>
  </Tooltip.Content>
</Tooltip>

{/* With placement */}
<Tooltip delay={0}>
  <Tooltip.Trigger>
    <Button>Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content placement="bottom">
    <p>Tooltip</p>
  </Tooltip.Content>
</Tooltip>

{/* With offset */}
<Tooltip delay={0}>
  <Tooltip.Trigger>
    <Button>Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content offset={12}>
    <p>Tooltip</p>
  </Tooltip.Content>
</Tooltip>

import { useState } from "react";

const [isOpen, setIsOpen] = useState(false);

<Tooltip
  content="I am a tooltip"
  isOpen={isOpen}
  onOpenChange={setIsOpen}
>
  <Button>Hover me</Button>
</Tooltip>

import { useState } from "react";

const [isOpen, setIsOpen] = useState(false);

<Tooltip isOpen={isOpen} onOpenChange={setIsOpen} delay={0}>
  <Tooltip.Trigger>
    <Button>Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>
    <p>I am a tooltip</p>
  </Tooltip.Content>
</Tooltip>

带延迟

<Tooltip content="Tooltip" delay={500} closeDelay={200}>
  <Button>Hover me</Button>
</Tooltip>

<Tooltip delay={500} closeDelay={200}>
  <Tooltip.Trigger>
    <Button>Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>
    <p>Tooltip</p>
  </Tooltip.Content>
</Tooltip>

自定义内容

<Tooltip
  content={
    <div>
      <strong>Title</strong>
      <p>Description</p>
    </div>
  }
>
  <Button>Hover me</Button>
</Tooltip>

<Tooltip delay={0}>
  <Tooltip.Trigger>
    <Button>Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>
    <div>
      <strong>Title</strong>
      <p>Description</p>
    </div>
  </Tooltip.Content>
</Tooltip>

自定义触发器

<Tooltip content="Tooltip">
  <div className="custom-trigger">Custom trigger</div>
</Tooltip>

<Tooltip delay={0}>
  <Tooltip.Trigger className="custom-trigger">
    <div>Custom trigger</div>
  </Tooltip.Trigger>
  <Tooltip.Content>
    <p>Tooltip</p>
  </Tooltip.Content>
</Tooltip>

组件组成

v3 Tooltip 的结构如下：

Tooltip (Root)
  ├── Tooltip.Trigger
  │   └── [Trigger element]
  └── Tooltip.Content
      ├── Tooltip.Arrow (optional)
      └── [Tooltip content]

v3 新增 prop

isDisabled

isDisabled prop 可完全禁用 Tooltip。禁用后，悬停或聚焦时都不会显示提示：

<Tooltip isDisabled>
  <Tooltip.Trigger>
    <Button>No tooltip</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>
    <p>This will not show</p>
  </Tooltip.Content>
</Tooltip>

trigger

trigger prop 控制 Tooltip 的激活方式，取值为 "hover"（默认）或 "focus"：

{/* Show tooltip only on focus */}
<Tooltip trigger="focus">
  <Tooltip.Trigger>
    <Button>Focus me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>
    <p>Shown on focus only</p>
  </Tooltip.Content>
</Tooltip>