Tooltip 文字提示

常用于展示鼠标 hover 时的提示信息。

基础用法

在这里提供了 9 种不同方向的展示方式, 可以通过以下完整示例来理解, 选择需要的效果。

使用 content 属性来决定 hover 时的提示信息。 由 placement 属性来决定展示的方向: [方向]-[对齐位置]; 四个方向: top, bottom, left, right; 三种对齐位置: start, end, 默认为空。 如 placement="left-end", 则提示信息出现在目标元素左侧, 且提示信息的底部与目标元素底部对齐。

<template>
  <div class="tooltip-base-box">
    <div class="row center">
      <px-tooltip
        class="box-item"
        content="Top Left prompts info"
        placement="top-start"
      >
        <px-button>top-start</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Top Center prompts info"
        placement="top"
      >
        <px-button>top</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Top Right prompts info"
        placement="top-end"
      >
        <px-button>top-end</px-button>
      </px-tooltip>
    </div>
    <div class="row">
      <px-tooltip
        class="box-item"
        content="Left Top prompts info"
        placement="left-start"
      >
        <px-button>left-start</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Right Top prompts info"
        placement="right-start"
      >
        <px-button>right-start</px-button>
      </px-tooltip>
    </div>
    <div class="row">
      <px-tooltip
        class="box-item"
        content="Left Center prompts info"
        placement="left"
      >
        <px-button class="mt-3 mb-3">left</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Right Center prompts info"
        placement="right"
      >
        <px-button>right</px-button>
      </px-tooltip>
    </div>
    <div class="row">
      <px-tooltip
        class="box-item"
        content="Left Bottom prompts info"
        placement="left-end"
      >
        <px-button>left-end</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Right Bottom prompts info"
        placement="right-end"
      >
        <px-button>right-end</px-button>
      </px-tooltip>
    </div>
    <div class="row center">
      <px-tooltip
        class="box-item"
        content="Bottom Left prompts info"
        placement="bottom-start"
      >
        <px-button>bottom-start</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Bottom Center prompts info"
        placement="bottom"
      >
        <px-button>bottom</px-button>
      </px-tooltip>
      <px-tooltip
        class="box-item"
        content="Bottom Right prompts info"
        placement="bottom-end"
      >
        <px-button>bottom-end</px-button>
      </px-tooltip>
    </div>
  </div>
</template>

<style>
.tooltip-base-box .row {
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.tooltip-base-box .center {
  justify-content: center;
}
.tooltip-base-box .box-item {
  margin-top: 10px;
}
</style>

触发方式

Tooltip 默认是 hover 触发, 也可以通过 trigger 属性来设置触发方式: hover, click, contextmenu。

<template>
  <px-tooltip content="hover trigger">
    <px-button>hover</px-button>
  </px-tooltip>
  <px-tooltip trigger="click" content="click trigger">
    <px-button>click</px-button>
  </px-tooltip>
  <px-tooltip trigger="contextmenu" content="contextmenu trigger">
    <px-button>contextmenu</px-button>
  </px-tooltip>
</template>

主题

Tooltip 组件内置了两个主题: light 和 dark。

TIP

要使用自定义主题, 您必须知道您的工具提示在哪里渲染, 如果您的工具提示被呈现为根元素, 您将需要全局设置css规则。

设置自定义主题时, 需要同时修改弹出箭头和内容样式, 具体设置见下方 demo-preview

由于组件库祖宗之法基于 css houdini paintWorklet, 像素盒子大部分基于 pixelbox 渲染, 当前仅提供纯色主题, 如果希望渲染线性渐变, 等待后续升级

通过设置 effect 来修改主题, 默认为 light。

<template>
  <px-tooltip content="light theme">
    <px-button>Light</px-button>
  </px-tooltip>
  <px-tooltip content="dark theme" effect="dark">
    <px-button>Dark</px-button>
  </px-tooltip>

  <px-tooltip content="customized theme" effect="customized">
    <px-button>Customized theme</px-button>
  </px-tooltip>
</template>

<style>
.px-tooltip .px-tooltip__popper.is-customized {
  --px-bg-color: #9fe597;
  --px-border-color: #9fe597;
  --px-popover-text-color: red;
}

.px-tooltip .px-tooltip__popper.is-customized #arrow::before {
  --px-popover-bg-color: #9fe597;
  --px-popover-border-color: #9fe597;
}
</style>

更多内容的文字提示

展示多行文本或者是设置文本内容的格式

使用具名插槽 content, 代替 content 属性。

<template>
  <px-tooltip placement="top">
    <template #content>
      <px-text tag="div" color="#9fe597">multiple lines</px-text>
      <px-text tag="div" color="#cce581">second line</px-text>
    </template>
    <px-button>Top center</px-button>
  </px-tooltip>
</template>

高级扩展

除了这些基本设置外，还有一些属性可以让使用者更好的定制自己的效果:

transition 属性可以定制显隐的动画效果，默认为fade。

如果需要关闭 tooltip 功能, 可以使用 disabled 属性

Tooltip 是一个基于 popperjs 二次封装的扩展, 可以通过 popperOptions 属性来定制 popperjs 的配置。

<script lang="ts" setup>
import { ref } from 'vue'

const disabled = ref(false)
</script>
<template>
  <px-tooltip
    :disabled="disabled"
    content="click to close tooltip function"
    placement="bottom"
  >
    <px-button @click="disabled = !disabled" size="small">
      click to {{ disabled ? 'active' : 'close' }} tooltip function
    </px-button>
  </px-tooltip>
</template>

虚拟触发

有时候我们想把 tooltip 的触发元素放在别的地方，而不需要写在一起，这时候就可以使用虚拟触发。

WARNING

设计缺陷问题, 由虚拟触发的 popover 元素需要光标从 placement 位置移出才能触发消失事件, 暂未解决。

<script setup leng="ts">
import { ref, computed } from 'vue'

const virtualTrigger = ref()

const virtualRef = computed(() => {
  const el = virtualTrigger.value
  return el?.$el ?? el
})
</script>

<template>
  <px-tooltip
    content="Bottom center"
    placement="bottom"
    trigger="hover"
    virtual-triggering
    :virtual-ref="virtualRef"
  ></px-tooltip>
  <px-button ref="virtualTrigger" size="small">virtual trigger</px-button>
</template>

手动模式

通过 manual 属性, 可以设置 tooltip 的触发模式为手动模式, 调用组件暴露的 show 和 hide 方法即可。

<script setup lang="ts">
import { ref } from 'vue'
import type { TooltipInstance } from '@mmt817/pixel-ui'

const tooltipRef = ref<TooltipInstance>()
const open = () => {
  tooltipRef.value?.show()
}
const close = () => {
  tooltipRef.value?.hide()
}
</script>

<template>
  <px-tooltip ref="tooltipRef" content="手动控制的提示" manual placement="top">
    <px-button>手动控制提示</px-button>
  </px-tooltip>
  <div class="mt-20 gap-10">
    <px-button @click="open">显示</px-button>
    <px-button @click="close">隐藏</px-button>
  </div>
</template>

自定义动画

Tooltip 可以自定义动画, 通过 transition 属性来设置动画名称, 默认为 fade。

TIP

过渡效果的更多信息可以在 Vue 过渡效果 中找到。

<template>
  <px-tooltip content="I am an px-tooltip" transition="slide-fade">
    <px-button>trigger me</px-button>
  </px-tooltip>
</template>

<style>
.slide-fade-enter-active {
  transition: all 0.3s ease-out;
}

.slide-fade-leave-active {
  transition: all 0.8s cubic-bezier(1, 0.5, 0.8, 1);
}

.slide-fade-enter-from,
.slide-fade-leave-to {
  transform: translateX(120px);
  opacity: 0;
}
</style>

Tooltip API

Props

Name	Description	Type	Default
content	显示内容,可被slot#content覆盖	string	—
trigger	触发方式	enum - hover | click | contextmenu	hover
placement	组件出现位置	enum	bottom
manual	手动控制	boolean	false
disabled	是否禁用	boolean	false
popperOptions	popperjs配置	Partial<Options>	{}
effect	主题样式	enum - light | dark | customized	light
transition	过渡效果	enum	fade
showTimeout	显示延时	number	0
hideTimeout	隐藏延时	number	200

Events

Name	Description	Type
visible-change	Popover 可见性改变时触发	(_val: boolean) => void
click-outside	点击区域外时触发	() => void

Slots

Name	Description
default	Tooltip 触发 & 引用的元素
content	自定义内容

Expose

Name	Description	Type
show	展示 Popover	() => void
hide	关闭 Popover	() => void