الانتقال إلى المحتوى

تلميح

تلميحات عند تمرير المؤشر والتركيز على أزرار الرموز، واختصارات لوحة المفاتيح، والتسميات المختصرة — مع تطبيق أسلوب «النيوبروتاليست» في الحدود والظلال.

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

تلميح الأداة هو تسمية قصيرة تظهر عند تمرير المؤشر فوق العنصر أو عند تركيز لوحة المفاتيح عليه، وتصف العنصر الذي تحيط به — وهو نص تكميلي، ولا يُعد أبدًا مكانًا للمحتوى التفاعلي. مبنية على عنصر Base UI Tooltip الأساسي، ومزودة بواجهة بوابة ومراعية للتصادم، ومصممة وفقًا لأسلوب «النيوبروتالية»: حدود سميكة، وظل قوي، وتعبئة معكوسة حتى تظهر بوضوح على أي خلفية.

استخدمه عندما:

  • الأزرار التي تحتوي على أيقونة فقط — قم بتسمية الإجراء الذي لا تستطيع الأيقونة وحدها توضيحه: أشرطة الأدوات، وإجراءات صفوف الجداول، وعناصر التحكم في المحرر.
  • اختصارات لوحة المفاتيح — اكتب الاختصار بجانب التسمية باستخدام 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

لتفعيل RTL في Neobrutalism، راجع دليل إعداد RTL.

"use client"

import {

إمكانية الوصول

تتبع تلميحة الأداة معيار WAI-ARIA Tooltip pattern: حيث يتم عرض النافذة المنبثقة وفقًا لمعيار role="tooltip"، وتشير العنصر الأساسي إلى aria-describedby الخاص بالمشغل، وبالتالي تقوم برامج قراءة الشاشة بإعلان التلميحة كوصف لعنصر التحكم. لا تحظى تلميحة الأداة نفسها بالتركيز أبدًا — ضع الروابط أو الأزرار في Popover بدلاً من ذلك، وحافظ على وضوح المشغل بدونها.

تفاعلات لوحة المفاتيح:

مفتاحالإجراء
Tab / Shift + Tabنقل التركيز إلى المشغل — يؤدي التركيز إلى فتح تلميح الأداة، بينما يؤدي تركه إلى إغلاقه
Escapeإغلاق تلميح الأداة مع بقاء التركيز على المشغل
Enter / Spaceتنشيط الإجراء الخاص بالمشغل — تلميح الأداة هو وصف، وليس عنصر تحكم

مرجع API

لمزيد من المعلومات، راجع وثائق Base UI.