更新记录

1.0.0（2026-07-04） 下载此版本

第一版，鸿蒙原生弹框

平台兼容性

uni-app(3.7.13)

uni-app x(3.7.13)

其他

harmony-popup

HarmonyOS 原生弹框插件，基于 uni-app x UTS 开发。提供 Toast 提示、模态对话框（Alert / Confirm / Prompt）、操作菜单、自定义弹出层，支持 5 个方向弹出、动画效果和 Slot 自定义内容。

平台支持

安装

将 harmony-popup 目录放入项目的 uni_modules/ 目录下即可。

快速上手

引入组件

使用 showModal({ editable: true }) 或 showPopup() 前，必须在页面中引入 <harmony-popup /> 组件：

<template>
  <view>
    <!-- 页面内容 -->

    <!-- 函数模式（必须引入，用于 editable 和 showPopup） -->
    <harmony-popup />
  </view>
</template>

<script>
import { showToast, showModal, showActionSheet, showPopup, closePopup } from '@/uni_modules/harmony-popup'
import HarmonyPopup from '@/uni_modules/harmony-popup/components/harmony-popup/harmony-popup.uvue'

export default {
  components: { HarmonyPopup }
}
</script>

基本用法

// Toast 提示
showToast({ message: '操作成功' })

// Alert 提示框
showModal({
  title: '提示',
  content: '操作完成',
  showCancel: false
})

// Confirm 确认框
showModal({
  title: '确认',
  content: '确定要删除吗？',
  success(res) {
    if (res.confirm) { /* 点击了确定 */ }
    if (res.cancel) { /* 点击了取消 */ }
  }
})

// Prompt 输入框（需要 <harmony-popup /> 组件）
showModal({
  title: '请输入',
  editable: true,
  placeholderText: '请输入姓名',
  success(res) {
    console.log('输入内容：', res.content)
  }
})

// ActionSheet 操作菜单
showActionSheet({
  itemList: ['拍照', '相册', '文件'],
  success(res) {
    console.log('选中下标：', res.tapIndex)
  }
})

// 自定义 Popup（需要 <harmony-popup /> 组件）
showPopup({
  position: 'bottom',
  title: '选择操作',
  content: '请选择一个操作',
  buttons: [
    { text: '取消', type: 'default' },
    { text: '确定', type: 'primary' }
  ],
  showClose: true,
  onButtonClick(index) { console.log('点击按钮:', index) },
  onClose() { console.log('关闭') }
})

// 关闭自定义 Popup
closePopup()

API 文档

showToast(options)

显示 Toast 提示（使用原生 promptAction，无需组件）。

showModal(options)

显示模态对话框。非 editable 模式使用原生 promptAction；editable 模式需要 <harmony-popup /> 组件。

success 回调参数 ShowModalResult：

showActionSheet(options)

显示操作菜单（使用原生 promptAction，无需组件）。

success 回调参数 ShowActionSheetResult：

showPopup(options)

显示自定义弹出层。需要页面中引入 <harmony-popup /> 组件。

PopupPosition 类型： 'center' | 'top' | 'bottom' | 'left' | 'right'

PopupButton 类型：

closePopup()

关闭当前显示的自定义弹出层（无参数，无返回值）。

动画效果

默认启用动画，可通过 animation: false 关闭。

动画时长通过 duration 参数控制，默认 300ms。

Slot 模式

除函数 API 外，还可以使用 Slot 模式自定义弹窗内容，直接在弹窗中嵌入 Vue 组件。

使用方式

<template>
  <view>
    <view class="btn" @click="popupVisible = true">
      <text>打开 Slot 弹窗</text>
    </view>

    <harmony-popup
      :visible="popupVisible"
      position="center"
      :show-close="true"
      :animation="true"
      :duration="300"
      :auto-cancel="true"
      corner-radius="16"
      background-color="#FFFFFF"
      @close="handleClose"
      @update:visible="val => popupVisible = val"
    >
      <!-- 自定义标题 -->
      <view slot="title">
        <text style="font-size: 36rpx; font-weight: bold; color: #e74c3c;">自定义标题</text>
      </view>

      <!-- 自定义内容（默认 slot） -->
      <view style="padding: 20rpx 0;">
        <text style="font-size: 28rpx; color: #666;">自定义内容区域</text>
        <input
          style="height: 80rpx; background-color: #f5f5f5; border-radius: 12rpx; padding: 0 20rpx;"
          placeholder="请输入"
          v-model="inputValue"
        />
      </view>

      <!-- 自定义底部 -->
      <view slot="footer" style="flex-direction: row; justify-content: center;">
        <view class="btn-cancel" @click="popupVisible = false">
          <text>取消</text>
        </view>
        <view class="btn-confirm" @click="handleConfirm">
          <text>确定</text>
        </view>
      </view>
    </harmony-popup>
  </view>
</template>

<script>
import HarmonyPopup from '@/uni_modules/harmony-popup/components/harmony-popup/harmony-popup.uvue'

export default {
  components: { HarmonyPopup },
  data() {
    return {
      popupVisible: false,
      inputValue: ''
    }
  },
  methods: {
    handleClose() { console.log('关闭') },
    handleConfirm() {
      console.log('输入：', this.inputValue)
      this.popupVisible = false
    }
  }
}
</script>

Props

Events

Slots

方法（通过 ref 调用）

注意事项

1. showToast()、showModal({ editable: false })、showActionSheet() 使用 HarmonyOS 原生 API，不需要引入组件。
2. showModal({ editable: true }) 和 showPopup() 必须在页面中引入 <harmony-popup /> 组件，否则会返回错误。
3. 左/右侧弹窗宽度为 500rpx，上/下侧弹窗宽度为全屏（750rpx），居中弹窗宽度为 600rpx。
4. Slot 模式和函数模式可以在同一页面共存，使用不同的 <harmony-popup /> 实例。
5. 本插件仅支持 HarmonyOS 平台，其他平台调用会返回错误。
6. 弹窗内容区最大高度为 85vh，超出部分可滚动。