更新记录
1.0.0(2026-11-18) 下载此版本
插件
平台兼容性
hjy-popups 使用说明
版本:v1.0.0 | 类型:uni_modules 组件(component-vue) 简介:悬浮菜单 / 二级菜单 / 气泡菜单 / 扩展菜单,可在任意坐标点弹出带小三角指向的浮层。
一、组件介绍
hjy-popups 是一个基于 uni-app 的悬浮气泡菜单组件。它通过 x / y 坐标定位一个锚点,在锚点附近弹出一个带小三角指向的浮层菜单,支持亮色 / 暗色主题、竖向 / 横向排列、自动避让屏幕边缘,并可通过插槽自定义内容。
典型使用场景:右上角「+」号扩展菜单、长按弹出操作菜单、悬浮按钮展开二级菜单等。
兼容性
| 平台 | 支持情况 |
|---|---|
| Vue2 | ✅ 支持 |
| Vue3 | ⚠️ 未明确验证(组件使用 v-model 的 input 事件,Vue3 下需自行适配) |
| App(vue) | ✅ 支持 |
| H5(移动端 / PC) | ✅ 支持 |
| 微信小程序 | ✅ 支持 |
| 其他小程序(支付宝 / 百度 / 字节 / QQ 等) | ⚠️ 未明确验证 |
| 快应用 | ⚠️ 未明确验证 |
运行环境要求:HBuilderX
^3.1.0,组件不采集任何数据、无额外权限。
二、安装
组件已以 uni_modules 形式提供,目录结构如下:
your-project/
└── uni_modules/
└── hjy-popups/
├── package.json
├── changelog.md
└── components/
└── hjy-popups/
└── hjy-popups.vue
将 uni_modules/hjy-popups 整个目录复制到你自己项目的 uni_modules 下即可。uni_modules easycom 机制会自动注册组件,无需在页面里手动 import 或 components 声明,模板中可直接使用 <hjy-popups>。
三、快速开始
<template>
<view>
<!-- 右上角弹出菜单 -->
<hjy-popups
v-model="show"
:popData="menu"
:x="140"
:y="0"
theme="dark"
placement="top-end"
dynamic
@tapPopup="onTapItem"
/>
<button @click="show = !show">打开菜单</button>
</view>
</template>
<script>
export default {
data() {
return {
show: false,
menu: [
{ title: '创建群聊', icon: '/static/group.png', disabled: true },
{ title: '添加好友', icon: '/static/friend.png' },
{ title: '***', icon: '/static/scan.png' },
{ title: '收付款', icon: '/static/pay.png' }
]
}
},
methods: {
onTapItem(item) {
uni.showToast({ title: item.title, icon: 'none' })
}
}
}
</script>
四、API
4.1 Props
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value(v-model) |
Boolean |
false |
控制浮层显示 / 隐藏,配合 v-model 使用 |
popData |
Array |
[] |
菜单项数据,结构见下表 |
x |
Number |
0 |
锚点横坐标(单位见下文「坐标单位」) |
y |
Number |
0 |
锚点纵坐标(单位见下文「坐标单位」) |
placement |
String |
'default' |
弹出方向:default(自动判断)、top-start、top-end、bottom-start、bottom-end |
direction |
String |
'column' |
菜单项排列方向:column(竖向)、row(横向) |
theme |
String |
'light' |
主题:light(白底)、dark(深灰底 #4C4C4C) |
dynamic |
Boolean |
false |
是否动态避让屏幕边缘,开启后浮层不会贴边溢出 |
gap |
Number |
20 |
开启 dynamic 时,浮层与屏幕边缘的最小间距 |
maskBg |
String |
'rgba(0,0,0,0)' |
遮罩层背景色,默认透明(点击遮罩可关闭) |
triangle |
Boolean |
true |
是否显示指向锚点的小三角 |
popData 菜单项结构
| 字段 | 类型 | 说明 |
|---|---|---|
title |
String |
菜单项文字 |
icon |
String |
菜单图标路径(可选),图标尺寸 40rpx |
disabled |
Boolean |
是否禁用,禁用项变灰且点击不触发事件(可选) |
4.2 Events
| 事件名 | 回调参数 | 说明 |
|---|---|---|
input |
(value: Boolean) |
遮罩点击或菜单点击时触发,用于 v-model 双向绑定 |
tapPopup |
(item: Object) |
点击某个可用菜单项时触发,参数为该项数据;点击后浮层自动关闭 |
说明:
disabled: true的菜单项不会触发tapPopup。
4.3 Slots
| 插槽名 | 说明 |
|---|---|
| 默认插槽 | 浮层内部除 popData 菜单项之外的自定义内容,可放置任意 view / 按钮等 |
五、坐标单位与定位逻辑
- 默认模式(
dynamic=false):x / y传入的是设计稿尺寸(以 375 屏宽为基准的 rpx 换算值),组件内部按屏幕宽度 / 375自动缩放。 - 动态模式(
dynamic=true):x / y按实际像素使用,组件会根据gap自动钳制,避免浮层超出屏幕边缘。 - H5 平台:组件内部会自动叠加状态栏高度,开发者无需手动处理。
placement 方向示意
| 取值 | 浮层相对锚点位置 |
|---|---|
default |
自动根据锚点在屏幕中的象限选择方向 |
top-start |
在锚点上方,左对齐 |
top-end |
在锚点上方,右对齐 |
bottom-start |
在锚点下方,左对齐 |
bottom-end |
在锚点下方,右对齐 |
六、常见用法
1. 右上角导航栏「+」菜单
在页面生命周期里监听原生导航栏按钮点击:
<hjy-popups v-model="show" :popData="menu" :x="140" :y="0"
theme="dark" placement="top-end" dynamic @tapPopup="onTapItem" />
onNavigationBarButtonTap(e) {
if (e.index === 0) this.show = !this.show
}
2. 横向排列的工具栏
<hjy-popups v-model="show" :popData="tools" :x="100" :y="400"
direction="row" theme="light" placement="top-start" />
3. 自定义内容(插槽)
<hjy-popups v-model="show" :x="200" :y="300" placement="bottom-start">
<view class="custom-box">
<text>自定义内容区</text>
<button>确定</button>
</view>
</hjy-popups>
七、注意事项
- 组件通过
position: fixed全屏遮罩定位,z-index: 9999,请避免页面内出现更高层级元素导致被遮挡。 - 点击遮罩会触发
input事件关闭浮层;如需禁止点击遮罩关闭,可在外部拦截v-model赋值。 - 组件基于 Vue2 语法(
v-model默认监听input事件)。在 Vue3 项目中使用时,建议改用:model-value+@update:model-value,或自行包一层兼容。 dynamic开启后浮层会自动靠边钳制,配合较小的gap(如 10~20)效果更佳。- 图标请放在项目
static目录下,并使用绝对路径(如/static/xxx.png)引用。
八、更新日志
1.0.0(2023-11-08)
- 首次提交插件,提供悬浮 / 气泡 / 二级菜单能力。
(注:部分内容由豆包 AI 生成)

收藏人数:
下载插件并导入HBuilderX
下载插件ZIP
赞赏(0)
下载 2
赞赏 0
下载 12775974
赞赏 1960
赞赏
京公网安备:11010802035340号