Tooltip 文字提示
鼠标移到元素上或元素获得焦点时,在旁边显示一小段说明文字。适合解释图标按钮、被截断的文字等,内容只读、不需要点击。需要在弹出层里放按钮、链接时用 Popover。
引入
import { NsTooltip } from '@ns/ui'
基础用法
把要说明的元素放在默认插槽里,content 是提示文字。
<script setup lang="ts">
import { NsTooltip, NsButton } from '@ns/ui'
</script>
<template>
<NsTooltip content="保存当前修改">
<NsButton>保存</NsButton>
</NsTooltip>
</template>
常见用法
只有图标的按钮、被截断的长文字,都适合用提示补充说明。
<template>
<NsSpace wrap align="center">
<NsTooltip content="编辑">
<NsButton icon="edit" aria-label="编辑" />
</NsTooltip>
<NsTooltip content="分享">
<NsButton icon="share" aria-label="分享" />
</NsTooltip>
<NsTooltip content="删除">
<NsButton type="danger" icon="trash" aria-label="删除" />
</NsTooltip>
<NsTooltip content="2026 年第三季度华东区域销售数据汇总(含退货).xlsx">
<span class="ellipsis">2026 年第三季度华东区域销售数据汇总(含退货).xlsx</span>
</NsTooltip>
</NsSpace>
</template>
<style scoped>
.ellipsis {
display: inline-block;
max-width: 160px;
overflow: hidden;
white-space: nowrap;
text-overflow: ellipsis;
vertical-align: middle;
}
</style>
主题
effect 有两种:
dark(默认):和页面背景相反的颜色。浅色主题下是深底浅字,暗色主题下是浅底深字。light:底色和页面背景相同(浅色主题下是白底),加一圈边框。
<template>
<NsSpace wrap>
<NsTooltip content="深色提示" effect="dark">
<NsButton>深色(dark)</NsButton>
</NsTooltip>
<NsTooltip content="浅色提示" effect="light">
<NsButton>浅色(light)</NsButton>
</NsTooltip>
</NsSpace>
</template>
位置
placement 有 12 个取值:top、bottom、left、right 四个方向,每个方向可以加 -start 或 -end 让提示框和元素的一边对齐(上下方向对齐左边或右边,左右方向对齐上边或下边)。默认是 top。
指定的方向放不下时会自动翻到反方向;提示框超出视口左右(或上下)边缘时会被推回视口内,箭头仍然指着触发元素。把鼠标移到下面的按钮上看效果,上面的开关可以切换两种主题:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsRadio, NsRadioGroup, NsSpace, NsTooltip } from '@ns/ui'
import type { TooltipEffect } from '@ns/ui'
const effect = ref<TooltipEffect>('dark')
</script>
<template>
<div class="placements">
<div class="placements__row placements__row--center">
<NsRadioGroup v-model="effect" type="button" size="small">
<NsRadio value="dark" label="dark" />
<NsRadio value="light" label="light" />
</NsRadioGroup>
</div>
<div class="placements__row placements__row--center">
<NsTooltip :effect="effect" placement="top-start" content="top-start">
<NsButton>top-start</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="top" content="top">
<NsButton>top</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="top-end" content="top-end">
<NsButton>top-end</NsButton>
</NsTooltip>
</div>
<div class="placements__row placements__row--between">
<NsSpace direction="vertical" align="start">
<NsTooltip :effect="effect" placement="left-start" content="left-start">
<NsButton>left-start</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="left" content="left">
<NsButton>left</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="left-end" content="left-end">
<NsButton>left-end</NsButton>
</NsTooltip>
</NsSpace>
<NsSpace direction="vertical" align="end">
<NsTooltip :effect="effect" placement="right-start" content="right-start">
<NsButton>right-start</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="right" content="right">
<NsButton>right</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="right-end" content="right-end">
<NsButton>right-end</NsButton>
</NsTooltip>
</NsSpace>
</div>
<div class="placements__row placements__row--center">
<NsTooltip :effect="effect" placement="bottom-start" content="bottom-start">
<NsButton>bottom-start</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="bottom" content="bottom">
<NsButton>bottom</NsButton>
</NsTooltip>
<NsTooltip :effect="effect" placement="bottom-end" content="bottom-end">
<NsButton>bottom-end</NsButton>
</NsTooltip>
</div>
</div>
</template>
<style scoped>
.placements {
max-width: 520px;
margin: 0 auto;
}
.placements__row {
display: flex;
gap: var(--ns-spacing-2);
}
.placements__row--center {
justify-content: center;
}
.placements__row--center + .placements__row--center {
margin-top: var(--ns-spacing-6);
}
.placements__row--between {
justify-content: space-between;
margin: var(--ns-spacing-3) 0;
}
</style>
触发方式
提示没有 trigger 属性,固定是悬停和聚焦两种方式都能触发:
- 悬停:鼠标移入显示、移出隐藏。鼠标移到提示框上不会让它保持显示。
- 聚焦:触发元素(或它里面的按钮、输入框)获得焦点时显示,失去焦点时隐藏。键盘用户按 Tab 也能看到提示。
- 手动控制:只传
:visible、不接收update:visible,这时鼠标和焦点都不起作用,完全由外部的变量决定。下面用旁边的两个按钮改这个变量。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInput, NsSpace, NsTooltip } from '@ns/ui'
const keyword = ref('')
const visible = ref(false)
</script>
<template>
<NsSpace wrap>
<NsTooltip content="鼠标移入显示,移出隐藏">
<NsButton>悬停</NsButton>
</NsTooltip>
<NsTooltip content="输入框获得焦点时显示,失去焦点后隐藏">
<NsInput v-model="keyword" placeholder="聚焦" style="width: 160px" />
</NsTooltip>
<NsTooltip :visible="visible" content="只由旁边的按钮控制">
<NsButton>手动(只传 :visible)</NsButton>
</NsTooltip>
<NsButton type="primary" variant="link" @click="visible = true">打开</NsButton>
<NsButton type="primary" variant="link" @click="visible = false">关闭</NsButton>
</NsSpace>
</template>
间距
offset 是提示框和触发元素之间的距离,单位 px,默认 8。
<template>
<NsSpace wrap>
<NsTooltip content="离按钮 4px" :offset="4">
<NsButton>间距 4</NsButton>
</NsTooltip>
<NsTooltip content="离按钮 8px">
<NsButton>间距 8(默认)</NsButton>
</NsTooltip>
<NsTooltip content="离按钮 24px" :offset="24">
<NsButton>间距 24</NsButton>
</NsTooltip>
</NsSpace>
</template>
自定义内容
内容不只是一行文字时用 content 插槽。提示框最宽 300px,超过后自动换行。
<template>
<NsSpace wrap>
<NsTooltip effect="light">
<NsButton>快捷键</NsButton>
<template #content>
<div>保存:Ctrl + S</div>
<div>撤销:Ctrl + Z</div>
</template>
</NsTooltip>
<NsTooltip
content="这是一段比较长的说明文字,提示框最宽 300px,超过以后会自动换行,不会一直往右延伸到屏幕外面。"
>
<NsButton>长文字自动换行</NsButton>
</NsTooltip>
</NsSpace>
</template>
延迟显示和隐藏
showAfter 是鼠标移入后等多久才显示,hideAfter 是移出后等多久才隐藏,单位毫秒。没等到就移出(或移回)会取消这次显示(或隐藏)。两个延迟只对鼠标有效,获得、失去焦点时立即显示、隐藏。
<template>
<NsSpace wrap>
<NsTooltip content="移入 500 毫秒后显示" :show-after="500">
<NsButton>延迟显示</NsButton>
</NsTooltip>
<NsTooltip content="移出 1 秒后隐藏" :hide-after="1000">
<NsButton>延迟隐藏</NsButton>
</NsTooltip>
<NsTooltip
content="移入 300 毫秒后显示,移出 800 毫秒后隐藏"
:show-after="300"
:hide-after="800"
>
<NsButton>两个都延迟</NsButton>
</NsTooltip>
</NsSpace>
</template>
禁用
disabled 为 true 时不显示。正在显示时被禁用会立即收起。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTooltip, NsButton, NsCheckbox, NsSpace } from '@ns/ui'
const disabled = ref(false)
</script>
<template>
<NsSpace wrap>
<NsTooltip content="没被禁用时才会显示" :disabled="disabled">
<NsButton>鼠标移上来</NsButton>
</NsTooltip>
<NsCheckbox v-model="disabled">禁用提示</NsCheckbox>
</NsSpace>
</template>
受控显示
用 v-model:visible 时,鼠标移入移出会更新绑定的变量,外部改这个变量也能显示、隐藏。只写 :visible(不接收 update:visible)时,显示与否完全由外部决定,鼠标移入移出不起作用(见“触发方式”里的手动控制)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTooltip, NsButton, NsSpace } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsSpace wrap>
<NsTooltip v-model:visible="visible" content="悬停和外部按钮都能控制">
<NsButton>双向绑定</NsButton>
</NsTooltip>
<NsButton @click="visible = !visible">切换</NsButton>
<span>visible:{{ visible }}</span>
</NsSpace>
</template>
自定义过渡动画
transition 是 Vue <Transition> 的 name,默认 ns-tooltip-fade(淡入淡出),自己写对应的 -enter-active、-enter-from 等类名。提示框挂在 body 下,样式要写成全局的(不带 scoped)。
<template>
<NsTooltip content="缩放着出现" transition="my-zoom">
<NsButton>缩放动画</NsButton>
</NsTooltip>
</template>
<style>
.my-zoom-enter-active,
.my-zoom-leave-active {
transition:
opacity 0.3s ease,
transform 0.3s ease;
}
.my-zoom-enter-from,
.my-zoom-leave-to {
opacity: 0;
transform: scale(0.6);
}
</style>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| content | string | - | 提示文字。也可以用 content 插槽。两者都没有时不显示 |
| placement | TooltipPlacement | 'top' | 出现的位置,12 个取值见“类型”。放不下时自动翻到反方向 |
| disabled | boolean | false | 是否禁用 |
| offset | number | 8 | 提示框和触发元素的间距,单位 px |
| transition | string | 'ns-tooltip-fade' | 过渡动画的名字(<Transition> 的 name) |
| visible | boolean | - | 是否显示,支持 v-model:visible。不传时由组件自己根据鼠标、焦点决定 |
| showAfter | number | 0 | 鼠标移入后延迟多少毫秒显示。只对鼠标移入有效,获得焦点时立即显示 |
| hideAfter | number | 0 | 鼠标移出后延迟多少毫秒隐藏。只对鼠标移出有效,失去焦点时立即隐藏 |
| effect | 'dark' | 'light' | 'dark' | 主题:dark 是和页面背景相反的颜色,light 是浅色底加边框 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:visible | (value: boolean) | 传了 visible 时,鼠标移入移出、获得或失去焦点要改变显示状态时触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 触发提示的元素 |
| content | - | 提示内容,替换 content 属性 |
类型
import type { TooltipPlacement, TooltipEffect, TooltipProps } from '@ns/ui'
type TooltipPlacement =
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'
type TooltipEffect = 'dark' | 'light'
注意事项
- 触发元素外面会包一层
display: inline-block的div。要让触发元素撑满一行时,给NsTooltip加style="display: block",或者自己调整布局。 - 提示框挂在
body下,用position: fixed定位,显示期间会跟着页面、滚动容器的滚动和窗口缩放重新定位。 - 鼠标移到提示框上不会让它保持显示,所以提示框里不要放需要点击的内容,那种情况用 Popover。
- 键盘用户按 Tab 聚焦到触发元素(或它里面的按钮、输入框)时也会显示提示。
- 被禁用的原生按钮(
<button disabled>)不会触发鼠标事件,要给它加提示时,在按钮外面再包一层span。
优化点
- [ ] 支持
trigger(如点击触发),现在只有悬停和聚焦两种触发方式 - [ ] 鼠标移进提示框时保持显示(enterable),方便复制提示里的文字
- [ ] 支持
teleport指定挂载位置或不传送 - [ ] 支持
showArrow隐藏箭头、popperClass自定义提示框类名 - [x] 提示框和触发元素用
aria-describedby关联起来(显示期间加在插槽里的第一个元素上)