文字提示元件，用於滑鼠懸停時顯示額外資訊。

基礎用法

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>
  <!-- 延遲 1s 顯示 -->
  <LhTooltip content="延迟1秒显示" :show-after="1000">
    <LhButton>延迟提示</LhButton>
  </LhTooltip>
  <!-- open-delay / close-delay -->
  <LhTooltip content="进入 300ms 后显示，移出 500ms 后隐藏" :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>
  <!-- 延遲 1s 顯示 -->
  <LhTooltip content="延迟1秒显示" :show-after="1000">
    <LhButton>延迟提示</LhButton>
  </LhTooltip>
  <!-- open-delay / close-delay -->
  <LhTooltip content="进入 300ms 后显示，移出 500ms 后隐藏" :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="延迟 1 秒隐藏" :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="延迟 1 秒隐藏" :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`	—

注：trigger 的 'click' 取值當前尚未實現（行為等同 'hover'），點選切換將在後續版本提供。

Slots

插槽名	說明
default	觸發提示的元素（提示正文透過 `content` 屬性設定）

Methods

透過 ref 可以呼叫元件暴露的方法：

方法名	說明
show	立即顯示提示
hide	立即隱藏提示
toggle	切換提示顯示狀態

無障礙

彈出層自帶 role="tooltip"；顯示時觸發器根元素自動設定 aria-describedby 指向彈出層，隱藏時自動移除，不留懸空引用
鍵盤可達：hover / focus 觸發方式下，鍵盤焦點進入觸發器（focusin）同樣會顯示提示，焦點離開自動隱藏，對齊 WAI-ARIA APG 的 tooltip 模式；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

/**
 * Tooltip 元件 Props
 */
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

無障礙

類型定義