Vant3 中文入门教程 Vant3 Popover 气泡弹出框

2024-02-25 开发教程 Vant3 中文入门教程 匿名 4

介绍

弹出式的气泡菜单。

实例演示

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Popover } from 'vant';
const app = createApp();
app.use(Popover);

代码演示

基础用法

当 Popover 弹出时,会基于 reference插槽的内容进行定位。

<van-popover v-model:show="showPopover" :actions="actions" @select="onSelect">
<template #reference>
<van-button type="primary">浅色风格</van-button>
</template>
</van-popover>
import { ref } from 'vue';
import { Toast } from 'vant';
export default {
setup() {
const showPopover = ref(false);
// 通过 actions 属性来定义菜单选项
const actions = [
{ text: '选项一' },
{ text: '选项二' },
{ text: '选项三' },
];
const onSelect = (action) => Toast(action.text);
return {
actions,
onSelect,
showPopover,
};
},
};

深色风格

Popover 支持浅色和深色两种风格,默认为浅色风格,将 theme属性设置为 dark可切换为深色风格。

<van-popover v-model:show="showPopover" theme="dark" :actions="actions">
<template #reference>
<van-button type="primary">深色风格</van-button>
</template>
</van-popover>
import { ref } from 'vue';
export default {
setup() {
const showPopover = ref(false);
const actions = [
{ text: '选项一' },
{ text: '选项二' },
{ text: '选项三' },
];
return {
actions,
showPopover,
};
},
};

弹出位置

通过 placement属性来控制气泡的弹出位置。

<van-popover placement="top" />

placement支持以下值:

top           # 顶部中间位置
top-start # 顶部左侧位置
top-end # 顶部右侧位置
left # 左侧中间位置
left-start # 左侧上方位置
left-end # 左侧下方位置
right # 右侧中间位置
right-start # 右侧上方位置
right-end # 右侧下方位置
bottom # 底部中间位置
bottom-start # 底部左侧位置
bottom-end # 底部右侧位置

展示图标

actions数组中,可以通过 icon字段来定义选项的图标,支持传入图标名称或图片链接。

<van-popover v-model:show="showPopover" :actions="actions">
<template #reference>
<van-button type="primary">展示图标</van-button>
</template>
</van-popover>
import { ref } from 'vue';
export default {
setup() {
const showPopover = ref(false);
const actions = [
{ text: '选项一', icon: 'add-o' },
{ text: '选项二', icon: 'music-o' },
{ text: '选项三', icon: 'more-o' },
];
return {
actions,
showPopover,
};
},
};

禁用选项

actions数组中,可以通过 disabled字段来禁用某个选项。

<van-popover v-model:show="showPopover" :actions="actions">
<template #reference>
<van-button type="primary">禁用选项</van-button>
</template>
</van-popover>
import { ref } from 'vue';
export default {
setup() {
const showPopover = ref(false);
const actions = [
{ text: '选项一', disabled: true },
{ text: '选项二', disabled: true },
{ text: '选项三' },
];
return {
actions,
showPopover,
};
},
};

自定义内容

通过默认插槽,可以在 Popover 内部放置任意内容。

<van-popover v-model:show="showPopover">
<van-grid
square
clickable
:border="false"
column-num="3"
style="width: 240px;"
>
<van-grid-item
v-for="i in 6"
:key="i"
text="选项"
icon="photo-o"
@click="showPopover = false"
/>
</van-grid>
<template #reference>
<van-button type="primary">自定义内容</van-button>
</template>
</van-popover>
import { ref } from 'vue';
export default {
setup() {
const showPopover = ref(false);
return { showPopover };
},
};

API

Props

参数说明类型默认值
v-model:show是否展示气泡弹出层

boolean

false

actions选项列表

Action[]

[]

placement弹出位置

string

bottom

theme

主题风格,可选值为 dark

string

light

trigger

触发方式,可选值为 manual

click

duration动画时长,单位秒,设置为 0 可以禁用动画

number | string

0.3

offset出现位置的偏移量

[number, number]

[0, 8]

overlay是否显示遮罩层

boolean

false

overlay-class v3.0.10

自定义遮罩层类名

string | Array | object

-

overlay-style v3.0.10

自定义遮罩层样式

object

-
close-on-click-action是否在点击选项后关闭

boolean

true

close-on-click-outside是否在点击外部元素后关闭菜单

boolean

true

close-on-click-overlay v3.0.10

是否在点击遮罩层后关闭菜单

boolean

true

teleport

指定挂载的节点,等同于 Teleport 组件的 to 属性

string | Element

body

icon-prefix v3.0.17

图标类名前缀,等同于 Icon 组件的 class-prefix 属性

string

van-icon

Action 数据结构

actions属性是一个由对象构成的数组,数组中的每个对象配置一列,对象可以包含以下值:

键名说明类型
text选项文字

string

icon文字左侧的图标,支持传入图标名称或图片链接

string

color选项文字颜色

string

disabled是否为禁用状态

boolean

className为对应选项添加额外的类名

string | Array | object

Events

事件名说明回调参数
select点击选项时触发

action: Action, index: number

open打开菜单时触发-
close关闭菜单时触发-
opened打开菜单且动画结束后触发-
closed关闭菜单且动画结束后触发-
click-overlay点击遮罩层时触发

event: MouseEvent

Slots

名称说明
default自定义菜单内容
reference触发 Popover 显示的元素内容

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-popover-arrow-size

6px

-
--van-popover-border-radius

var(--van-border-radius-lg)

-
--van-popover-action-width

128px

-
--van-popover-action-height

44px

-
--van-popover-action-font-size

var(--van-font-size-md)

-
--van-popover-action-line-height

var(--van-line-height-md)

-
--van-popover-action-icon-size

20px

-
--van-popover-light-text-color

var(--van-text-color)

-
--van-popover-light-background-color

var(--van-white)

-
--van-popover-light-action-disabled-text-color

var(--van-gray-5)

-
--van-popover-dark-text-color

var(--van-white)

-
--van-popover-dark-background-color

#4a4a4a

-
--van-popover-dark-action-disabled-text-color

var(--van-gray-6)

-

常见问题

Popover 的点击事件无法正确触发?

这种情况通常是由于项目中引入了 fastclick库导致的。建议移除 fastclick,或者配置 fastclick的 ignore 规则。