跳到内容
1.6k

工具提示

图标按钮、键盘快捷键和截断标签的悬停和焦点提示——采用新粗野主义风格的边框和阴影处理。

import { Button } from "@/components/ui/button"
import {
  Tooltip,

工具提示是一段简短的说明，在悬停或键盘聚焦时出现，用来描述它所包裹的那个控件——它是补充文字，绝不该用来放交互内容。它基于 Base UI Tooltip 基元构建，通过 portal 渲染并会自动避让边界，同时按新粗野主义的配方设计：粗边框、硬阴影，以及反色填充，因此在任何背景上都清晰可读。

适合以下场景：

  • 纯图标按钮——为一个孤零零的图标说清它的操作：工具栏、表格行操作、编辑器控件。
  • 键盘快捷键——用 Kbd 把按键组合写在标签旁边，就像下面的示例那样。
  • 被截断或过于简略的文字——完整文件名、被裁掉的表格单元格、缩写的状态码。

安装

运行以下命令：

pnpm dlx shadcn@latest add https://neobrutalism.com/r/base/tooltip.json
npx shadcn@latest add https://neobrutalism.com/r/base/tooltip.json
yarn dlx shadcn@latest add https://neobrutalism.com/r/base/tooltip.json
bunx --bun shadcn@latest add https://neobrutalism.com/r/base/tooltip.json

将 TooltipProvider 添加到应用的根部。

app/layout.tsx
import { TooltipProvider } from "@/components/ui/tooltip"
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <TooltipProvider>{children}</TooltipProvider>
      </body>
    </html>
  )
}

安装以下依赖：

pnpm add @base-ui/react
npm install @base-ui/react
yarn add @base-ui/react
bun add @base-ui/react

将以下代码复制并粘贴到您的项目中。

components/ui/tooltip.tsx
"use client"

import * as React from "react"
import { Tooltip as TooltipPrimitive } from "radix-ui"

import { cn } from "@/lib/utils"

function TooltipProvider({
  delayDuration = 0,
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
  return (
    <TooltipPrimitive.Provider
      data-slot="tooltip-provider"
      delayDuration={delayDuration}
      {...props}
    />
  )
}

function Tooltip({
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
}

function TooltipTrigger({
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
}

function TooltipContent({
  className,
  sideOffset = 0,
  children,
  ...props
}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
  return (
    <TooltipPrimitive.Portal>
      <TooltipPrimitive.Content
        data-slot="tooltip-content"
        sideOffset={sideOffset}
        className={cn(
          "z-50 inline-flex w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) items-center gap-1.5 rounded border-2 bg-foreground px-2 py-1 text-xs text-background shadow-md has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
          className
        )}
        {...props}
      >
        {children}
        <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
      </TooltipPrimitive.Content>
    </TooltipPrimitive.Portal>
  )
}

export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }

更新导入路径以匹配您的项目设置。

将 TooltipProvider 添加到应用的根部。

app/layout.tsx
import { TooltipProvider } from "@/components/ui/tooltip"
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <TooltipProvider>{children}</TooltipProvider>
      </body>
    </html>
  )
}

用法

import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"
<Tooltip>
  <TooltipTrigger>Hover</TooltipTrigger>
  <TooltipContent>
    <p>Add to library</p>
  </TooltipContent>
</Tooltip>

组合

使用以下组合来构建 Tooltip：

Tooltip
├── TooltipTrigger
└── TooltipContent

示例

方位

使用 side 属性来更改工具提示的位置。

import { Button } from "@/components/ui/button"
import {
  Tooltip,

带键盘快捷键

import { SaveIcon } from "lucide-react"

import { Button } from "@/components/ui/button"

禁用的按钮

用一个 span 包裹禁用的按钮，即可在该按钮上显示工具提示。

import { Button } from "@/components/ui/button"
import {
  Tooltip,

RTL

要在 Neobrutalism 中启用 RTL 支持，请参阅 RTL 配置指南。

"use client"

import {

无障碍

工具提示遵循 WAI-ARIA Tooltip 模式：弹出层以 role="tooltip" 渲染，基元则把触发器的 aria-describedby 指向它，于是屏幕阅读器会把这段提示当作控件的描述来播报。工具提示本身永远不会获得焦点——要放链接或按钮，请改用 Popover，并保证触发器在没有提示的情况下也能被理解。

键盘交互：

按键操作
Tab / Shift + Tab把焦点移到触发器上——聚焦即打开提示，离开即关闭
Escape关闭工具提示，焦点仍留在触发器上
Enter / Space执行触发器自身的操作——工具提示只是描述，不是控件

API 参考

请参阅 Base UI Tooltip 文档。