Skip to Content
文档

工具提示

用于在用户鼠标悬停在元素上时显示附加信息。

SourceStorybookRecipeArk

设置

¥Setup

为了方便使用,请为 Tooltip 组件创建一个封闭的组件组合。

¥For ease of use, create a closed component composition for the Tooltip component.

import { Tooltip as ChakraTooltip, Portal } from "@chakra-ui/react"
import * as React from "react"

export interface TooltipProps extends ChakraTooltip.RootProps {
  showArrow?: boolean
  portalled?: boolean
  portalRef?: React.RefObject<HTMLElement>
  content: React.ReactNode
  contentProps?: ChakraTooltip.ContentProps
  disabled?: boolean
}

export const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
  function Tooltip(props, ref) {
    const {
      showArrow,
      children,
      disabled,
      portalled = true,
      content,
      contentProps,
      portalRef,
      ...rest
    } = props

    if (disabled) return children

    return (
      <ChakraTooltip.Root {...rest}>
        <ChakraTooltip.Trigger asChild>{children}</ChakraTooltip.Trigger>
        <Portal disabled={!portalled} container={portalRef}>
          <ChakraTooltip.Positioner>
            <ChakraTooltip.Content ref={ref} {...contentProps}>
              {showArrow && (
                <ChakraTooltip.Arrow>
                  <ChakraTooltip.ArrowTip />
                </ChakraTooltip.Arrow>
              )}
              {content}
            </ChakraTooltip.Content>
          </ChakraTooltip.Positioner>
        </Portal>
      </ChakraTooltip.Root>
    )
  },
)

或者,你可以使用以下命令将其添加到你的项目中。

¥Alternatively, you can add it to your project using the following command.

npx @chakra-ui/cli snippet add tooltip

用法

¥Usage

import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="...">
  <button />
</Tooltip>

示例

¥Examples

箭头

¥Arrow

使用 showArrow 属性在工具提示上显示箭头。

¥Use the showArrow prop to show an arrow on the tooltip.

放置位置

¥Placement

使用 positioning.placement 属性更改工具提示的位置。

¥Use the positioning.placement prop to change the position of the tooltip.

偏移

¥Offset

使用 positioning.offset 属性更改工具提示的偏移量。

¥Use the positioning.offset prop to change the offset of the tooltip.

延迟

¥Delay

使用 openDelaycloseDelay 属性更改工具提示的延迟时间。

¥Use the openDelay and closeDelay prop to change the delay of the tooltip.

自定义背景

¥Custom Background

使用 --tooltip-bg CSS 变量更改工具提示的背景颜色。

¥Use the --tooltip-bg CSS variable to change the background color of the tooltip.

受控

¥Controlled

使用 openonOpenChange 属性控制工具提示的可见性。

¥Use the open and onOpenChange prop to control the visibility of the tooltip.

商店

¥Store

控制工具提示的另一种方法是使用 RootProvider 组件和 useTooltip 存储钩子。

¥An alternative way to control the tooltip is to use the RootProvider component and the useTooltip store hook.

这样,你就可以从工具提示外部访问工具提示的状态和方法。

¥This way you can access the tooltip state and methods from outside the tooltip.

交互性

¥Interactive

使用 interactive 属性在与内容交互时保持工具提示打开。

¥Use the interactive prop to keep the tooltip open when interacting with its content.

已禁用

¥Disabled

使用 disabled 属性禁用工具提示。禁用后,将不会显示工具提示。

¥Use the disabled prop to disable the tooltip. When disabled, the tooltip will not be shown.

包含头像

¥With Avatar

以下是如何将 Tooltip 组件与 Avatar 组件结合使用的示例。

¥Here's an example of how to use the Tooltip component with an Avatar component.

SA

包含复选框

¥With Checkbox

以下是如何将 Tooltip 组件与 Checkbox 组件结合使用的示例。

¥Here's an example of how to use the Tooltip component with a Checkbox component.

包含菜单项

¥With MenuItem

以下是如何将 TooltipMenuItem 组件一起使用的示例。

¥Here's an example of how to use the Tooltip with a MenuItem component.

包含菜单触发器

¥With MenuTrigger

以下是如何将 TooltipMenuTrigger 组件一起使用的示例。

¥Here's an example of how to use the Tooltip with a MenuTrigger component.

包含开关

¥With Switch

以下是如何将 Tooltip 封装在 Switch 组件中的示例。

¥Here's an example of how to wrap Tooltip around a Switch component.

包含标签

¥With Tabs

以下是如何将 Tooltip 封装在 Tabs 组件中的示例。

¥Here's an example of how to wrap Tooltip around a Tabs component.

Manage your team members

属性

¥Props

根元素

¥Root

PropDefaultType
closeDelay '500'
number

The close delay of the tooltip.

closeOnClick true
boolean

Whether the tooltip should close on click

closeOnEscape true
boolean

Whether to close the tooltip when the Escape key is pressed.

closeOnPointerDown true
boolean

Whether to close the tooltip on pointerdown.

closeOnScroll true
boolean

Whether the tooltip should close on scroll

interactive false
boolean

Whether the tooltip's content is interactive. In this mode, the tooltip will remain open when user hovers over the content.

lazyMount false
boolean

Whether to enable lazy mounting

openDelay '1000'
number

The open delay of the tooltip.

skipAnimationOnMount false
boolean

Whether to allow the initial presence animation.

unmountOnExit false
boolean

Whether to unmount on exit.

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

aria-label
string

Custom label for the tooltip.

defaultOpen
boolean

The initial open state of the tooltip when rendered. Use when you don't need to control the open state of the tooltip.

disabled
boolean

Whether the tooltip is disabled

id
string

The unique identifier of the machine.

ids
Partial<{ trigger: string; content: string; arrow: string; positioner: string }>

The ids of the elements in the tooltip. Useful for composition.

immediate
boolean

Whether to synchronize the present change immediately or defer it to the next frame

onExitComplete
VoidFunction

Function called when the animation ends in the closed state

onOpenChange
(details: OpenChangeDetails) => void

Function called when the tooltip is opened.

open
boolean

The controlled open state of the tooltip

positioning
PositioningOptions

The user provided options used to position the popover content

present
boolean

Whether the node is present (controlled by the user)

Previous

切换提示

Next

警报