# 工具提示

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

## Features

- 提供者控制全局显示延迟。

- 在触发器获得焦点或被悬停时打开。

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

- 支持自定义时间设置。

## [Anatomy](#anatomy)

导入所有部件并将它们组合在一起。

```jsx
import { Tooltip } from "radix-ui";

export default () => (
  <Tooltip.Provider>
    <Tooltip.Root>
      <Tooltip.Trigger />

      <Tooltip.Portal>
        <Tooltip.Content>
          <Tooltip.Arrow />
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  </Tooltip.Provider>
);
```

## [API 参考](#api-参考)

### [Provider](#provider)

将您的应用程序包裹起来，为工具提示提供全局功能。

| Prop                      | Type      | Default          |
| ------------------------- | --------- | ---------------- |
| `delayDuration`           | `number`  | `700`            |
| `skipDelayDuration`       | `number`  | `300`            |
| `disableHoverableContent` | `boolean` | No default value |

### [Root](#root)

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

| Prop                      | Type       | Default          |
| ------------------------- | ---------- | ---------------- |
| `defaultOpen`             | `boolean`  | No default value |
| `open`                    | `boolean`  | No default value |
| `onOpenChange`            | `function` | No default value |
| `delayDuration`           | `number`   | `700`            |
| `disableHoverableContent` | `boolean`  | No default value |

### [Trigger](#trigger)

切换工具提示的按钮。默认情况下，`Tooltip.Content` 会根据触发器的位置。

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | `false` |

| Data attribute | Values                                         |
| -------------- | ---------------------------------------------- |
| `[data-state]` | `"closed" \| "delayed-open" \| "instant-open"` |

### [Portal](#portal)

使用时，将内容部分门户到 `body` 中。

| Prop         | Type          | Default          |
| ------------ | ------------- | ---------------- |
| `forceMount` | `boolean`     | No default value |
| `container`  | `HTMLElement` | `document.body`  |

### [Content](#content)

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

| Prop                   | Type                | Default          |
| ---------------------- | ------------------- | ---------------- |
| `asChild`              | `boolean`           | `false`          |
| `aria-label`           | `string`            | No default value |
| `onEscapeKeyDown`      | `function`          | No default value |
| `onPointerDownOutside` | `function`          | No default value |
| `forceMount`           | `boolean`           | No default value |
| `side`                 | `enum`              | `"top"`          |
| `sideOffset`           | `number`            | `0`              |
| `align`                | `enum`              | `"center"`       |
| `alignOffset`          | `number`            | `0`              |
| `avoidCollisions`      | `boolean`           | `true`           |
| `collisionBoundary`    | `Boundary`          | `[]`             |
| `collisionPadding`     | `number \| Padding` | `0`              |
| `arrowPadding`         | `number`            | `0`              |
| `sticky`               | `enum`              | `"partial"`      |
| `hideWhenDetached`     | `boolean`           | `false`          |

| Data attribute | Values                                         |
| -------------- | ---------------------------------------------- |
| `[data-state]` | `"closed" \| "delayed-open" \| "instant-open"` |
| `[data-side]`  | `"left" \| "right" \| "bottom" \| "top"`       |
| `[data-align]` | `"start" \| "end" \| "center"`                 |

| CSS Variable                               | Description                                      |
| ------------------------------------------ | ------------------------------------------------ |
| `--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` 内部渲染。

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | `false` |
| `width`   | `number`  | `10`    |
| `height`  | `number`  | `5`     |

## [示例](#示例)

### [全局配置](#全局配置)

使用 `Provider` 来全局控制 `delayDuration` 和 `skipDelayDuration`。

```jsx
import { Tooltip } from "radix-ui";

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` 属性控制工具提示打开所需的时间。

```jsx
import { Tooltip } from "radix-ui";

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` 以支持此功能。使用它们来限制内容的尺寸。

```jsx
// index.jsx

import { Tooltip } from "radix-ui";

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>
);
```

```css
/* 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` 和任何碰撞从其计算的原点动画内容。

```jsx
// index.jsx

import { Tooltip } from "radix-ui";

import "./styles.css";

export default () => (
  <Tooltip.Root>
    <Tooltip.Trigger>…</Tooltip.Trigger>

    <Tooltip.Content className="TooltipContent">…</Tooltip.Content>
  </Tooltip.Root>
);
```

```css
/* 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` 属性。它们的值将在运行时根据碰撞情况进行更改。使用它们来创建碰撞和方向感知的动画。

```jsx
// index.jsx

import { Tooltip } from "radix-ui";

import "./styles.css";

export default () => (
  <Tooltip.Root>
    <Tooltip.Trigger>…</Tooltip.Trigger>

    <Tooltip.Content className="TooltipContent">…</Tooltip.Content>
  </Tooltip.Root>
);
```

```css
/* 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);
  }
}
```

## [可访问性](#可访问性)

### [键盘交互](#键盘交互)

| Key      | Description                    |
| -------- | ------------------------------ |
| `Tab`    | 打开/关闭工具提示，不延迟。    |
| `Space`  | 如果打开，则立即关闭工具提示。 |
| `Enter`  | 如果打开，则立即关闭工具提示。 |
| `Escape` | 如果打开，则立即关闭工具提示。 |

## [自定义 API](#自定义-api)

通过将原始部件抽象到您自己的组件中创建自己的 API。

### [抽象部件并引入内容属性](#抽象部件并引入内容属性)

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

#### 用法

```jsx
import { Tooltip } from "./your-tooltip";

export default () => (
  <Tooltip content="工具提示内容">
    <button>工具提示触发器</button>
  </Tooltip>
);
```

#### 实现

使用 [`asChild` 属性](/primitives/docs/guides/composition) 将触发器部分转换为可插入的区域。它将用传递给它的子元素替换触发器。

```jsx
// your-tooltip.jsx

import * as React from "react";

import { Tooltip as TooltipPrimitive } from "radix-ui";

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>
  );
}
```

<!--$-->

<!--/$-->