Vue Amazing UI

Appearance

3.9.2

文字提示 Tooltip ​

赞助

悬浮提示，展现需要关注的信息

何时使用 ​

  • 当某个页面需要向用户显示警告的信息时

基本使用 ​

Tesla
Godzilla
Show Code
vue
<script setup lang="ts">
function openChange(open: boolean) {
  console.log('open', open)
}
</script>
<template>
  <Space>
    <Tooltip tooltip="特斯拉" @open-change="openChange">
      <Button type="primary">Tesla</Button>
    </Tooltip>
    <Tooltip tooltip="哥斯拉" @open-change="openChange">
      <Button type="primary">Godzilla</Button>
    </Tooltip>
  </Space>
</template>

自定义样式 ​

气泡卡片用 tooltipClass / tooltipStyle，其外层定位面板用 popupClassName / popupStyle，层级用 zIndex


Card Class
Card Style
Panel Class / zIndex
Show Code
vue
<template>
  <Space gap="large">
    <Tooltip :max-width="360" bg-color="#fff" tooltip-class="custom-class">
      <template #tooltip>
        <p style="text-align: center">卡片类名</p>
        通过 tooltipClass 定制气泡卡片的字号、颜色与内边距
      </template>
      <Button type="primary">Card Class</Button>
    </Tooltip>
    <Tooltip
      :max-width="360"
      bg-color="#fff"
      :tooltip-style="{
        padding: '12px 18px',
        borderRadius: '12px',
        fontSize: '16px',
        color: 'rgba(0, 0, 0, 0.88)'
      }"
    >
      <template #tooltip>
        <p style="text-align: center">卡片样式</p>
        通过 tooltipStyle 定制气泡卡片的样式
      </template>
      <Button type="primary">Card Style</Button>
    </Tooltip>
    <Tooltip
      :arrow="false"
      :max-width="360"
      bg-color="#fff"
      :tooltip-style="{ color: 'rgba(0, 0, 0, 0.88)' }"
      popup-class-name="custom-panel-class"
      :popup-style="{ filter: 'drop-shadow(0 6px 14px rgba(255, 105, 0, 0.45))' }"
      :z-index="1200"
    >
      <template #tooltip>
        <p style="text-align: center">定位面板</p>
        橙色虚线是定位面板（popupClassName），投影来自 popupStyle，层级由 zIndex 指定
      </template>
      <Button type="primary">Panel Class / zIndex</Button>
    </Tooltip>
  </Space>
</template>
<style lang="less">
.custom-class {
  font-size: 16px !important;
  color: #0958d9 !important;
  padding: 12px 18px !important;
  border-radius: 12px !important;
  p {
    margin-bottom: 8px;
    font-size: 20px;
    font-weight: 600;
  }
}
.custom-panel-class {
  border-radius: 8px;
  outline: 1px dashed #ff6900;
}
</style>

位置 ​

位置有 12 个方向


TL
Top
TR
LT
Left
LB
RT
Right
RB
BL
Bottom
BR
Show Code
vue
<script setup lang="ts">
const buttonWidth = 70
</script>
<template>
  <div class="placement-demo">
    <div :style="{ marginLeft: `${buttonWidth}px`, whiteSpace: 'nowrap' }">
      <Tooltip tooltip="Vue Amazing UI" placement="topLeft">
        <Button class="place-btn">TL</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="top">
        <Button class="place-btn">Top</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="topRight">
        <Button class="place-btn">TR</Button>
      </Tooltip>
    </div>
    <div :style="{ width: `${buttonWidth}px`, float: 'left' }">
      <Tooltip tooltip="Vue Amazing UI" placement="leftTop">
        <Button class="place-btn">LT</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="left">
        <Button class="place-btn">Left</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="leftBottom">
        <Button class="place-btn">LB</Button>
      </Tooltip>
    </div>
    <div :style="{ width: `${buttonWidth}px`, marginLeft: `${buttonWidth * 4 + 24}px` }">
      <Tooltip tooltip="Vue Amazing UI" placement="rightTop">
        <Button class="place-btn">RT</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="right">
        <Button class="place-btn">Right</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="rightBottom">
        <Button class="place-btn">RB</Button>
      </Tooltip>
    </div>
    <div :style="{ marginLeft: `${buttonWidth}px`, clear: 'both', whiteSpace: 'nowrap' }">
      <Tooltip tooltip="Vue Amazing UI" placement="bottomLeft">
        <Button class="place-btn">BL</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="bottom">
        <Button class="place-btn">Bottom</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" placement="bottomRight">
        <Button class="place-btn">BR</Button>
      </Tooltip>
    </div>
  </div>
</template>
<style lang="less" scoped>
.placement-demo {
  .place-btn {
    width: 70px;
    margin-right: 8px;
    margin-bottom: 8px;
    text-align: center;
  }
}
</style>

箭头指向 ​

设置了 arrowPointAtCenter 后，箭头将指向目标元素的中心


Align edge / 边缘对齐
Arrow points to center / 箭头指向中心
Show Code
vue
<template>
  <Space>
    <Tooltip tooltip="Vue Amazing UI" placement="topLeft">
      <Button type="primary">Align edge / 边缘对齐</Button>
    </Tooltip>
    <Tooltip tooltip="Vue Amazing UI" placement="topLeft" arrow-point-at-center>
      <Button type="primary">Arrow points to center / 箭头指向中心</Button>
    </Tooltip>
  </Space>
</template>

自动调整位置 ​

请滚动或缩放浏览器窗口来查看自适应调整弹出位置的效果


Flip Automatically
Show Code
vue
<template>
  <Tooltip tooltip="Vue Amazing UI">
    <Button type="primary">Flip Automatically</Button>
  </Tooltip>
</template>

多彩文字提示 ​

我们添加了多种预设色彩的文字提示样式，用作不同场景使用

Presets
pink
red
yellow
orange
cyan
green
blue
purple
geekblue
magenta
volcano
gold
lime
Custom
#f50
#2db7f5
#87d068
#108ee9
Show Code
vue
<script setup lang="ts">
const presetColors = [
  'pink',
  'red',
  'yellow',
  'orange',
  'cyan',
  'green',
  'blue',
  'purple',
  'geekblue',
  'magenta',
  'volcano',
  'gold',
  'lime'
]
const customColors = ['#f50', '#2db7f5', '#87d068', '#108ee9']
</script>
<template>
  <Divider orientation="left">Presets</Divider>
  <Space>
    <Tooltip v-for="color in presetColors" :key="color" tooltip="提示文字" :bg-color="color">
      <Button>{{ color }}</Button>
    </Tooltip>
  </Space>
  <Divider orientation="left">Custom</Divider>
  <Space>
    <Tooltip v-for="color in customColors" :key="color" tooltip="提示文字" :bg-color="color">
      <Button>{{ color }}</Button>
    </Tooltip>
  </Space>
</template>

不同的触发方式 ​

click 触发时再次点击触发器收起；click / contextmenu 触发时点击浮层之外或按 esc 关闭


Hover Me
Click Me
Focus Me
Right Click Me
Show Code
vue
<template>
  <Space>
    <Tooltip>
      <template #tooltip>Vue Amazing UI</template>
      <Button type="primary">Hover Me</Button>
    </Tooltip>
    <Tooltip trigger="click">
      <template #tooltip>Vue Amazing UI</template>
      <Button type="primary">Click Me</Button>
    </Tooltip>
    <Tooltip trigger="focus">
      <template #tooltip>Vue Amazing UI</template>
      <Button type="primary">Focus Me</Button>
    </Tooltip>
    <Tooltip trigger="contextmenu">
      <template #tooltip>Vue Amazing UI</template>
      <Button type="primary">Right Click Me</Button>
    </Tooltip>
  </Space>
</template>

禁用 ​

设置 disabled 后不再响应任何触发


Disabled Tooltip
Show Code
vue
<template>
  <Tooltip tooltip="Vue Amazing UI" disabled>
    <Button type="primary">Disabled Tooltip</Button>
  </Tooltip>
</template>

锚点模式 ​

传入 anchor 后不再渲染触发包裹层，触发监听、tabindex / aria-describedby 与定位均以传入元素为准，使用方的 DOM 结构不随提示显隐变化；getDisabled 在每次展示前求值，返回 true 时不展示


基础锚点
锚点元素（悬停查看提示）
展示前判定
受判定拦截的锚点
放行拦截
Show Code
vue
<script setup lang="ts">
import { ref } from 'vue'
import { Button, Space, Switch, Tooltip } from 'vue-amazing-ui'
const anchorRef = ref<InstanceType<typeof Button> | null>(null)
const gatedAnchorRef = ref<InstanceType<typeof Button> | null>(null)
const gatingAllowed = ref(false)
function gatingDisabled(): boolean {
  return !gatingAllowed.value
}
</script>
<template>
  <Space vertical>
    <Space align="center">
      <span>基础锚点</span>
      <Button ref="anchorRef">锚点元素（悬停查看提示）</Button>
      <Tooltip :anchor="anchorRef?.$el ?? null" tooltip="Vue Amazing UI" />
    </Space>
    <Space align="center">
      <span>展示前判定</span>
      <Button ref="gatedAnchorRef">受判定拦截的锚点</Button>
      <Switch v-model:value="gatingAllowed" checked="放行" unchecked="拦截" />
      <Tooltip :anchor="gatedAnchorRef?.$el ?? null" :get-disabled="gatingDisabled" tooltip="Vue Amazing UI" />
    </Space>
  </Space>
</template>

按键控制 ​

enter 切换显示（需开启 keyboard）；esc 关闭在 trigger 为 click / contextmenu 时于触发器或气泡卡片上按下即可


Click Me
Show Code
vue
<template>
  <Tooltip trigger="click" keyboard>
    <template #tooltip>Vue Amazing UI</template>
    <Button type="primary">Click Me</Button>
  </Tooltip>
</template>

自定义弹出框挂载容器 ​

Stay in place
Mounted to Container
Show Code
vue
<script setup lang="ts">
import { ref } from 'vue'
import { Tooltip } from 'vue-amazing-ui'
const containerRef = ref<HTMLDivElement>()
</script>
<template>
  <div
    ref="containerRef"
    style="display: inline-block; padding: 64px 32px; border-radius: 8px; border: 1px solid #f0f0f0;"
  >
    <Space>
      <Tooltip tooltip="Vue Amazing UI" :to="false">
        <Button type="primary">Stay in place</Button>
      </Tooltip>
      <Tooltip tooltip="Vue Amazing UI" :to="containerRef">
        <Button type="primary">Mounted to Container</Button>
      </Tooltip>
    </Space>
  </div>
</template>

自定义过渡动画时间 ​

Transition Duration 300ms
Show Code
vue
<template>
  <Tooltip :transition-duration="300">
    <template #tooltip>Vue Amazing UI</template>
    <Button type="primary">Transition Duration 300ms</Button>
  </Tooltip>
</template>

延迟显示隐藏 ​

Delay 300ms Tooltip
Delay 500ms Tooltip
Show Code
vue
<template>
  <Space>
    <Tooltip
      :show-delay="300"
      :hide-delay="300"
      tooltip="Vue Amazing UI (delay 300ms)"
      :tooltip-style="{ textAlign: 'center' }"
    >
      <Button type="primary">Delay 300ms Tooltip</Button>
    </Tooltip>
    <Tooltip
      :show-delay="500"
      :hide-delay="500"
      tooltip="Vue Amazing UI (delay 500ms)"
      :tooltip-style="{ textAlign: 'center' }"
    >
      <Button type="primary">Delay 500ms Tooltip</Button>
    </Tooltip>
  </Space>
</template>

使用 Methods ​

Methods Tooltip
显示
隐藏
Show Code
vue
<script setup lang="ts">
import { ref } from 'vue'
import { Tooltip } from 'vue-amazing-ui'
const tooltipRef = ref<InstanceType<typeof Tooltip> | null>(null)
function onShow() {
  tooltipRef.value?.show()
}
function onHide() {
  tooltipRef.value?.hide()
}
</script>
<template>
  <Space>
    <Tooltip ref="tooltipRef" tooltip="Vue Amazing UI">
      <Button type="primary">Methods Tooltip</Button>
    </Tooltip>
    <Button type="primary" @click="onShow">显示</Button>
    <Button @click="onHide">隐藏</Button>
  </Space>
</template>

受控显示 ​

使用 open 属性控制浮层的显示与隐藏：传入即受控，内部触发（悬停 / 点击 / Esc）只经 update:open 上报，是否收起由该属性决定；openControl 为真时 trigger: hover 不再驱动显隐，显隐完全由 open 决定


Controlled: false
Toggle Open
Hover (openControl)
Toggle Open (openControl)
Show Code
vue
<script setup lang="ts">
import { ref } from 'vue'
import { Tooltip } from 'vue-amazing-ui'
const controlledOpen = ref<boolean>(false)
const openControlOpen = ref<boolean>(false)
</script>
<template>
  <Space vertical :gap="12">
    <Space>
      <Tooltip v-model:open="controlledOpen" tooltip="Vue Amazing UI">
        <Button>Controlled: {{ controlledOpen }}</Button>
      </Tooltip>
      <Button type="primary" @click="controlledOpen = !controlledOpen">Toggle Open</Button>
    </Space>
    <Space>
      <Tooltip v-model:open="openControlOpen" open-control tooltip="Hover won't open me">
        <Button>Hover (openControl)</Button>
      </Tooltip>
      <Button type="primary" @click="openControlOpen = !openControlOpen">Toggle Open (openControl)</Button>
    </Space>
  </Space>
</template>

隐藏后卸载 ​

设置 destroyOnHide 后，浮层在离开动画结束时卸载 DOM，再次显示时重新创建并定位；默认 false（元素常驻，仅切换显示）。基于 Tooltip 的 Popover / Popconfirm 同样支持


Hover (destroyOnHide)
Hover (default)
Click: false
Toggle Open
Show Code
vue
<script setup lang="ts">
import { ref } from 'vue'
import { Tooltip } from 'vue-amazing-ui'
const destroyOpen = ref(false)
</script>
<template>
  <Space>
    <Tooltip tooltip="Vue Amazing UI" destroy-on-hide>
      <Button type="primary">Hover (destroyOnHide)</Button>
    </Tooltip>
    <Tooltip tooltip="Vue Amazing UI">
      <Button>Hover (default)</Button>
    </Tooltip>
    <Tooltip v-model:open="destroyOpen" tooltip="Vue Amazing UI" trigger="click" destroy-on-hide>
      <Button type="primary">Click: {{ destroyOpen }}</Button>
    </Tooltip>
    <Button @click="destroyOpen = !destroyOpen">Toggle Open</Button>
  </Space>
</template>

隐藏箭头 ​

Hide Arrow
Show Code
vue
<template>
  <Tooltip :arrow="false" tooltip="Vue Amazing UI">
    <Button type="primary">Hide Arrow</Button>
  </Tooltip>
</template>

APIs ​

Tooltip Props ​

名称说明类型默认值
open
v-model
文字提示是否显示；显式传入（含 false）即为受控，显隐以该值为准，内部触发只经 update:open / openChange 上报（不传时由内部触发自管）booleanundefined
openControl仅当 trigger: hover 时生效：移入移出连 update:open 都不再上报（显隐受控本身由是否传入 open 决定）booleanfalse
content展示的内容stringundefined
tooltip文字提示内容stringundefined
maxWidth文字提示最大宽度，单位 pxstring | number240
bgColor文字提示框背景颜色，支持预设色 (pink | red | yellow | orange | cyan | green | blue | purple | geekblue | magenta | volcano | gold | lime) 或自定义色值 (如 #f50 / rgba)string'var(--va-bg-spotlight-color)'
placement文字提示位置'top' | 'topLeft' | 'topRight' | 'bottom' | 'bottomLeft' | 'bottomRight' | 'left' | 'leftTop' | 'leftBottom' | 'right' | 'rightTop' | 'rightBottom''top'
arrow是否显示箭头booleantrue
arrowPointAtCenter箭头是否指向目标元素中心，仅当 placement 为复合方向 (如 topLeft) 时生效booleanfalse
contentClass设置展示内容的类名stringundefined
contentStyle设置展示内容的样式CSSProperties{}
tooltipClass设置文字提示的类名stringundefined
tooltipStyle设置文字提示的样式CSSProperties{}
popupClassName设置浮层面板（定位盒）的类名，用于自定义面板层样式stringundefined
popupStyle设置浮层面板（定位盒）的样式，在皮肤变量与动画原点之后合并，可覆盖定位CSSProperties{}
disabled是否禁用文字提示，禁用后不响应任何触发booleanfalse
trigger文字提示触发方式 (click 再次点击触发器收起，click / contextmenu 点击浮层之外收起)'hover' | 'click' | 'focus' | 'contextmenu''hover'
keyboard是否支持按键操作 (enter 切换显示)，仅当 trigger: 'click' 时生效；esc 关闭不受此属性控制，trigger 为 click / contextmenu 时始终可用booleanfalse
flip文字提示被浏览器窗口或最近可滚动父元素遮挡时自动调整弹出位置booleantrue
showDelay文字提示显示的延迟时间，单位 ms，仅当 trigger: hover 时生效number100
hideDelay文字提示隐藏的延迟时间，单位 ms，仅当 trigger: hover 时生效number100
destroyOnHide隐藏后是否卸载弹出框 DOM：离开动画结束后卸载整棵浮层子树，再次显示时重新创建并重新定位（适合浮层内容较重、实例较多的场景）booleanfalse
getDisabled展示前的动态禁用判定，每次展示前求值，返回 true 时不展示（如文本未溢出时不需要提示）() => booleanundefined
anchor外部锚点：传入后不再渲染触发包裹层，触发监听、tabindex / aria-describedby 与定位均以该元素为准（此时本组件的 $attrs 不再下发）HTMLElement | nullnull
to弹出框挂载的容器节点：显式传入时按此挂载（元素标签名 (例如 'body') 或元素本身，false 会待在原地）；不传时优先挂到最近的承载层内容容器（Modal / Drawer / Dialog 卡片或上层浮层面板），无承载层时为 bodystring | HTMLElement | falseundefined
zIndex浮层层级，优先级最高（覆盖默认层级与 ConfigProvider 的 baseZIndex 自动分配）numberundefined
transitionDuration文字提示动画的过渡持续时间，单位 msnumber100
tooltipRole气泡卡片的 role，落在 .tooltip-card（与 tooltipStyle 同节点）；对话框类皮肤（见 弹出确认 Popconfirm）改为 alertdialogstring'tooltip'
tooltipLabelledby气泡卡片可访问名称的来源元素 id：role 为 dialog / alertdialog 时必需，普通提示无需设置stringundefined
describedBy是否把气泡卡片的 id 关联到触发器的 aria-describedby；对话框类面板应关闭，否则整块内容会被当作触发器的描述朗读booleantrue

Slots ​

名称说明用法
tooltip自定义文字提示内容v-slot:tooltip
default自定义展示的内容v-slot:default

Events ​

名称说明类型
openChange显示隐藏的回调(open: boolean) => void
animationend显示隐藏动画结束时的回调(open: boolean) => void

Methods ​

名称说明类型
show显示文字提示() => void
hide隐藏文字提示() => void
focusTrigger让焦点回到触发元素（关闭浮层后归还焦点）() => void
tooltipCardRef气泡卡片根元素（供判定焦点是否仍在面板内）HTMLElement | null

Released under the MIT License.

Copyright © 2023-present the Muse Catcher