工具提示

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

import React from 'react';
import * as Tooltip from '@radix-ui/react-tooltip';
import { PlusIcon } from '@radix-ui/react-icons';
import './styles.css';

const TooltipDemo = () => {
  return (
    <Tooltip.Provider>
      <Tooltip.Root>
        <Tooltip.Trigger asChild>
          <button className="IconButton">
            <PlusIcon />
          </button>
        </Tooltip.Trigger>
        <Tooltip.Portal>
          <Tooltip.Content className="TooltipContent" sideOffset={5}>
            Add to library
            <Tooltip.Arrow className="TooltipArrow" />
          </Tooltip.Content>
        </Tooltip.Portal>
      </Tooltip.Root>
    </Tooltip.Provider>
  );
};

export default TooltipDemo;

特性

提供程序以全局控制显示延迟。

当触发器获得焦点或悬停时打开。

当触发器被激活或按下 Esc 键时关闭。

支持自定义时间。

安装

从命令行安装组件。

npm install @radix-ui/react-tooltip

结构

导入所有部分并将其组合在一起。

import * as Tooltip from '@radix-ui/react-tooltip';

export default () => (
  <Tooltip.Provider>
    <Tooltip.Root>
      <Tooltip.Trigger />
      <Tooltip.Portal>
        <Tooltip.Content>
          <Tooltip.Arrow />
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  </Tooltip.Provider>
);

API 参考

提供程序

包装您的应用程序以向您的工具提示提供全局功能。

属性	类型	默认值
`delayDuration`	`数字`	`700`
`skipDelayDuration`	`数字`	`300`
`disableHoverableContent`	`布尔值`	无默认值

根

包含工具提示的所有部分。

属性	类型	默认值
`defaultOpen`	`布尔值`	无默认值
`open`	`布尔值`	无默认值
`onOpenChange`	`函数`	无默认值
`delayDuration`	`数字`	`700`
`disableHoverableContent`	`布尔值`	无默认值

触发器

切换工具提示的按钮。默认情况下，Tooltip.Content 将自身定位在触发器旁边。

属性	类型	默认值
`asChild`	`布尔值`	`false`

数据属性	值
`[data-state]`	`"closed" \|"delayed-open" \|"instant-open"`

传送门

使用时，将内容部分传送至 body 中。

属性	类型	默认值
`forceMount`	`布尔值`	无默认值
`container`	`HTMLElement`	`document.body`

内容

工具提示打开时弹出的组件。

属性	类型	默认值
`asChild`	`布尔值`	`false`
`aria-label`	`字符串`	无默认值
`onEscapeKeyDown`	`函数`	无默认值
`onPointerDownOutside`	`函数`	无默认值
`forceMount`	`布尔值`	无默认值
`侧边`	`枚举`	`"top"`
`sideOffset`	`数字`	`0`
`对齐`	`枚举`	`"center"`
`alignOffset`	`数字`	`0`
`avoidCollisions`	`布尔值`	`true`
`collisionBoundary`	`边界`	`[]`
`collisionPadding`	`数字 \| 填充`	`0`
`arrowPadding`	`数字`	`0`
`粘性`	`枚举`	`"partial"`
`hideWhenDetached`	`布尔值`	`false`

数据属性	值
`[data-state]`	`"closed" \|"delayed-open" \|"instant-open"`
`[data-side]`	`"left" \|"right" \|"bottom" \|"top"`
`[data-align]`	`"start" \|"end" \|"center"`

CSS 变量	描述
`--radix-tooltip-content-transform-origin`	从内容和箭头位置/偏移量计算出的 `transform-origin`
`--radix-tooltip-content-available-width`	触发器和边界边缘之间的剩余宽度
`--radix-tooltip-content-available-height`	触发器和边界边缘之间的剩余高度
`--radix-tooltip-trigger-width`	触发器的宽度
`--radix-tooltip-trigger-height`	触发器的高度

箭头

一个可选的箭头元素，用于与工具提示一起渲染。这可以用来帮助视觉上将触发器与 Tooltip.Content 关联。必须渲染在 Tooltip.Content 内。

属性	类型	默认值
`asChild`	`布尔值`	`false`
`宽度`	`数字`	`10`
`高度`	`数字`	`5`

示例

全局配置

使用 Provider 全局控制 delayDuration 和 skipDelayDuration。

import * as Tooltip from '@radix-ui/react-tooltip';

export default () => (
  <Tooltip.Provider delayDuration={800} skipDelayDuration={500}>
    <Tooltip.Root>
      <Tooltip.Trigger>…</Tooltip.Trigger>
      <Tooltip.Content>…</Tooltip.Content>
    </Tooltip.Root>
    <Tooltip.Root>
      <Tooltip.Trigger>…</Tooltip.Trigger>
      <Tooltip.Content>…</Tooltip.Content>
    </Tooltip.Root>
  </Tooltip.Provider>
);

立即显示

使用 delayDuration 属性来控制工具提示打开所需的时间。

import * as Tooltip from '@radix-ui/react-tooltip';

export default () => (
  <Tooltip.Root delayDuration={0}>
    <Tooltip.Trigger>…</Tooltip.Trigger>
    <Tooltip.Content>…</Tooltip.Content>
  </Tooltip.Root>
);

约束内容大小

您可能希望约束内容的宽度，使其与触发器宽度匹配。您可能还希望约束其高度，使其不超过视口。

我们公开了几个 CSS 自定义属性，例如 --radix-tooltip-trigger-width 和 --radix-tooltip-content-available-height 来支持这一点。使用它们来约束内容尺寸。

// index.jsx
import * as Tooltip from '@radix-ui/react-tooltip';
import './styles.css';

export default () => (
  <Tooltip.Root>
    <Tooltip.Trigger>…</Tooltip.Trigger>
    <Tooltip.Portal>
      <Tooltip.Content className="TooltipContent" sideOffset={5}>
        …
      </Tooltip.Content>
    </Tooltip.Portal>
  </Tooltip.Root>
);

/* styles.css */
.TooltipContent {
  width: var(--radix-tooltip-trigger-width);
  max-height: var(--radix-tooltip-content-available-height);
}

源感知动画

我们公开了 CSS 自定义属性 --radix-tooltip-content-transform-origin。使用它根据 side、sideOffset、align、alignOffset 和任何碰撞来从其计算出的原点为内容设置动画。

// index.jsx
import * as Tooltip from '@radix-ui/react-tooltip';
import './styles.css';

export default () => (
  <Tooltip.Root>
    <Tooltip.Trigger>…</Tooltip.Trigger>
    <Tooltip.Content className="TooltipContent">…</Tooltip.Content>
  </Tooltip.Root>
);

/* styles.css */
.TooltipContent {
  transform-origin: var(--radix-tooltip-content-transform-origin);
  animation: scaleIn 0.5s ease-out;
}

@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

碰撞感知动画

我们公开了 data-side 和 data-align 属性。它们的值将在运行时更改以反映碰撞。使用它们创建碰撞和方向感知动画。

// index.jsx
import * as Tooltip from '@radix-ui/react-tooltip';
import './styles.css';

export default () => (
  <Tooltip.Root>
    <Tooltip.Trigger>…</Tooltip.Trigger>
    <Tooltip.Content className="TooltipContent">…</Tooltip.Content>
  </Tooltip.Root>
);

/* styles.css */
.TooltipContent {
  animation-duration: 0.6s;
  animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.TooltipContent[data-side='top'] {
  animation-name: slideUp;
}
.TooltipContent[data-side='bottom'] {
  animation-name: slideDown;
}

@keyframes slideDown {
  from {
    opacity: 0;
    transform: translateY(-10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes slideUp {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

可访问性

键盘交互

键	描述
`Tab`	立即打开/关闭工具提示。
`空格`	如果已打开，则立即关闭工具提示。
`回车`	如果已打开，则立即关闭工具提示。
`Esc`	如果已打开，则立即关闭工具提示。

自定义 API

通过将基本部分抽象到您自己的组件中来创建您自己的 API。

抽象部分并引入内容属性

此示例抽象了所有 Tooltip 部分，并引入了新的 content 属性。

用法

import { Tooltip } from './your-tooltip';

export default () => (
  <Tooltip content="Tooltip content">
    <button>Tooltip trigger</button>
  </Tooltip>
);

实现

使用 asChild 属性将触发器部分转换为可插槽区域。它将用传递给它的子元素替换触发器。

// your-tooltip.jsx
import React from 'react';
import * as TooltipPrimitive from '@radix-ui/react-tooltip';

export function Tooltip({
  children,
  content,
  open,
  defaultOpen,
  onOpenChange,
  ...props
}) {
  return (
    <TooltipPrimitive.Root
      open={open}
      defaultOpen={defaultOpen}
      onOpenChange={onOpenChange}
    >
      <TooltipPrimitive.Trigger asChild>
        {children}
      </TooltipPrimitive.Trigger>
      <TooltipPrimitive.Content side="top" align="center" {...props}>
        {content}
        <TooltipPrimitive.Arrow width={11} height={5} />
      </TooltipPrimitive.Content>
    </TooltipPrimitive.Root>
  );
}

上一页工具栏

下一页无障碍图标

在 GitHub 上编辑此页面。

概述

指南

组件

实用程序

特性

用法

实现