Tooltip

Tooltip 从 HeroUI v2 到 v3 的迁移指南。

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

结构变化

在 v2 中，Tooltip 使用 content prop：

1import { Tooltip, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Tooltip content="I am a tooltip">6      <Button>Hover me</Button>7    </Tooltip>8  );9}

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

1import { Tooltip, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Tooltip>6      <Tooltip.Trigger>7        <Button>Hover me</Button>8      </Tooltip.Trigger>9      <Tooltip.Content>10        I am a tooltip11      </Tooltip.Content>12    </Tooltip>13  );14}

主要变化

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

迁移示例

内容配置

1{/* With arrow */}2<Tooltip content="I am a tooltip" showArrow>3  <Button>Hover me</Button>4</Tooltip>5
6{/* With placement */}7<Tooltip content="Tooltip" placement="bottom">8  <Button>Hover me</Button>9</Tooltip>10
11{/* With offset */}12<Tooltip content="Tooltip" offset={12}>13  <Button>Hover me</Button>14</Tooltip>

1import { useState } from "react";2
3const [isOpen, setIsOpen] = useState(false);4
5<Tooltip6  content="I am a tooltip"7  isOpen={isOpen}8  onOpenChange={setIsOpen}9>10  <Button>Hover me</Button>11</Tooltip>

带延迟

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

自定义内容

1<Tooltip2  content={3    <div>4      <strong>Title</strong>5      <p>Description</p>6    </div>7  }8>9  <Button>Hover me</Button>10</Tooltip>

自定义触发器

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

组件组成

v3 Tooltip 的结构如下：

1Tooltip (Root)2  ├── Tooltip.Trigger3  │   └── [Trigger element]4  └── Tooltip.Content5      ├── Tooltip.Arrow (optional)6      └── [Tooltip content]

v3 新增 prop

isDisabled

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

1<Tooltip isDisabled>2  <Tooltip.Trigger>3    <Button>No tooltip</Button>4  </Tooltip.Trigger>5  <Tooltip.Content>6    <p>This will not show</p>7  </Tooltip.Content>8</Tooltip>

trigger

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

1{/* Show tooltip only on focus */}2<Tooltip trigger="focus">3  <Tooltip.Trigger>4    <Button>Focus me</Button>5  </Tooltip.Trigger>6  <Tooltip.Content>7    <p>Shown on focus only</p>8  </Tooltip.Content>9</Tooltip>

自定义渲染函数

Tooltip.Content 与 Tooltip.Arrow 均支持 render prop，可在高级场景下用自定义渲染函数覆盖默认 DOM 元素。

说明

`content` prop

v2： 使用 content prop 传入提示文本 / 内容
v3： 内容作为 Tooltip.Content 的 children

箭头

v2： 由根上的 showArrow 控制
v3： 在 Tooltip.Content 上使用 showArrow，并包含 Tooltip.Arrow 组件

placement 与 offset

v2： placement 与 offset 在根上
v3： placement 与 offset 移至 Tooltip.Content

触发元素

v2： children 自动作为触发器
v3： 必须将触发元素包在 Tooltip.Trigger 内

默认延迟

v2： delay 默认为 0
v3： delay 默认为 700（注意：示例中使用 delay={0} 以贴近 v2 行为）

总结

组件结构：必须使用复合组件（Tooltip.Trigger、Tooltip.Content、Tooltip.Arrow）
content prop 已移除：请使用 Tooltip.Content 的 children
prop 迁移：showArrow、placement、offset 移至 Tooltip.Content
样式相关 prop 已移除：color、size、radius、shadow — 请使用 Tailwind CSS
classNames 已移除：请在各子组件上使用 className
motionProps 已移除：动画机制已不同
高级 prop 已移除：大量定位与行为相关 prop 已移除
默认延迟变更：默认由 0 改为 700
isDisabled prop：v3 新增，可完全禁用 Tooltip
trigger prop：取 "hover"（默认）或 "focus"，用于控制激活方式
渲染 prop：Tooltip.Content 与 Tooltip.Arrow 支持 render prop，用于自定义 DOM 渲染