更新记录

1.0.7（2026-01-27）

优化

1.0.6（2025-05-27）

修改了有几率不显示的问题

1.0.5（2025-01-16）

添加布局点击事件的emit监听

平台兼容性

uni-app(3.6.15)

uni-app x(3.6.15)

qiao-dropdown 下拉菜单组件

一个轻量级、高度可定制的 uni-app 下拉菜单组件，支持自定义任意内容布局。

特性

• 支持自定义触发器和下拉内容
• 智能定位：根据触发元素位置自动判断上下/左右展示方向
• 边界检查：确保下拉内容不超出屏幕
• 点击外部区域自动关闭
• 支持禁用状态
• 支持屏幕旋转和窗口大小调整
• 兼容多端（H5、小程序、App）

安装

将 qiao-dropdown 文件夹复制到项目的 uni_modules 目录下即可。

基础用法

<template>
  <qiao-dropdown ref="dropdown">
    <!-- 触发器（默认插槽） -->
    <view class="trigger-btn">点击展开</view>

    <!-- 下拉内容 -->
    <template #content>
      <view class="menu-box">
        <view class="menu-item" v-for="item in list" :key="item.id" @click="(item)">
          {{ item.name }}
        </view>
      </view>
    </template>
  </qiao-dropdown>
</template>

<script>
export default {
  data() {
    return {
      list: [
        { id: 1, name: '编辑' },
        { id: 2, name: '复制' },
        { id: 3, name: '删除' },
      ]
    }
  },
  methods: {
    (item) {
      console.log('选中：', item)
      // 手动关闭下拉菜单
      this.$refs.dropdown.close()
    }
  }
}
</script>

<style>
.trigger-btn {
  padding: 16rpx 32rpx;
  background: #667eea;
  color: #fff;
  border-radius: 8rpx;
}

.menu-box {
  background: #fff;
  border-radius: 12rpx;
  box-shadow: 0 4rpx 20rpx rgba(0, 0, 0, 0.15);
  overflow: hidden;
}

.menu-item {
  padding: 24rpx 32rpx;
  font-size: 28rpx;
  color: #333;
  border-bottom: 1rpx solid #f0f0f0;
}

.menu-item:last-child {
  border-bottom: none;
}
</style>

Props 属性

插槽 Slots

事件 Events

方法 Methods

通过 ref 获取组件实例后可调用以下方法：

使用示例

1. 基础菜单

<qiao-dropdown ref="dropdown">
  <view class="btn">更多操作</view>
  <template #content>
    <view class="menu">
      <view class="menu-item" @click="handleEdit">编辑</view>
      <view class="menu-item" @click="handleDelete">删除</view>
    </view>
  </template>
</qiao-dropdown>

2. 禁用状态

<qiao-dropdown :disabled="true">
  <view class="btn disabled">已禁用</view>
  <template #content>
    <view>这个内容不会显示</view>
  </template>
</qiao-dropdown>

3. 监听点击事件

<qiao-dropdown @dropClick="Click">
  <view class="btn">点击触发事件</view>
  <template #content>
    <view class="menu">...</view>
  </template>
</qiao-dropdown>

<script>
export default {
  methods: {
    Click() {
      console.log('下拉菜单已展开')
    }
  }
}
</script>

4. 复杂自定义内容（筛选面板）

<qiao-dropdown ref="filterDropdown">
  <view class="btn">筛选条件</view>
  <template #content>
    <view class="filter-panel">
      <view class="filter-title">筛选条件</view>
      <view class="filter-item">
        <text>状态：</text>
        <view class="tags">
          <view 
            class="tag" 
            :class="{ active: status === item.value }"
            v-for="item in statusList" 
            :key="item.value"
            @click="status = item.value"
          >{{ item.label }}</view>
        </view>
      </view>
      <view class="filter-btns">
        <view class="btn-reset" @click="resetFilter">重置</view>
        <view class="btn-confirm" @click="confirmFilter">确认</view>
      </view>
    </view>
  </template>
</qiao-dropdown>

<script>
export default {
  methods: {
    confirmFilter() {
      // 处理筛选逻辑
      this.$refs.filterDropdown.close()
    }
  }
}
</script>

5. 多个下拉菜单（v-for 循环）

<view v-for="(item, index) in dataList" :key="item.id">
  <qiao-dropdown :ref="'dropdown' + index">
    <view class="btn">操作</view>
    <template #content>
      <view class="menu">
        <view class="menu-item" @click="handleAction(item, index)">处理</view>
      </view>
    </template>
  </qiao-dropdown>
</view>

<script>
export default {
  methods: {
    handleAction(item, index) {
      console.log('处理项：', item)
      // v-for 中的 ref 是数组，需要取第一个元素
      this.$refs['dropdown' + index][0].close()
    }
  }
}
</script>

定位逻辑说明

组件会根据触发元素在屏幕中的位置自动调整下拉内容的展示方向：

• 垂直方向：触发元素在屏幕上半部分时，下拉内容向下展开；在下半部分时，向上展开
• 水平方向：触发元素在屏幕左半部分时，下拉内容左对齐；在右半部分时，右对齐
• 边界保护：下拉内容始终保持距离屏幕边缘至少 10px 的间距

注意事项

1. 下拉内容使用 position: fixed 定位，z-index 为 10000，确保覆盖其他元素
2. 遮罩层 z-index 为 1000，点击遮罩层会关闭下拉菜单
3. 选中下拉项后需要手动调用 close() 方法关闭菜单
4. 在 v-for 循环中使用时，ref 会变成数组，需要通过 [0] 获取实例

更新日志

详见 changelog.md