Tooltip - Kumo 中文文档

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
import { PlusIcon } from "@phosphor-icons/react";

export function TooltipHeroDemo() {
  return (
    <TooltipProvider>
      <Tooltip
        content="Add new item"
        render={
          <Button shape="square" icon={PlusIcon} aria-label="Add new item" />
        }
      />
    </TooltipProvider>
  );
}

安装

批量导入

import { Tooltip, TooltipProvider } from "@cloudflare/kumo";

细粒度导入

import { Tooltip, TooltipProvider } from "@cloudflare/kumo/components/tooltip";

用法

import { Tooltip, Button } from "@cloudflare/kumo";

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

关于跨多个 tooltip 的延迟分组，参见 TooltipProvider。

示例

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
import { PlusIcon } from "@phosphor-icons/react";

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

多个 Tooltip

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";
import { PlusIcon, TranslateIcon } from "@phosphor-icons/react";

export function TooltipMultipleDemo() {
  return (
    <TooltipProvider>
      <div className="flex gap-2">
        <Tooltip
          content="Add"
          render={<Button shape="square" icon={PlusIcon} aria-label="Add" />}
        />
        <Tooltip
          content="Change language"
          render={
            <Button
              shape="square"
              icon={TranslateIcon}
              aria-label="Change language"
            />
          }
        />
      </div>
    </TooltipProvider>
  );
}

长内容 / 溢出

内容较长的 tooltip 会利用 Base UI Positioner 提供的 --available-width, 自动把宽度限制在视口可用空间内。把鼠标悬停到边缘按钮上，可以看到 tooltip 自动换行而不是溢出视口。

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";

/**
 * Control the delay before opening and closing the tooltip.
 * `delay` controls open delay (default: 600ms), `closeDelay` controls close delay (default: 0ms).
 */
/**
 * Demonstrates that long tooltip content respects available viewport space.
 * Tooltips near the edge of the viewport constrain their width to
 * `--available-width` so they don't overflow.
 */
export function TooltipOverflowDemo() {
  const longContent =
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco.";
  return (
    <TooltipProvider>
      <div className="flex w-full justify-between">
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          Near left edge
        </Tooltip>
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          Centered
        </Tooltip>
        <Tooltip
          content={longContent}
          side="bottom"
          render={<Button variant="secondary" />}
        >
          Near right edge
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

延迟控制

用 delay 控制打开前的等待时长 (默认 600ms), 用 closeDelay 控制关闭前的等待时长 (默认 0ms)。

import { Tooltip, TooltipProvider, Button } from "@cloudflare/kumo";

export function TooltipDelayDemo() {
  return (
    <TooltipProvider>
      <div className="flex gap-4">
        <Tooltip
          content="Opens after 1 second"
          delay={1000}
          render={<Button variant="secondary" />}
        >
          1s open delay
        </Tooltip>
        <Tooltip
          content="Stays open 500ms after leaving"
          closeDelay={500}
          render={<Button variant="secondary" />}
        >
          500ms close delay
        </Tooltip>
        <Tooltip
          content="Instant open, stays 1s"
          delay={0}
          closeDelay={1000}
          render={<Button variant="secondary" />}
        >
          Instant + 1s close
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

TooltipProvider

TooltipProvider 把多个 tooltip 分组：第一个 tooltip 显示之后，切换到其他 tooltip 时会跳过打开延迟。只需在应用根部或布局中放置一次——不要包在每个 Tooltip 外面。

// 在应用或布局外包一层即可
<TooltipProvider>
  <App />
</TooltipProvider>

// 之后可在内部任意位置使用 Tooltip
<Tooltip content="Add" render={<Button shape="square" icon={PlusIcon} />} />

API 参考

属性	类型	默认值	说明
side	`"top" \| "bottom" \| "left" \| "right"`	`"top"`	-
className	`string`	-	Additional CSS classes
children	`ReactNode`	-	Child elements
content*	`ReactNode`	-	Content to display in the tooltip

TooltipProvider

属性	类型	默认值	说明
delay	`number`	`600`	How long to wait (ms) before opening a tooltip once the pointer enters the trigger.
closeDelay	`number`	`0`	How long to wait (ms) before closing a tooltip.
timeout	`number`	`400`	Grace period (ms) during which a just-closed tooltip's delay is skipped when another tooltip opens.