更新记录

1.0.0（2026-07-08）

• 首个版本，提供 Android 原生全局弹框容器。
• 增加 iOS 原生全局弹框容器实现。
• 支持 view、text、image 三类白名单节点。
• 支持 show、close、update 与受控点击事件回传。

平台兼容性

uni-app(5.14)

其他

tsw-global-modal

tsw-global-modal 是一个基于 UTS 的全局弹框插件，支持 Android 和 iOS。
它的特点是：弹框由原生层承载，不依赖当前页面组件树，可以在页面里直接通过 API 打开、更新和关闭。

插件能做什么

• 提供全局弹框显示能力
• 支持 show、update、close、isShowing
• 支持用字符串布局描述弹框内容
• 支持 view、text、image 三种标签
• 支持通过 data-action 回传按钮点击结果

适合这些场景：

• 全局活动弹窗
• 升级提醒
• 营销引导弹框
• 跨页面通用弹框

支持平台

建议环境：

• HBuilderX 5.07+
• uni-app / uni-app x

推荐使用方式

这个插件最推荐的用法，就是和你首页现在的写法一样：
在 main.js 挂载全局 $modal，页面里直接通过 this.$modal 调用。

这样做的好处：

• 页面里不用重复 import
• 可以统一管理模板
• 可以统一处理按钮回调
• 页面调用很简单，直接传 type 就能打开对应模板

接入步骤

1. 在 utils/modal.js 封装一层

项目里推荐保留一个 utils/modal.js，负责这几件事：

• 引入底层插件 @/uni_modules/tsw-global-modal
• 维护模板 TEMPLATES
• 统一 show、update、close、isShowing
• 统一处理 data-action 点击结果

你现在项目里的用法就是这一套。

2. 在 main.js 挂到全局

import App from './App'
import modal from './utils/modal'

// Vue2
Vue.prototype.$modal = modal
modal.init()

// Vue3
app.config.globalProperties.$modal = modal
modal.init()

这样之后，任意页面里都可以直接用：

this.$modal.show(...)
this.$modal.close(...)
this.$modal.isShowing()

3. 在页面中直接调用

这就是最推荐的页面写法：

<script>
export default {
  methods: {
    openModal(type) {
      this.$modal.show({
        type,
        success: (res) => {
          console.log('action:', res.action)

          if (res.action === 'confirm') {
            console.log('点击了确定')
          }

          if (res.action === 'cancel') {
            console.log('点击了取消')
          }

          if (res.action === 'ok') {
            console.log('点击了知道了')
          }
        }
      })
    },
    closeModal() {
      this.$modal.close('manual-close')
    },
    checkStatus() {
      const showing = this.$modal.isShowing()
      console.log('当前是否显示:', showing)
    }
  }
}
</script>

最常用的实际用法

打开模板弹框

this.$modal.show({
  type: 1,
  success: (res) => {
    console.log(res.action)
  }
})

关闭弹框

this.$modal.close('manual-close')

判断弹框是否正在显示

const showing = this.$modal.isShowing()

更新当前弹框内容

this.$modal.update({
  layout: '<view><text style="font-size: 30rpx; color: #ef4444;">内容已更新</text></view>'
})

API 说明

show(options)

显示一个弹框。
如果你已经在 utils/modal.js 里配置了模板，平时最常用的是传 type。

常用参数：

示例：

this.$modal.show({
  type: 1,
  success: (res) => {
    console.log(res.action)
  }
})

update(options)

在弹框已经显示时更新内容。

this.$modal.update({
  layout: '<view><text style="color:#ef4444;">内容已更新</text></view>'
})

close(action)

关闭当前弹框。

this.$modal.close('manual-close')

isShowing()

判断当前是否有弹框正在显示。

const showing = this.$modal.isShowing()

按钮点击怎么处理

插件本身不限制你用什么按钮组件，它只识别节点上的 data-action。

例如：

<view data-action="confirm" style="background: #2563eb; padding: 18rpx 36rpx; border-radius: 36rpx;">
  <text style="font-size: 26rpx; color: #ffffff;">确定</text>
</view>

当用户点击后，会回传这个 action 值，比如：

• confirm
• cancel
• ok
• details

你现在项目里的推荐处理方式，就是在 show 的 success 回调里判断：

this.$modal.show({
  type: 2,
  success: (res) => {
    if (res.action === 'later') {
      console.log('点击了稍后')
    }

    if (res.action === 'details') {
      console.log('点击了查看详情')
    }

    if (res.action === 'ignore') {
      console.log('点击了忽略')
    }
  }
})

layout 支持说明

支持的标签

• view
• text
• image

常用属性

• style
• id
• data-action
• src
• mode

常用样式

支持常见的基础样式，例如：

• display
• flex-direction
• justify-content
• align-items
• width
• height
• padding
• margin
• font-size
• font-weight
• line-height
• text-align
• color
• background
• background-color
• background-image
• border-radius
• position
• top/right/bottom/left

模板模式说明

如果你按当前项目推荐方式接入，日常使用并不需要每次手写 layout。
更推荐做法是：

• 在 utils/modal.js 里统一维护模板
• 页面里只传 type
• 业务逻辑只处理 success 回调

例如：

this.$modal.show({ type: 1 })
this.$modal.show({ type: 2 })
this.$modal.show({ type: 3 })
this.$modal.show({ type: 4 })

这样页面层会非常干净，也更方便后续统一改样式。

注意事项

• 这不是 WebView 渲染，不能当成完整 HTML/CSS 使用
• 建议控制布局层级，不要写过深的嵌套
• 输入框、复杂表单、复杂动画不属于当前插件能力范围
• data-action 建议直接写在可点击节点上
• 图片建议优先使用可访问的网络地址
• 如果你已经有统一模板，推荐页面层只传 type，不要在多个页面重复写 layout

总结

如果你想要的用法是：

• 在 main.js 全局挂载
• 页面里直接 this.$modal.show({ type, success })
• 模板统一放在 utils/modal.js
• 按钮点击后通过 action 回调处理

那当前首页这种接入方式，就是这个插件最推荐、最好用的使用方式。