Popover 气泡弹出框 ​

介绍 ​

弹出式的气泡菜单。

引入 ​

通过以下方式来引入组件。

js
import { createApp } from 'vue';
import { Popover } from '@szhn/dh-design-mobile';

const app = createApp();
app.use(Popover);

代码演示 ​

基础用法 ​

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

html
<van-popover v-model:show="showPopover" :actions="actions" @select="onSelect">
  <template #reference>
    <van-button type="primary">浅色风格</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';
import { showToast } from '@szhn/dh-design-mobile';

export default {
  setup() {
    const showPopover = ref(false);

    // 通过 actions 属性来定义菜单选项
    const actions = [
      { text: '选项一' },
      { text: '选项二' },
      { text: '选项三' },
    ];
    const onSelect = (action) => showToast(action.text);

    return {
      actions,
      onSelect,
      showPopover,
    };
  },
};

深色风格 ​

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

html
<van-popover v-model:show="showPopover" theme="dark" :actions="actions">
  <template #reference>
    <van-button type="primary">深色风格</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: '选项一' },
      { text: '选项二' },
      { text: '选项三' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

水平排列 ​

将 actions-direction 属性设置为 horizontal 后，菜单选项会变成水平排列。

html
<van-popover
  v-model:show="showPopover"
  :actions="actions"
  actions-direction="horizontal"
>
  <template #reference>
    <van-button type="primary">水平排列</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: '选项一' },
      { text: '选项二' },
      { text: '选项三' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

弹出位置 ​

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

html
<van-popover placement="top" />

placement 支持以下值：

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

展示图标 ​

在 actions 数组中，可以通过 icon 字段来定义选项的图标，支持传入图标名称或图片链接，等同于 Icon 组件的 name 属性。

html
<van-popover v-model:show="showPopover" :actions="actions">
  <template #reference>
    <van-button type="primary">展示图标</van-button>
  </template>
</van-popover>
js
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 字段来禁用某个选项。

html
<van-popover v-model:show="showPopover" :actions="actions">
  <template #reference>
    <van-button type="primary">禁用选项</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: '选项一', disabled: true },
      { text: '选项二', disabled: true },
      { text: '选项三' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

自定义内容 ​

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

html
<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>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    return { showPopover };
  },
};

非受控模式 ​

你可以把 Popover 当做受控组件或非受控组件使用：

  • 当绑定 v-model:show 时，Popover 为受控组件，此时组件的显示完全由 v-model:show 的值决定。
  • 当未绑定 v-model:show 时，Popover 为非受控组件，此时你可以通过 show 属性传入一个默认值，组件值的显示由组件自身控制。
html
<van-popover :actions="actions" placement="top-start" @select="onSelect">
  <template #reference>
    <van-button type="primary">非受控模式</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';
import { showToast } from '@szhn/dh-design-mobile';

export default {
  setup() {
    const actions = [
      { text: '选项一' },
      { text: '选项二' },
      { text: '选项三' },
    ];
    const onSelect = (action) => showToast(action.text);
    return {
      actions,
      onSelect,
    };
  },
};

API ​

Props ​

参数说明类型默认值
v-model:show是否展示气泡弹出层booleanfalse
actions选项列表PopoverAction[][]
actions-direction v4.4.1选项列表的排列方向，可选值为 horizontalPopoverActionsDirectionvertical
placement弹出位置PopoverPlacementbottom
theme主题风格，可选值为 darkPopoverThemelight
trigger触发方式，可选值为 manualPopoverTriggerclick
duration动画时长，单位秒，设置为 0 可以禁用动画number | string0.3
offset出现位置的偏移量[number, number][0, 8]
overlay是否显示遮罩层booleanfalse
overlay-class自定义遮罩层类名string | Array | object-
overlay-style自定义遮罩层样式object-
show-arrow是否展示小箭头booleantrue
close-on-click-action是否在点击选项后关闭booleantrue
close-on-click-outside是否在点击外部元素后关闭菜单booleantrue
close-on-click-overlay是否在点击遮罩层后关闭菜单booleantrue
teleport指定挂载的节点，等同于 Teleport 组件的 to 属性string | Elementbody
icon-prefix图标类名前缀，等同于 Icon 组件的 class-prefix 属性stringvan-icon

PopoverAction 数据结构 ​

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

键名说明类型
text选项文字string
icon文字左侧的图标，支持传入图标名称或图片链接，等同于 Icon 组件的 name 属性string
color选项文字颜色string
disabled是否为禁用状态boolean
className为对应选项添加额外的类名string | Array | object

Events ​

事件名说明回调参数
select点击选项时触发action: PopoverAction, index: number
open打开菜单时触发-
close关闭菜单时触发-
opened打开菜单且动画结束后触发-
closed关闭菜单且动画结束后触发-
click-overlay点击遮罩层时触发event: MouseEvent

Slots ​

名称说明参数
default自定义菜单内容-
reference触发 Popover 显示的元素内容-
action自定义选项内容{ action: PopoverAction, index: number }

类型定义 ​

组件导出以下类型定义：

ts
import type {
  PopoverProps,
  PopoverTheme,
  PopoverAction,
  PopoverActionsDirection,
  PopoverTrigger,
  PopoverPlacement,
} from '@szhn/dh-design-mobile';

主题定制 ​

样式变量 ​

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

名称默认值描述
--van-popover-arrow-size6px气泡箭头大小
--van-popover-radiusvar(--van-radius-lg)气泡圆角大小
--van-popover-action-width128px操作项宽度
--van-popover-action-height44px操作项高度
--van-popover-action-font-sizevar(--van-font-size-md)操作项字体大小
--van-popover-action-line-heightvar(--van-line-height-md)操作项行高
--van-popover-action-icon-size20px操作项图标大小
--van-popover-horizontal-action-height34px水平操作项高度
--van-popover-horizontal-action-icon-size16px水平操作项图标大小
--van-popover-light-text-colorvar(--van-text-color)浅色主题文字颜色
--van-popover-light-backgroundvar(--van-background-2)浅色主题背景色
--van-popover-light-action-disabled-text-colorvar(--van-text-color-3)浅色主题禁用操作项文字颜色
--van-popover-dark-text-colorvar(--van-white)深色主题文字颜色
--van-popover-dark-background#4a4a4a深色主题背景色
--van-popover-dark-action-disabled-text-colorvar(--van-text-color-2)深色主题禁用操作项文字颜色

常见问题 ​

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

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