@lazycatcloud/vue-popup

轻量 Vue 3 Popup 组件库，提供声明式 <Popup /> 组件和命令式 popupCreate() 调用。组件行为参考 Vant Popup 的常用能力，但运行时不依赖 Vant。

安装

pnpm add @lazycatcloud/vue-popup vue

入口处引入样式：

import "@lazycatcloud/vue-popup/style.css";

声明式使用

<script setup lang="ts">
import { ref } from "vue";
import { Popup } from "@lazycatcloud/vue-popup";

const show = ref(false);
</script>

<template>
  <button type="button" @click="show = true">打开</button>

  <Popup
    v-model:show="show"
    position="bottom"
    round
    closeable
    safe-area-inset-bottom
  >
    <div style="padding: 24px">Popup 内容</div>
  </Popup>
</template>

命令式使用

适合工具函数、控制器或跨组件场景动态打开弹窗。

import { defineComponent, h } from "vue";
import { popupCreate, usePopupClose } from "@lazycatcloud/vue-popup";

const Panel = defineComponent({
  setup() {
    const { close } = usePopupClose();

    return () =>
      h("section", { style: { padding: "24px" } }, [
        h("p", "命令式弹窗内容"),
        h("button", { type: "button", onClick: () => close() }, "关闭"),
      ]);
  },
});

const popup = popupCreate(
  Panel,
  {},
  {
    position: "bottom",
    round: true,
    closeable: true,
    onOpened: () => {
      console.log("opened");
    },
  }
);

await popup.waitOpen();

关闭最上层命令式弹窗：

import { closeTopPopup } from "@lazycatcloud/vue-popup";

closeTopPopup();

Popup Props

常用 props：

• show: 是否显示，支持 v-model:show
• position: top | bottom | left | right | center
• overlay: 是否显示遮罩，默认 true
• closeOnClickOverlay: 点击遮罩关闭，默认 true
• closeOnPopstate: 浏览器返回时关闭
• lockScroll: 锁定 body 滚动，默认 true
• lazyRender: 懒渲染，默认 true
• round: 圆角
• closeable: 显示关闭按钮
• duration: 动画时长，单位秒
• teleport: Vue Teleport 目标
• beforeClose: 关闭前拦截，返回 true 才继续关闭
• overlayStyle / overlayClass: 遮罩样式
• safeAreaInsetTop / safeAreaInsetBottom: 安全区 padding
• transition / transitionAppear: 自定义转场名和初始动画

事件：

• open
• close
• opened
• closed
• update:show
• clickOverlay
• clickCloseIcon
• keydown

命令式 API

popupCreate(component, componentProps?, popupProps?)

返回：

{
  closed: Ref<boolean>;
  close: (needAnimation?: boolean) => Promise<void>;
  waitOpen: () => Promise<void>;
}

默认行为：

• 默认 show = true
• 默认 round = true
• 默认 closeOnPopstate = true
• 默认 transitionAppear = true
• position === "bottom" 时默认启用 safeAreaInsetBottom

样式变量

可以通过 CSS 变量覆盖默认外观：

:root {
  --lzc-popup-background: #fff;
  --lzc-popup-round-radius: 16px;
  --lzc-overlay-background: rgb(0 0 0 / 55%);
  --lzc-popup-close-icon-color: #667085;
}

Demo

pnpm install
pnpm run dev

默认地址：

http://localhost:2390/

开发验证

pnpm run test
pnpm run build