工具提示

¥Tooltip

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

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

Provider to control display delay globally.

Opens when the trigger is focused or hovered.

Closes when the trigger is activated or when pressing escape.

Supports custom timings.

安装

¥Installation

从命令行安装组件。

¥Install the component from your command line.

npm install @radix-ui/react-tooltip

结构

¥Anatomy

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

¥Import all parts and piece them together.

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 Reference

提供者

¥Provider

封装你的应用，为你的工具提示提供全局功能。

¥Wraps your app to provide global functionality to your tooltips.

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

根

¥Root

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

¥Contains all the parts of a tooltip.

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 将根据触发器进行定位。

¥The button that toggles the tooltip. By default, the Tooltip.Content will position itself against the trigger.

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

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

门户

¥Portal

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

¥When used, portals the content part into the body.

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

内容

¥Content

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

¥The component that pops out when the tooltip is open.

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`	The `transform-origin` computed from the content and arrow positions/offsets
`--radix-tooltip-content-available-width`	The remaining width between the trigger and the boundary edge
`--radix-tooltip-content-available-height`	The remaining height between the trigger and the boundary edge
`--radix-tooltip-trigger-width`	The width of the trigger
`--radix-tooltip-trigger-height`	The height of the trigger

箭头

¥Arrow

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

¥An optional arrow element to render alongside the tooltip. This can be used to help visually link the trigger with the Tooltip.Content. Must be rendered inside Tooltip.Content.

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

示例

¥Examples

全局配置

¥Configure globally

使用 Provider 全局控制 delayDuration 和 skipDelayDuration。

¥Use the Provider to control delayDuration and skipDelayDuration globally.

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

立即显示

¥Show instantly

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

¥Use the delayDuration prop to control the time it takes for the tooltip to open.

import { Tooltip } from "radix-ui";

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

限制内容大小

¥Constrain the content size

你可能需要限制内容的宽度，使其与触发器的宽度匹配。你可能还需要限制其高度，使其不超过视口。

¥You may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport.

为了支持此功能，我们公开了几个 CSS 自定义属性，例如 --radix-tooltip-trigger-width 和 --radix-tooltip-content-available-height。使用它们来限制内容尺寸。

¥We expose several CSS custom properties such as --radix-tooltip-trigger-width and --radix-tooltip-content-available-height to support this. Use them to constrain the content dimensions.

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

原点感知动画

¥Origin-aware animations

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

¥We expose a CSS custom property --radix-tooltip-content-transform-origin. Use it to animate the content from its computed origin based on side, sideOffset, align, alignOffset and any collisions.

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

碰撞感知动画

¥Collision-aware animations

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

¥We expose data-side and data-align attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations.

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

可访问性

¥Accessibility

键盘交互

¥Keyboard Interactions

Key	Description
`Tab`	Opens/closes the tooltip without delay.
`Space`	If open, closes the tooltip without delay.
`Enter`	If open, closes the tooltip without delay.
`Escape`	If open, closes the tooltip without delay.

自定义 API

¥Custom APIs

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

¥Create your own API by abstracting the primitive parts into your own component.

抽象部分并引入内容属性

¥Abstract parts and introduce a content prop

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

¥This example abstracts all of the Tooltip parts and introduces a new content prop.

用法

¥Usage

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

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

实现

¥Implementation

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

¥Use the asChild prop to convert the trigger part into a slottable area. It will replace the trigger with the child that gets passed to it.

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

Previous工具栏

Next可访问图标

概览

指南

组件

实用工具