Tooltip

TooltipGitHub
一个在悬停在元素上时显示信息的弹出框。

用法

在 Tooltip 的默认插槽中使用 Button 或任何其他组件。

确保使用 App 组件包裹您的应用程序,该组件使用了TooltipProvider组件(来自 Reka UI)。
您可以查看 App 组件的 tooltip 属性,了解如何全局配置 Tooltip。

文本

使用 text 属性设置 Tooltip 的内容。

<template>
  <UTooltip text="Open on GitHub">
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>

键盘按键

使用 kbds 属性在 Tooltip 中渲染 Kbd 组件。

<template>
  <UTooltip text="Open on GitHub" :kbds="['meta', 'G']">
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
您可以使用特殊按键,例如 meta,在 macOS 上显示为 ,在其他平台上显示为 Ctrl

延迟

使用 delay-duration 属性更改 Tooltip 出现前的延迟。例如,您可以将其设置为 0 以使其立即出现。

<template>
  <UTooltip :delay-duration="0" text="Open on GitHub">
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
这可以通过 App 组件中的 tooltip.delayDuration 选项进行全局配置。

内容

使用 content 属性控制 Tooltip 内容的渲染方式,例如其 alignside

<template>
  <UTooltip
    :content="{
      align: 'center',
      side: 'bottom',
      sideOffset: 8
    }"
    text="Open on GitHub"
  >
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>

箭头

使用 arrow 属性在 Tooltip 上显示箭头。

<template>
  <UTooltip arrow text="Open on GitHub">
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>

禁用

使用 disabled 属性禁用 Tooltip。

<template>
  <UTooltip disabled text="Open on GitHub">
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>

示例

控制打开状态

您可以使用 default-open 属性或 v-model:open 指令控制其打开状态。

<script setup lang="ts">
const open = ref(false)

defineShortcuts({
  o: () => open.value = !open.value
})
</script>

<template>
  <UTooltip v-model:open="open" text="Open on GitHub">
    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
在此示例中,利用 defineShortcuts,您可以通过按 O 切换 Tooltip。

随光标移动

您可以使用以下方式使 Tooltip 在鼠标悬停在元素上时跟随光标reference属性

悬停我
<script setup lang="ts">
const open = ref(false)
const anchor = ref({ x: 0, y: 0 })

const reference = computed(() => ({
  getBoundingClientRect: () =>
    ({
      width: 0,
      height: 0,
      left: anchor.value.x,
      right: anchor.value.x,
      top: anchor.value.y,
      bottom: anchor.value.y,
      ...anchor.value
    } as DOMRect)
}))
</script>

<template>
  <UTooltip
    :open="open"
    :reference="reference"
    :content="{ side: 'top', sideOffset: 16, updatePositionStrategy: 'always' }"
  >
    <div
      class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72"
      @pointerenter="open = true"
      @pointerleave="open = false"
      @pointermove="(ev) => {
        anchor.x = ev.clientX
        anchor.y = ev.clientY
      }"
    >
      Hover me
    </div>

    <template #content>
      {{ anchor.x.toFixed(0) }} - {{ anchor.y.toFixed(0) }}
    </template>
  </UTooltip>
</template>

API

属性

属性默认值类型
文本

string

工具提示的文本内容。

键盘按键

(string | undefined)[] | KbdProps[]

在工具提示中显示的键盘按键。

内容

{ side: 'bottom', sideOffset: 8, collisionPadding: 8 }

TooltipContentProps & Partial<EmitsToProps<TooltipContentImplEmits>>

Tooltip 的内容。

arrow

boolean | TooltipArrowProps

在工具提示旁边显示一个箭头。

portal

string | false | true | HTMLElement

在传送门中渲染工具提示。

reference

Element | VirtualElement

用于定位的引用(或锚点)元素。

如果未提供,将使用当前组件作为锚点。

defaultOpen

boolean

工具提示在初始渲染时的打开状态。当您不需要控制其打开状态时使用。

open

boolean

工具提示的受控打开状态。

delayDuration

700

number

覆盖提供给 Provider 的持续时间,以自定义特定工具提示的打开延迟。

disableHoverableContent

boolean

阻止 Tooltip.Content 在悬停时保持打开状态。禁用此功能会影响可访问性。继承自 Tooltip.Provider。

disableClosingTrigger

boolean

当为 true 时,点击触发器不会关闭内容。

disabled

boolean

当为 true 时,禁用工具提示。

ignoreNonKeyboardFocus

boolean

如果焦点不是来自键盘,则通过匹配 :focus-visible 选择器来阻止工具提示打开。这在您希望避免在切换浏览器标签页或关闭对话框时打开它时非常有用。

ui

{ content?: ClassNameValue; arrow?: ClassNameValue; text?: ClassNameValue; kbds?: ClassNameValue; kbdsSize?: ClassNameValue; }

插槽

插槽类型
default

{ open: boolean; }

内容

{}

事件

事件类型
update:open

[value: boolean]

主题

app.config.ts
export default defineAppConfig({
  ui: {
    tooltip: {
      slots: {
        content: 'flex items-center gap-1 bg-default text-highlighted shadow-sm rounded-sm ring ring-default h-6 px-2.5 py-1 text-xs select-none data-[state=delayed-open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-tooltip-content-transform-origin) pointer-events-auto',
        arrow: 'fill-default',
        text: 'truncate',
        kbds: "hidden lg:inline-flex items-center shrink-0 gap-0.5 not-first-of-type:before:content-['·'] not-first-of-type:before:me-0.5",
        kbdsSize: 'sm'
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        tooltip: {
          slots: {
            content: 'flex items-center gap-1 bg-default text-highlighted shadow-sm rounded-sm ring ring-default h-6 px-2.5 py-1 text-xs select-none data-[state=delayed-open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-tooltip-content-transform-origin) pointer-events-auto',
            arrow: 'fill-default',
            text: 'truncate',
            kbds: "hidden lg:inline-flex items-center shrink-0 gap-0.5 not-first-of-type:before:content-['·'] not-first-of-type:before:me-0.5",
            kbdsSize: 'sm'
          }
        }
      }
    })
  ]
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      ui: {
        tooltip: {
          slots: {
            content: 'flex items-center gap-1 bg-default text-highlighted shadow-sm rounded-sm ring ring-default h-6 px-2.5 py-1 text-xs select-none data-[state=delayed-open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-tooltip-content-transform-origin) pointer-events-auto',
            arrow: 'fill-default',
            text: 'truncate',
            kbds: "hidden lg:inline-flex items-center shrink-0 gap-0.5 not-first-of-type:before:content-['·'] not-first-of-type:before:me-0.5",
            kbdsSize: 'sm'
          }
        }
      }
    })
  ]
})