مكوّن تلميح نصي، يُستخدم لإظهار معلومات إضافية عند مرور مؤشر الفأرة.

الاستخدام الأساسي

vue

<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- الاستخدام الأساسي -->
  <LhTooltip content="هذه رسالة تلميح">
    <LhButton>مرِّر لإظهار التلميح</LhButton>
  </LhTooltip>
</template>

vue

<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- الاستخدام الأساسي -->
  <LhTooltip content="هذه رسالة تلميح">
    <LhButton>مرِّر لإظهار التلميح</LhButton>
  </LhTooltip>
</template>

مواضع مختلفة

vue

<script setup lang="ts">
</script>

<template>
  <!-- أعلى -->
  <LhTooltip content="تلميح علوي" placement="top">
    <LhButton>أعلى</LhButton>
  </LhTooltip>
  <!-- أسفل -->
  <LhTooltip content="تلميح سفلي" placement="bottom">
    <LhButton>أسفل</LhButton>
  </LhTooltip>
  <!-- يسار -->
  <LhTooltip content="تلميح يساري" placement="left">
    <LhButton>يسار</LhButton>
  </LhTooltip>
  <!-- يمين -->
  <LhTooltip content="تلميح يميني" placement="right">
    <LhButton>يمين</LhButton>
  </LhTooltip>
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- أعلى -->
  <LhTooltip content="تلميح علوي" placement="top">
    <LhButton>أعلى</LhButton>
  </LhTooltip>
  <!-- أسفل -->
  <LhTooltip content="تلميح سفلي" placement="bottom">
    <LhButton>أسفل</LhButton>
  </LhTooltip>
  <!-- يسار -->
  <LhTooltip content="تلميح يساري" placement="left">
    <LhButton>يسار</LhButton>
  </LhTooltip>
  <!-- يمين -->
  <LhTooltip content="تلميح يميني" placement="right">
    <LhButton>يمين</LhButton>
  </LhTooltip>
</template>

تأخير مخصص

vue

<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- يظهر بعد تأخير ثانية -->
  <LhTooltip content="يظهر بعد تأخير قدره ثانية" :show-after="1000">
    <LhButton>تلميح مؤجَّل</LhButton>
  </LhTooltip>
  <!-- open-delay / close-delay -->
  <LhTooltip content="يظهر بعد 300 مللي ثانية من الدخول، ويختفي بعد 500 مللي ثانية من الخروج" :open-delay="300" :close-delay="500">
    <LhButton>open-delay / close-delay</LhButton>
  </LhTooltip>
</template>

vue

<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- يظهر بعد تأخير ثانية -->
  <LhTooltip content="يظهر بعد تأخير قدره ثانية" :show-after="1000">
    <LhButton>تلميح مؤجَّل</LhButton>
  </LhTooltip>
  <!-- open-delay / close-delay -->
  <LhTooltip content="يظهر بعد 300 مللي ثانية من الدخول، ويختفي بعد 500 مللي ثانية من الخروج" :open-delay="300" :close-delay="500">
    <LhButton>open-delay / close-delay</LhButton>
  </LhTooltip>
</template>

التدويل

يمكن تدويل نص التلميح عبر LhConfigProvider مع حزم اللغات.

vue

<script setup lang="ts">
import { ref } from 'vue'
import { LhConfigProvider, LhTooltip, LhButton } from '@lh-ui/vue3'
import { zhCN } from '@lh-ui/vue3'
import { enUS } from '@lh-ui/vue3'

const locale = ref('zh-CN')
</script>

<template>
  <!-- تبديل حزمة اللغة عبر ConfigProvider -->
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhTooltip :content="locale === 'zh-CN' ? '中文提示' : 'English Tooltip'">
      <LhButton>Tooltip</LhButton>
    </LhTooltip>
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      {{ locale === 'zh-CN' ? '切换英文' : 'Switch to Chinese' }}
    </LhButton>
  </LhConfigProvider>
</template>

vue

<script>
import { LhConfigProvider, LhTooltip, LhButton } from '@lh-ui/vue3'
import { zhCN } from '@lh-ui/vue3'
import { enUS } from '@lh-ui/vue3'

export default {
  components: { LhConfigProvider, LhTooltip, LhButton },
  data() {
    return {
      locale: 'zh-CN',
      zhCN: zhCN,
      enUS: enUS,
    }
  },
}
</script>

<template>
  <!-- تبديل حزمة اللغة عبر ConfigProvider -->
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhTooltip :content="locale === 'zh-CN' ? '中文提示' : 'English Tooltip'">
      <LhButton>Tooltip</LhButton>
    </LhTooltip>
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      {{ locale === 'zh-CN' ? '切换英文' : 'Switch to Chinese' }}
    </LhButton>
  </LhConfigProvider>
</template>

التخطيط السريع عبر sx

ضبط مسافات وأحجام العنصر الجذري للمُشغِّل بسرعة عبر خاصية sx، دون كتابة CSS إضافي.

vue

<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- تخطيط مسافات sx -->
  <LhTooltip content="يعمل sx على العنصر الجذري للمُشغِّل" :sx="{ mt: 2, ml: 2 }">
    <LhButton type="primary">مسافة علوية 2، ومسافة يمينية 2</LhButton>
  </LhTooltip>
</template>

vue

<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- تخطيط مسافات sx -->
  <LhTooltip content="يعمل sx على العنصر الجذري للمُشغِّل" :sx="{ mt: 2, ml: 2 }">
    <LhButton type="primary">مسافة علوية 2، ومسافة يمينية 2</LhButton>
  </LhTooltip>
</template>

يعتمد sx شبكة أساسها 8px: mt: 2 → marginTop: 16px، وml: 2 → marginLeft: 16px. وللاطلاع على الخصائص الكاملة راجع التخطيط السريع عبر sx.

طريقة التشغيل والحالة

تُحدَّد طريقة التشغيل عبر trigger؛ ويعطّل disabled التلميح؛ ويتحكم manual مع visible يدويًا في الإظهار؛ بينما يتحكم hideAfter في التأخير قبل الإخفاء.

vue

<script setup lang="ts">
import { ref } from 'vue'
import { LhTooltip, LhButton } from '@lh-ui/vue3'

const manualVisible = ref(false)
</script>

<template>
  <!-- تشغيل بالنقر -->
  <LhTooltip content="يُطلَق بالنقر" trigger="click">
    <LhButton>تشغيل بالنقر</LhButton>
  </LhTooltip>
  <!-- تشغيل بالتركيز -->
  <LhTooltip content="يُطلَق بالتركيز" trigger="focus">
    <LhButton>تشغيل بالتركيز</LhButton>
  </LhTooltip>
  <!-- تلميح معطَّل -->
  <LhTooltip content="تلميح معطَّل" disabled>
    <LhButton type="info" disabled>تلميح معطَّل</LhButton>
  </LhTooltip>
  <!-- تحكّم يدوي -->
  <LhTooltip content="تحكّم يدوي" manual :visible="manualVisible">
    <LhButton @click="manualVisible = !manualVisible">تبديل يدوي</LhButton>
  </LhTooltip>
  <!-- إخفاء مؤجَّل -->
  <LhTooltip content="يختفي بعد ثانية" :hide-after="1000">
    <LhButton>إخفاء مؤجَّل</LhButton>
  </LhTooltip>
</template>

vue

<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
  data() {
    return {
      manualVisible: false,
    }
  },
}
</script>

<template>
  <!-- تشغيل بالنقر -->
  <LhTooltip content="يُطلَق بالنقر" trigger="click">
    <LhButton>تشغيل بالنقر</LhButton>
  </LhTooltip>
  <!-- تشغيل بالتركيز -->
  <LhTooltip content="يُطلَق بالتركيز" trigger="focus">
    <LhButton>تشغيل بالتركيز</LhButton>
  </LhTooltip>
  <!-- تلميح معطَّل -->
  <LhTooltip content="تلميح معطَّل" disabled>
    <LhButton type="info" disabled>تلميح معطَّل</LhButton>
  </LhTooltip>
  <!-- تحكّم يدوي -->
  <LhTooltip content="تحكّم يدوي" manual :visible="manualVisible">
    <LhButton @click="manualVisible = !manualVisible">تبديل يدوي</LhButton>
  </LhTooltip>
  <!-- إخفاء مؤجَّل -->
  <LhTooltip content="يختفي بعد ثانية" :hide-after="1000">
    <LhButton>إخفاء مؤجَّل</LhButton>
  </LhTooltip>
</template>

كلٌّ من openDelay وcloseDelay اسم بديل لـ showAfter وhideAfter على الترتيب، فاختر ما تفضّل.

السمة والمظهر

بدّل السمة الفاتحة والداكنة عبر effect، وخصِّص لون الخلفية عبر bgColor، وقَيِّد العرض الأقصى عبر maxWidth، وحدِّد وجهة تركيب الطبقة المنبثقة عبر teleportTarget.

vue

<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- السمة الداكنة -->
  <LhTooltip content="السمة الداكنة" effect="dark">
    <LhButton>السمة الداكنة</LhButton>
  </LhTooltip>
  <!-- السمة الفاتحة -->
  <LhTooltip content="السمة الفاتحة" effect="light">
    <LhButton>السمة الفاتحة</LhButton>
  </LhTooltip>
  <!-- لون خلفية مخصص -->
  <LhTooltip content="لون خلفية مخصص" bg-color="#5a3fa8">
    <LhButton>لون خلفية مخصص</LhButton>
  </LhTooltip>
  <!-- العرض الأقصى -->
  <LhTooltip content="هذا النص طويل نسبيًا، وسيُقيَّده maxWidth ليُلتف ضمن 160px تلقائيًا" :max-width="160">
    <LhButton>العرض الأقصى 160px</LhButton>
  </LhTooltip>
  <!-- نقطة تركيب مخصصة -->
  <LhTooltip content="طبقة منبثقة مركَّبة على #app" teleport-target="#app">
    <LhButton>نقطة تركيب مخصصة</LhButton>
  </LhTooltip>
</template>

vue

<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- السمة الداكنة -->
  <LhTooltip content="السمة الداكنة" effect="dark">
    <LhButton>السمة الداكنة</LhButton>
  </LhTooltip>
  <!-- السمة الفاتحة -->
  <LhTooltip content="السمة الفاتحة" effect="light">
    <LhButton>السمة الفاتحة</LhButton>
  </LhTooltip>
  <!-- لون خلفية مخصص -->
  <LhTooltip content="لون خلفية مخصص" bg-color="#5a3fa8">
    <LhButton>لون خلفية مخصص</LhButton>
  </LhTooltip>
  <!-- العرض الأقصى -->
  <LhTooltip content="هذا النص طويل نسبيًا، وسيُقيَّده maxWidth ليُلتف ضمن 160px تلقائيًا" :max-width="160">
    <LhButton>العرض الأقصى 160px</LhButton>
  </LhTooltip>
  <!-- نقطة تركيب مخصصة -->
  <LhTooltip content="طبقة منبثقة مركَّبة على #app" teleport-target="#app">
    <LhButton>نقطة تركيب مخصصة</LhButton>
  </LhTooltip>
</template>

Props

اسم الخاصية	الوصف	النوع	القيمة الافتراضية
content	محتوى التلميح	`string`	`''`
placement	موضع التلميح	`"top" \| "top-start" \| "top-end" \| "bottom" \| "bottom-start" \| "bottom-end" \| "left" \| "left-start" \| "left-end" \| "right" \| "right-start" \| "right-end"`	`'top'`
trigger	طريقة التشغيل	`"hover" \| "click" \| "focus"`	`'hover'`
disabled	التعطيل	`boolean`	`false`
manual	التحكم اليدوي في الإظهار	`boolean`	`false`
visible	حالة الإظهار في التحكم اليدوي	`boolean`	—
showAfter	زمن التأخير قبل الإظهار (ms)	`number`	`0`
hideAfter	زمن التأخير قبل الإخفاء (ms)	`number`	`0`
openDelay	زمن التأخير قبل الإظهار (ms)، اسم بديل لـ showAfter	`number`	—
closeDelay	زمن تأخير الإغلاق	`number`	—
effect	السمة	`"dark" \| "light"`	`'dark'`
type	نوع لون السمة المدمج (يتجاوز لون خلفية effect)	`"primary" \| "success" \| "warning" \| "danger" \| "info"`	—
bgColor	لون خلفية مخصص (يتجاوز لون خلفية effect وtype)	`string`	—
maxWidth	العرض الأقصى	`string \| number`	`'200px'`
teleportTarget	وجهة Teleport (محدِّد أو عنصر، الافتراضي body)	`string \| HTMLElement`	`'body'`
themeVars	متغيرات السمة على مستوى المكوّن، تتجاوز إعداد ConfigProvider	`{ [x: string]: string; }`	—
bgPattern	نمط الخلفية على مستوى المكوّن، يتجاوز إعداد ConfigProvider	`string`	—
sx	خصائص التخطيط السريع sx (تُطبَّق على العنصر الجذري للمُشغِّل)	`LhSxProps`	—

ملاحظة: قيمة 'click' لـ trigger ليست مُنفَّذة بعد (سلوكها يماثل 'hover')، وسيُقدَّم التبديل بالنقر في إصدار لاحق.

Slots

اسم الفتحة	الوصف
default	العنصر الذي يشغّل التلميح (يُمرَّر متن التلميح عبر خاصية `content`)

Methods

يمكن استدعاء الدوال التي يكشفها المكوّن عبر ref:

اسم الدالة	الوصف
show	إظهار التلميح فورًا
hide	إخفاء التلميح فورًا
toggle	تبديل حالة إظهار التلميح

إتاحة الوصول

تحمل الطبقة المنبثقة role="tooltip"؛ وعند الإظهار يُضبط aria-describedby على العنصر الجذري للمُشغِّل تلقائيًا ليشير إلى الطبقة المنبثقة، ويُزال عند الإخفاء فورًا دون ترك إشارة معلَّقة
قابلية الوصول بلوحة المفاتيح: مع طريقتي التشغيل hover / focus يظهر التلميح أيضًا عند دخول تركيز لوحة المفاتيح إلى المُشغِّل (focusin)، ويُخفى تلقائيًا عند مغادرة التركيز، وذلك محاذٍ لنمط tooltip في WAI-ARIA APG؛ أما التشغيل بـ click فلا يستجيب للتركيز
يجب وضع عنصر قابل للتركيز داخل المُشغِّل (مثل زر أو رابط)، فالنص الخالص لا يمكن تركيزه بلوحة المفاتيح ولن يكون التلميح في متناول مستخدميها

تعريفات الأنواع

بنية الأنواع التي يُصدِّرها هذا المكوّن بلغة TypeScript كالتالي (مستخرجة آليًا من packages/components/tooltip/src/types.ts و@lh-ui/share/core/*؛ انقر كل عنصر لعرض التعريف الكامل؛ لأوصاف الخصائص انظر جدول Props أعلاه):

LhTooltipPlacement

/**
 * نوع Tooltip
 */
export type LhTooltipPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'

LhTooltipTrigger

export type LhTooltipTrigger = 'hover' | 'click' | 'focus'

LhTooltipEffect

export type LhTooltipEffect = 'dark' | 'light'

LhTooltipType

export type LhTooltipType = 'primary' | 'success' | 'warning' | 'danger' | 'info'

LhTooltipProps

/**
 * Props مكوّن Tooltip
 */
export interface LhTooltipProps {
  /** محتوى نص التلميح */
  content?: string
  /** موضع الإظهار */
  placement?: LhTooltipPlacement
  /** طريقة التشغيل */
  trigger?: LhTooltipTrigger
  /** تعطيل */
  disabled?: boolean
  /** تحكّم يدوي في الإظهار */
  manual?: boolean
  /** حالة الإظهار في التحكم اليدوي */
  visible?: boolean
  /** زمن التأخير قبل الإظهار (ms) */
  showAfter?: number
  /** زمن التأخير قبل الإخفاء (ms) */
  hideAfter?: number
  /** زمن التأخير قبل الإظهار (ms)، اسم بديل لـ showAfter */
  openDelay?: number
  /** زمن تأخير الإغلاق */
  closeDelay?: number
  /** السمة */
  effect?: LhTooltipEffect
  /** نوع لون السمة المدمج (يتجاوز لون خلفية effect) */
  type?: LhTooltipType
  /** لون خلفية مخصص (يتجاوز لون خلفية effect وtype) */
  bgColor?: string
  /** العرض الأقصى */
  maxWidth?: string | number
  /** وجهة Teleport (محدِّد أو عنصر، الافتراضي body) */
  teleportTarget?: string | HTMLElement
  /** متغيرات السمة على مستوى المكوّن، تتجاوز إعداد ConfigProvider */
  themeVars?: Record<string, string>
  /** نمط الخلفية على مستوى المكوّن، يتجاوز إعداد ConfigProvider */
  bgPattern?: string
  /** خصائص التخطيط السريع sx (تُطبَّق على العنصر الجذري للمُشغِّل) */
  sx?: LhSxProps
}

Tooltip (تلميح)

الاستخدام الأساسي

مواضع مختلفة

تأخير مخصص

التدويل

التخطيط السريع عبر sx

طريقة التشغيل والحالة

السمة والمظهر

Tooltip API

Props

Slots

Methods

إتاحة الوصول

تعريفات الأنواع

Tooltip (تلميح) ​

الاستخدام الأساسي ​

مواضع مختلفة ​

تأخير مخصص ​

التدويل ​

التخطيط السريع عبر sx ​

طريقة التشغيل والحالة ​

السمة والمظهر ​

Tooltip API ​

Props ​

Slots ​

Methods ​

إتاحة الوصول ​

تعريفات الأنواع ​

Tooltip (تلميح)

الاستخدام الأساسي

مواضع مختلفة

تأخير مخصص

التدويل

التخطيط السريع عبر sx

طريقة التشغيل والحالة

السمة والمظهر

Tooltip API

Props

Slots

Methods

إتاحة الوصول

تعريفات الأنواع