Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Popover 弹出框
点击、悬停或聚焦某个元素时,在旁边弹出一个小框,里面可以放标题、文字或任意内容(链接、按钮、表单等)。只需要一行说明文字时用 Tooltip,需要用户二次确认时用 Popconfirm。
引入
import { NsPopover } from '@ns/ui'
基础用法
触发元素放在默认插槽里,content 是弹出框里的文字。默认点击触发:点一下打开,再点一下、点弹出框以外的地方或按 Esc 关闭。
<script setup lang="ts">
import { NsPopover, NsButton } from '@ns/ui'
</script>
<template>
<NsPopover content="这是弹出框的内容">
<NsButton>点我</NsButton>
</NsPopover>
</template>
触发方式
trigger 有四种:
click(默认):点击触发元素切换显示;点弹出框以外的地方、按 Esc 关闭。hover:鼠标移入显示、移出隐藏。鼠标可以从触发元素移进弹出框,弹出框不会收起。focus:触发元素(或它里面的输入框、按钮)获得焦点时显示,失去焦点时隐藏。manual:组件自己不响应任何操作(点外面、按 Esc 也不关闭),完全由v-model:visible或show()/hide()方法控制。下面用旁边的两个按钮改visible。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInput, NsPopover, NsSpace } from '@ns/ui'
const password = ref('')
const manualVisible = ref(false)
</script>
<template>
<NsSpace wrap>
<NsPopover content="点一下打开,再点一下、点外面或按 Esc 关闭">
<NsButton>点击(click)</NsButton>
</NsPopover>
<NsPopover trigger="hover" content="鼠标移入显示,移出隐藏">
<NsButton>悬停(hover)</NsButton>
</NsPopover>
<NsPopover trigger="focus" content="6 到 20 位,包含字母和数字">
<NsInput v-model="password" placeholder="聚焦(focus)" style="width: 180px" />
</NsPopover>
<NsPopover
v-model:visible="manualVisible"
trigger="manual"
content="只能用旁边的按钮打开、关闭"
>
<NsButton>手动(manual)</NsButton>
</NsPopover>
<NsButton type="primary" variant="link" @click="manualVisible = true">打开</NsButton>
<NsButton type="primary" variant="link" @click="manualVisible = false">关闭</NsButton>
</NsSpace>
</template>
标题
title 显示在内容上方。
<template>
<NsPopover title="使用说明" content="标题在上,内容在下。">
<NsButton>带标题</NsButton>
</NsPopover>
</template>
位置
placement 有 12 个取值(top、bottom、left、right,各自可以加 -start、-end),默认 top。-start 让弹出框和触发元素的左边(左右两侧时是上边)对齐,-end 和右边(下边)对齐。
指定的方向放不下时自动翻到反方向;弹出框超出视口边缘时会被推回视口内,箭头仍然指着触发元素。下面的示例用 trigger="hover",把鼠标移到按钮上看效果:
<template>
<div class="placements">
<div class="placements__row placements__row--center">
<NsPopover trigger="hover" placement="top-start" content="top-start">
<NsButton>top-start</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="top" content="top">
<NsButton>top</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="top-end" content="top-end">
<NsButton>top-end</NsButton>
</NsPopover>
</div>
<div class="placements__row placements__row--between">
<NsSpace direction="vertical" align="start">
<NsPopover trigger="hover" placement="left-start" content="left-start">
<NsButton>left-start</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="left" content="left">
<NsButton>left</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="left-end" content="left-end">
<NsButton>left-end</NsButton>
</NsPopover>
</NsSpace>
<NsSpace direction="vertical" align="end">
<NsPopover trigger="hover" placement="right-start" content="right-start">
<NsButton>right-start</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="right" content="right">
<NsButton>right</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="right-end" content="right-end">
<NsButton>right-end</NsButton>
</NsPopover>
</NsSpace>
</div>
<div class="placements__row placements__row--center">
<NsPopover trigger="hover" placement="bottom-start" content="bottom-start">
<NsButton>bottom-start</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="bottom" content="bottom">
<NsButton>bottom</NsButton>
</NsPopover>
<NsPopover trigger="hover" placement="bottom-end" content="bottom-end">
<NsButton>bottom-end</NsButton>
</NsPopover>
</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--between {
justify-content: space-between;
margin: var(--ns-spacing-3) 0;
}
</style>
间距
offset 是弹出框和触发元素的间距,单位 px,默认 8。把鼠标移到按钮上对比:
<template>
<NsSpace wrap>
<NsPopover trigger="hover" :offset="4" content="离按钮 4px">
<NsButton>offset 4</NsButton>
</NsPopover>
<NsPopover trigger="hover" content="离按钮 8px">
<NsButton>offset 8(默认)</NsButton>
</NsPopover>
<NsPopover
trigger="hover"
placement="bottom-start"
:offset="16"
content="在下方、左对齐,间距 16px"
>
<NsButton>bottom-start,offset 16</NsButton>
</NsPopover>
<NsPopover trigger="hover" :offset="24" content="离按钮 24px">
<NsButton>offset 24</NsButton>
</NsPopover>
</NsSpace>
</template>
宽度和箭头
width 传数字时按 px 处理,也可以传带单位的字符串;不传时宽度随内容变化(最小 150px,最大不超过视口)。show-arrow 设为 false 隐藏箭头。
<template>
<NsSpace wrap>
<NsPopover content="短内容">
<NsButton>不设宽度</NsButton>
</NsPopover>
<NsPopover :width="300" content="宽度固定 300px,内容超过宽度时自动换行。">
<NsButton>:width="300"</NsButton>
</NsPopover>
<NsPopover width="20em" content="宽度是 20em,字符串原样使用">
<NsButton>width="20em"</NsButton>
</NsPopover>
<NsPopover :show-arrow="false" content="没有箭头">
<NsButton>不显示箭头</NsButton>
</NsPopover>
</NsSpace>
</template>
自定义内容
用 content 插槽放任意内容。
<template>
<NsPopover title="分享到" :width="220">
<NsButton>分享</NsButton>
<template #content>
<div style="display: flex; gap: 8px;">
<NsButton size="small">复制链接</NsButton>
<NsButton size="small" type="primary">发送</NsButton>
</div>
</template>
</NsPopover>
</template>
触发元素写在 reference 插槽里
reference 插槽和默认插槽作用相同,同时写了两个时用 reference。
<template>
<NsPopover content="触发元素写在 reference 插槽里">
<template #reference>
<NsButton>reference 插槽</NsButton>
</template>
</NsPopover>
</template>
受控显示
用 v-model:visible 时,用户的操作(点击、悬停、点外面、Esc)会更新绑定的变量,外部改变量也能打开、关闭。
<script setup lang="ts">
import { ref } from 'vue'
import { NsPopover, NsButton, NsSpace } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsSpace wrap>
<NsPopover v-model:visible="visible" content="点按钮或点外部的开关都能控制">
<NsButton>触发元素</NsButton>
</NsPopover>
<NsButton @click="visible = !visible">外部开关</NsButton>
</NsSpace>
</template>
想完全自己控制(触发元素本身就是开关按钮)时,把 trigger 设为 manual:
<script setup lang="ts">
import { ref } from 'vue'
import { NsPopover, NsButton } from '@ns/ui'
const visible = ref(false)
</script>
<template>
<NsPopover v-model:visible="visible" trigger="manual" content="只由按钮控制">
<NsButton @click="visible = !visible">手动控制</NsButton>
</NsPopover>
</template>
通过方法控制
通过组件的 ref 调用 show()、hide(),ref 上的 actualVisible 是当前是否显示。
弹出框只在滚动、窗口缩放、触发元素或弹出框的尺寸变化时自动重新定位。触发元素只是挪了位置(例如改了外边距)时不会跟着走,这时调用 updatePosition()。先点 show(),再分别点后面两个按钮对比:
<script setup lang="ts">
import { nextTick, ref } from 'vue'
import { NsPopover, NsButton, NsSpace } from '@ns/ui'
const popoverRef = ref<InstanceType<typeof NsPopover>>()
const shift = ref(0)
const move = async (update: boolean) => {
shift.value = shift.value ? 0 : 120
if (update) {
// 等触发元素挪到新位置后再重新定位
await nextTick()
popoverRef.value?.updatePosition()
}
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton @click="popoverRef?.show()">show()</NsButton>
<NsButton @click="popoverRef?.hide()">hide()</NsButton>
<NsButton @click="move(false)">只挪动触发元素</NsButton>
<NsButton type="primary" @click="move(true)">挪动后 updatePosition()</NsButton>
</NsSpace>
<NsPopover
ref="popoverRef"
trigger="manual"
placement="right"
content="用方法打开的"
:style="{ marginLeft: `${shift}px` }"
>
<NsButton>触发元素</NsButton>
</NsPopover>
<span>actualVisible:{{ popoverRef?.actualVisible ?? false }}</span>
</NsSpace>
</template>
事件
弹出框真的显示出来时触发 show,隐藏时触发 hide。打开、关闭几次,看下面的计数:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsPopover } from '@ns/ui'
const showCount = ref(0)
const hideCount = ref(0)
</script>
<template>
<NsPopover content="打开、关闭时下面的计数会变" @show="showCount++" @hide="hideCount++">
<NsButton>点我</NsButton>
</NsPopover>
<p style="margin-top: 12px">show 触发 {{ showCount }} 次,hide 触发 {{ hideCount }} 次</p>
</template>
禁用
disabled 为 true 时不显示。正在显示时被禁用会立即收起,取消禁用后不会自己再弹出来。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCheckbox, NsPopover, NsSpace } from '@ns/ui'
const disabled = ref(true)
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="disabled">禁用弹出框</NsCheckbox>
<NsPopover content="没被禁用时才会显示" :disabled="disabled">
<NsButton>点我</NsButton>
</NsPopover>
</NsSpace>
</template>
自定义类名和过渡动画
popper-class 加在弹出框元素上,用来单独改某一个弹出框的样式。弹出框挂在 body 下,样式要写成全局的(不带 scoped),类名起得独特一些,免得影响别处。
transition 是 Vue <Transition> 的 name,默认 ns-popover-fade(淡入淡出),自己写对应的 -enter-active、-enter-from 等类名。
<template>
<NsSpace wrap>
<NsPopover
popper-class="demo-popover-accent"
title="提示"
content="左边多了一条主色竖线,内边距也加大了"
>
<NsButton>popper-class</NsButton>
</NsPopover>
<NsPopover transition="demo-popover-zoom" content="缩放着出现">
<NsButton>transition</NsButton>
</NsPopover>
</NsSpace>
</template>
<style>
.ns-popover__popper.demo-popover-accent {
padding: var(--ns-spacing-4);
border-left: 3px solid var(--ns-color-primary);
}
.demo-popover-zoom-enter-active,
.demo-popover-zoom-leave-active {
transition:
opacity 0.2s ease,
transform 0.2s ease;
}
.demo-popover-zoom-enter-from,
.demo-popover-zoom-leave-to {
opacity: 0;
transform: scale(0.8);
}
</style>
挂载位置
弹出框默认挂在 body 下。teleport 传 CSS 选择器可以挂到别的元素下,传 false 则留在组件所在的位置(传 true 等同于 'body')。
<template>
<NsPopover content="留在组件所在的位置" :teleport="false">
<NsButton>:teleport="false"</NsButton>
</NsPopover>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| content | string | - | 弹出框里的文字。也可以用 content 插槽 |
| title | string | - | 标题 |
| placement | PopperPlacement | 'top' | 出现的位置,12 个取值见“类型”。放不下时自动翻到反方向 |
| trigger | 'hover' | 'click' | 'focus' | 'manual' | 'click' | 触发方式 |
| width | number | string | - | 弹出框宽度,数字按 px 处理。不传时随内容变化 |
| offset | number | 8 | 弹出框和触发元素的间距,单位 px |
| disabled | boolean | false | 是否禁用 |
| visible | boolean | - | 是否显示,支持 v-model:visible |
| showArrow | boolean | true | 是否显示箭头 |
| popperClass | string | - | 加在弹出框上的类名 |
| transition | string | 'ns-popover-fade' | 过渡动画的名字(<Transition> 的 name) |
| teleport | string | boolean | 'body' | 弹出框挂到哪个元素下(CSS 选择器)。传 false 时留在组件所在的位置 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:visible | (value: boolean) | 传了 visible 时,用户的操作或方法调用要改变显示状态时触发 |
| show | - | 弹出框显示出来时触发 |
| hide | - | 弹出框隐藏时触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 触发元素 |
| reference | - | 触发元素,和默认插槽作用相同,优先于默认插槽 |
| content | - | 弹出框内容,替换 content 属性 |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| show | - | void | 显示弹出框。传了 visible 时只触发 update:visible(true) |
| hide | - | void | 隐藏弹出框。传了 visible 时只触发 update:visible(false) |
| updatePosition | - | void | 按触发元素当前的位置重新定位 |
ref 上还有一个只读的 actualVisible(boolean),表示弹出框当前是否显示。
类型
import type { PopoverTrigger, PopoverProps, PopperPlacement } from '@ns/ui'
type PopoverTrigger = 'hover' | 'click' | 'focus' | 'manual'
type PopperPlacement =
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'
注意事项
- 用了
v-model:visible、又在触发元素上自己写点击事件去改这个变量时,要把trigger设为manual。否则一次点击会被处理两次(你的点击事件打开,组件的点击触发又关上)。 - 只写
:visible、不接收update:visible时,显示与否完全由外部决定,用户的操作不起作用。 show、hide事件在弹出框真的显示、隐藏时才触发:受控时要等外部把visible改了才触发,重复调用show()不会重复触发。- 弹出框显示时按 Esc 只关闭弹出框。它放在对话框、抽屉里时,这次 Esc 不会把对话框、抽屉一起关掉。
trigger="click"时,点弹出框和触发元素以外的任何地方都会关闭。弹出框里如果有挂在body下的浮层(下拉选择、日期面板等),点这些浮层也会被当成“点了外面”;这种情况用trigger="manual"自己控制关闭。- 触发元素外面会包一层
display: inline-block的div。 - 弹出框用
position: fixed定位,显示期间会跟着页面、滚动容器的滚动和窗口缩放重新定位。
优化点
- [ ] 弹出框里嵌套挂在
body下的浮层时,点嵌套浮层不应该关闭弹出框 - [ ]
hover触发支持配置显示、隐藏的延迟(现在隐藏固定延迟 100 毫秒) - [ ] 打开后把焦点移进弹出框、关闭后还原(现在只有 Popconfirm 做了)
- [ ] 支持虚拟触发元素(传入一个已有的 DOM 元素或坐标)