ARTICLE · 1224330

【WG-SKILLS】——uniapp【弹窗容器】 base-popup:5 个方向 + 12 类实战场景,自定义弹窗组件一次成型!

发布时间：2026-10-21 21:39:27 最近访问：2026-10-21 21:39:16

大家好，我是【考拉搞AI】，一个专注于 VibeCoding 分享 & AI 工程化 的博主。

兜兜转转，今天我们继续回到uniapp-skill的迭代上来，因为从最近的实战来看，最简单的 反而是 最复杂的。

现在是全民VibeCoding的时代，有了好的点子和创意，在以前还得花钱找人做，还得各种拉扯，现在很多大佬、小白，都是全盘梭哈了，搞个Codex/Claude/Cursor，或者弄点国产能打的 DeepSeek/Glm，直接进入许愿式编程模式~

一句话甩给workbuddy：我要做一个京东那样的APP，能不能搞？不能搞我去找别人!

workbuddy:能搞，能搞！别说京东了，脸书都能搞！

等了半小时之后，几张崭新的、冒着热气的、花花绿绿的 html 跑了出来，各种商品、购物、下单，丝滑的很~

X：这也太牛了吧~

于是，兴高采烈的把localhost:3000发送给小伙伴！

可三分钟之后，似乎哪里不对劲？

我怎么下单？我怎么付款？我怎么收钱啊？

一番拉扯之后，才发现：我还需要搞接口、搞服务器、搞测试啊~~~~~

段子归段子，但两个不争的事实仍然摆在眼前：

AI 疯狂发展，逐渐降低了开发的门槛，许愿式编程或许不是假设
与此同时，粗制滥造/豆包式人格的Agent 也越来越多，做的东西良莠不齐，想真正做一个产品，绝非三言两语完事的

所以博主的建议是：

掌握更多的全栈开发知识（前端后端数据库运维安全等等），不求深入但求全面
规范开发，学会更好的给AI 制定路线，让AI 发挥100%的能量

这也是博主一直坚持做这些内容的初衷，既是对十年古法经验的总结，也是让 个人去驾驭AI，而不是彻彻底底让AI主导一切。

殊不知，你能直接让AI 做到的，意味着，其他小伙伴们也能让AI 直接做到。

对于个人开发者来说：

好的点子、创意 仍然是第一核心要素
驾驭AI 、规范开发，提升效率，知道如何更好地让AI 干活，有识别和判别的能力，将点子融进AI，掌握更多的知识、准确高效落地
当然咯，做出更优美、高大上更具设计感的页面仍然是必备，毕竟第一印象最重要！

废话不多说。

一、弹窗

职责	归属	具体内容
出现在哪	容器（`base-popup`）	顶部 / 底部 / 左 / 右 / 居中，5 个方向
怎么进来	容器	slide in/out，动画时长统一
圆角长什么样	容器	按方向智能应用，底部弹窗圆角在上面
遮罩点击能不能关	容器	`maskClosable` 一处开关
底部会不会被小白条盖住	容器	`safeArea` 自动适配
里面长什么样	内容（`base-card`）	标题、分割线、间距、按钮排布

换句话说：容器只干"外壳"这一件事，内容排版全部甩给 base-card。这就是这套技能一直在强调的容器原则——所有内容型组件都有一套统一的壳。

base-popup 直接把 base-card 装在了自己内部，你写业务的时候根本不用关心"弹窗里的卡片壳子怎么搭"。

二、圆角对齐

uni-app 里弹窗最烦的就是"方向"和"圆角"要自己算。底部弹窗圆角在上面，左侧抽屉圆角在右边，写反一个像素，四个方向就长得不一样。

base-popup 的做法是：方向决定圆角，不用自己写。

direction	弹出方式	圆角位置	典型场景
`bottom`	底部滑入	顶部左右两角	操作菜单、支付方式、加入购物车
`top`	顶部滑入	底部左右两角	消息通知、搜索面板
`left`	左侧滑入	右侧上下两角	个人中心抽屉、侧边导航
`right`	右侧滑入	左侧上下两角	筛选面板
`center`	居中缩放淡入	四角等圆	确认弹窗、危险操作二次确认

一段定位、一段动画：

/* 位置：4 个方向靠 transform 位移 */.popup-bottom { bottom: 0; left: 0; right: 0; transform: translateY(100%); }.popup-bottom.show { transform: translateY(0); }.popup-left   { top: 0; left: 0; bottom: 0; transform: translateX(-100%); }.popup-left.show { transform: translateX(0); }/* 居中：缩放 + 淡入，和滑入是两种气质 */.popup-center {top: 50%;left: 50%;transform: translate(-50%, -50%) scale(0.9);opacity: 0;transition: transform linear, opacity linear;}.popup-center.show {transform: translate(-50%, -50%) scale(1);opacity: 1;}

center 这个方向是这一版新加的。原因很实际：居中确认框是 App 里出现频率最高的弹窗，而之前的组件只有 4 个滑入方向，想做一个居中框只能自己另写一个 modal——那就等于把风格统一又打破了一次。

现在它就是 direction="center"，一行配置的事。

三、参数大全

弹窗组件最怕参数多。base-popup 一共 11 个 prop，够用且不啰嗦：

Prop	类型	默认值	说明
`show` / `v-model:show`	boolean	`false`	是否显示
`direction`	`'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'center'`	`'bottom'`	弹出方向
`radius`	string	`'16px'`	圆角（按方向智能应用）
`height`	string	`'auto'`	高度（top/bottom 生效）
`width`	string	`'280px'`	宽度（left/right/center 生效）
`padding`	`'default'` \| `'sm'` \| `'none'`	`'default'`	内边距档位
`title`	string	`''`	标题
`mask`	boolean	`true`	是否显示遮罩
`maskClosable`	boolean	`true`	点遮罩是否关闭
`duration`	number	`300`	动画时长（ms）
`safeArea`	boolean	`true`	适配底部安全区（bottom 生效）

另外 3 个 slot：

Slot	说明
默认	弹窗内容（内部 base-card 的 body 区）
`header-right`	头部右侧（比如一个"关闭"按钮）
`footer`	底部操作区（比如"取消 / 确认"）

最小可用形态，简单到不像一个组件：

<base-popup v-model:show="show" direction="bottom" title="提示">  <text>这里是弹窗内容</text></base-popup>

带底部操作区的完整形态：

<script setup lang="ts">import { ref } from 'vue'import { BasePopup } from '@/components/base'const show = ref(false)</script><template>  <base-popup    v-model:show="show"    direction="bottom"    title="选择支付方式"    padding="default"  >    <view class="pay-list">      <view class="pay-item" @click="pay = 'wechat'">        <text>微信支付</text>      </view>      <view class="pay-item" @click="pay = 'alipay'">        <text>支付宝</text>      </view>    </view>    <template #footer>      <button @click="show = false">取消</button>      <button type="primary" @click="confirmPay">确认支付</button>    </template>  </base-popup></template>

注意这里没有手写卡片外壳、没有写分割线、没有写头部底部的 padding——全是 base-card 在内部兜住了。

四、实战案例

base-popup 本身只是壳，真正决定它好不好用的是能撑起哪些业务场景。这次我们把常见 App 里的弹窗场景盘了一遍，当前是12个场景。

1. 支付方式选择（bottom）

最经典的结算页弹窗。难点不在弹窗，在状态联动：没选之前"确认支付"是禁用的，选中某一项才亮。

不可用的选项不是隐藏，而是保留位置 + 给出原因（比如"余额不足，需充值 ¥799 后使用"）。这点很关键：隐藏会让用户以为系统没这个选项，给原因才是好体验。

2. 加入购物车（bottom）—— 多维规格联动

这个场景最能体现"容器 + 业务组件"的组合思路。颜色 × 尺码两个维度，选一边要把另一边不可能的组合置灰：

关键在于：选中的颜色如果和当前尺码冲突，尺码要主动清空，而不是留一个非法组合在页面上。库存判断逻辑放在场景里，容器只管把这块内容摆出来。

3. 优惠券选择（bottom）—— 可用 / 不可用分组

券列表最容易做成一个只能选一张券的 radio 列表，但真实场景里用户需要**同时看到"还有什么券不能用"**，否则会去别处找。

分组 + 不可用项标注原因（"已过期" / "不满足使用条件"），是这个场景的标准解法。

4. 搜索面板（top）—— 历史 + 热词

搜索面板是从顶部下拉的，方向和底部弹窗相反，但容器是同一个：

历史记录要能单条删除，也能一键清空；热词是运营位。两块内容在弹窗里分区排布，靠 base-card 的分割线隔开。

5. 居中确认弹窗（center）—— 危险操作二次确认

删除账号、注销订单这类操作，必须有一个"你确定吗"的居中框。direction="center" 就是为它准备的。

这种弹窗有个硬要求：点遮罩不能关。所以 maskClosable 要显式关掉：

<base-popup  v-model:show="showConfirm"  direction="center"  width="320px"  :maskClosable="false">  <view class="dialog-body">    <text class="dialog-title">确认删除账号？</text>    <text class="dialog-desc">删除后无法恢复</text>  </view>  <template #footer>    <button @click="showConfirm = false">取消</button>    <button type="primary" @click="confirmDelete">删除</button>  </template></base-popup>

6. 右侧筛选 / 左侧抽屉（right / left）

这两个是老朋友了，但这次把它们放进了同一张"场景速查表"里，方便按场景直接查：

全部案例图：

似乎缺少时间类选择器，后续补上。

12 类场景速查表

场景	direction	依赖组件	关键结构
分享面板	`bottom`	`action-sheet`	options 数组 + 取消按钮
右侧筛选	`right`	-	筛选分组 + 重置/确定
左侧抽屉	`left`	-	导航列表
顶部通知	`top`	-	标题 + 摘要
表单筛选	`bottom`	`picker`	表单项列表 + 底部确定
列表勾选	`bottom`	`checkbox-group`	多选列表 + 批量操作
卡片选择	`bottom`	-	卡片网格 + 单选
支付方式选择	`bottom`	`radio-group`	radio 列表 + 底部合计栏
加入购物车	`bottom`	`stepper`	规格联动禁用 + 数量 stepper
优惠券选择	`bottom`	`coupon`	可用/不可用分组 + 单选
搜索面板	`top`	`search-bar`	顶部下拉 + chips
居中确认弹窗	`center`	-	标题 + 描述 + 双按钮