更新记录

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>

七、注意事项

  1. 组件通过 position: fixed 全屏遮罩定位,z-index: 9999,请避免页面内出现更高层级元素导致被遮挡。
  2. 点击遮罩会触发 input 事件关闭浮层;如需禁止点击遮罩关闭,可在外部拦截 v-model 赋值。
  3. 组件基于 Vue2 语法(v-model 默认监听 input 事件)。在 Vue3 项目中使用时,建议改用 :model-value + @update:model-value,或自行包一层兼容。
  4. dynamic 开启后浮层会自动靠边钳制,配合较小的 gap(如 10~20)效果更佳。
  5. 图标请放在项目 static 目录下,并使用绝对路径(如 /static/xxx.png)引用。

八、更新日志

1.0.0(2023-11-08)

  • 首次提交插件,提供悬浮 / 气泡 / 二级菜单能力。

(注:部分内容由豆包 AI 生成)

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议