工具提示

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

import * as React from "react";
import { Tooltip } from "radix-ui";
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;

Features

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

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

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

支持自定义时间设置。

安装

从命令行安装组件。

npm install @radix-ui/react-tooltip

结构

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

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 参考

Provider

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

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

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

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

Prop	Type	Default
`asChild`	`boolean`	`false`

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

Portal

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

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

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。

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

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

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

/* 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 { Tooltip } from "radix-ui";
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 { Tooltip } from "radix-ui";
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);
	}
}

可访问性

键盘交互

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

自定义 API

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

抽象部件并引入内容属性

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

用法

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

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

实现

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

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

上一篇工具条 Toolbar

下一篇无障碍图标 Accessible Icon

在 GitHub 上编辑此页面

概览 Overview

指南 Guides

组件 Components

通用工具 Utilities

工具提示

Features

用法

实现