工具提示

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

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;

功能特性

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

当触发器被聚焦或悬停时打开。

当触发器被激活或按下 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	类型	默认值
`delayDuration`	`number`	`700`
`skipDelayDuration`	`number`	`300`
`disableHoverableContent`	`boolean`	无默认值

Root

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

Prop	类型	默认值
`defaultOpen`	`boolean`	无默认值
`open`	`boolean`	无默认值
`onOpenChange`	`function`	无默认值
`delayDuration`	`number`	`700`
`disableHoverableContent`	`boolean`	无默认值

Trigger

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

Prop	类型	默认值
`asChild`	`boolean`	`false`

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

Portal

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

Prop	类型	默认值
`forceMount`	`boolean`	无默认值
`container`	`HTMLElement`	`document.body`

Content

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

Prop	类型	默认值
`asChild`	`boolean`	`false`
`aria-label`	`string`	无默认值
`onEscapeKeyDown`	`function`	无默认值
`onPointerDownOutside`	`function`	无默认值
`forceMount`	`boolean`	无默认值
`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-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`	触发器的高度

Arrow

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

Prop	类型	默认值
`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);
	}
}

可访问性

键盘交互

按键	描述
`Tab`	立即打开/关闭工具提示。
`Space`	如果打开，立即关闭工具提示。
`Enter`	如果打开，立即关闭工具提示。
`Escape`	如果打开，立即关闭工具提示。

自定义 API

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

抽象部件并引入内容 prop

此示例抽象了所有 Tooltip 部件，并引入了一个新的 content prop。

用法

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

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

实现

使用 asChild prop 将触发器部件转换为可插槽区域。它将用传递给它的子项替换触发器。

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

上一个工具栏

下一个无障碍图标

在 GitHub 上编辑此页。

概述

指南

组件

实用工具

功能特性

用法

实现