Tooltip 工具提示
@lark-ui/core

Tooltip 工具提示

当元素获得键盘焦点或鼠标悬停在其上时，显示与该元素相关信息的弹出层。

import { Tooltip, TooltipProvider, Button } from "@lark-ui/core";
import { PlusIcon } from "@phosphor-icons/react";

export function TooltipHeroDemo() {
  return (
    <TooltipProvider>
      <Tooltip
        content="添加新条目"
        render={
          <Button shape="square" icon={PlusIcon} aria-label="添加新条目" />
        }
      />
    </TooltipProvider>
  );
}

安装

统一导出

import { Tooltip, TooltipProvider } from "@lark-ui/core";

按需导出

import { Tooltip, TooltipProvider } from "@lark-ui/core/components/tooltip";

用法

import { Tooltip, Button } from "@lark-ui/core";

export default function Example() {
  return (
    <Tooltip content="Tooltip text" render={<Button />}>
      Hover me
    </Tooltip>
  );
}

如需在多个工具提示（Tooltip）之间共享延迟分组，请参见 TooltipProvider。

示例

基础工具提示

import { Tooltip, TooltipProvider, Button } from "@lark-ui/core";
import { PlusIcon } from "@phosphor-icons/react";

export function TooltipBasicDemo() {
  return (
    <TooltipProvider>
      <Tooltip
        content="添加"
        render={<Button shape="square" icon={PlusIcon} aria-label="添加" />}
      />
    </TooltipProvider>
  );
}

多个工具提示

import { Tooltip, TooltipProvider, Button } from "@lark-ui/core";
import { PlusIcon, TranslateIcon } from "@phosphor-icons/react";

export function TooltipMultipleDemo() {
  return (
    <TooltipProvider>
      <div className="flex gap-2">
        <Tooltip
          content="添加"
          render={<Button shape="square" icon={PlusIcon} aria-label="添加" />}
        />
        <Tooltip
          content="更改语言"
          render={
            <Button shape="square" icon={TranslateIcon} aria-label="更改语言" />
          }
        />
      </div>
    </TooltipProvider>
  );
}

超长内容 / 溢出

内容较长的工具提示会通过 Base UI 的 Positioner 提供的 --available-width， 自动把宽度限制在视口的可用空间内。悬停在边缘按钮上，即可看到工具提示换行而不是溢出视口。

import { Tooltip, TooltipProvider, Button } from "@lark-ui/core";

/**
 * Control the delay before opening and closing the tooltip.
 * `delay` controls open delay (default: 600ms), `closeDelay` controls close delay (default: 0ms).
 */
/**
 * 演示较长的工具提示内容会遵守可用的视口空间。
 * 靠近视口边缘的工具提示会将宽度限制为 `--available-width`，从而不会溢出。
 */
export function TooltipOverflowDemo() {
  const longContent =
    "这是一段用于验证工具提示在视口空间不足时如何换行与约束宽度的占位文本，内容需要足够长才能触发宽度上限与溢出处理，用来检查浮层不会超出屏幕边界。";
  return (
    <TooltipProvider>
      <div className="flex w-full justify-between">
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          靠近左边缘
        </Tooltip>
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          居中
        </Tooltip>
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          靠近右边缘
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

延迟控制

使用 delay 控制打开前的等待时长（默认 600ms）， 使用 closeDelay 控制关闭前的等待时长（默认 0ms）。

import { Tooltip, TooltipProvider, Button } from "@lark-ui/core";

export function TooltipDelayDemo() {
  return (
    <TooltipProvider>
      <div className="flex gap-4">
        <Tooltip
          content="1 秒后打开"
          delay={1000}
          render={<Button variant="secondary" />}
        >
          1 秒打开延迟
        </Tooltip>
        <Tooltip
          content="离开后保持打开 500 毫秒"
          closeDelay={500}
          render={<Button variant="secondary" />}
        >
          500 毫秒关闭延迟
        </Tooltip>
        <Tooltip
          content="立即打开，保持 1 秒"
          delay={0}
          closeDelay={1000}
          render={<Button variant="secondary" />}
        >
          立即打开 + 1 秒后关闭
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

TooltipProvider

TooltipProvider 会把多个工具提示分组在一起，这样在显示过第一个工具提示之后， 切换到其他工具提示时就会跳过打开延迟。请在应用根节点或布局中放置一次即可——不要为每个单独的 Tooltip 包裹。

// Wrap your app or layout once
<TooltipProvider>
  <App />
</TooltipProvider>

// Then use Tooltip anywhere inside
<Tooltip content="Add" render={<Button shape="square" icon={PlusIcon} />} />

API 参考

Tooltip

属性类型默认值说明
side"top" | "bottom" | "left" | "right""top"-
classNamestring-额外的 CSS 类名
childrenReactNode-子元素
content*ReactNode-工具提示中显示的内容

TooltipProvider

属性类型默认值说明
delaynumber600指针进入触发元素后，延迟多少毫秒（ms）打开工具提示。
closeDelaynumber0延迟多少毫秒（ms）关闭工具提示。
timeoutnumber400宽限期（ms），在此期间新打开的工具提示会跳过刚关闭工具提示的延迟。