uni.$on(eventName, callback) @$on

展示全部

# uni.$on(eventName, callback)

监听自定义事件。事件可以由 uni.$emit 触发。回调函数会接收 uni.$emit 传递的参数。 4.31+ 开始支持返回事件监听器 id, 用于 off 事件监听器。 GitCode GitHub

# $on 兼容性

Web	微信小程序	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	3.91	4.11	4.31	4.61

# 参数

名称	类型	必填	默认值	兼容性	描述
eventName	string	是	-	-	事件名称
callback	() => void	是	-	-	事件回调

# 返回值

类型
number

# 参见

相关 Bug

# uni.$off(eventName, callback)

移除自定义事件监听器。如果提供了事件名和回调，则只移除这个回调的监听器。 4.13+ 开始支持第二个参数为可选，如果仅提供事件名，则移除该事件的所有监听器。 4.31+ 开始第二个参数的类型由 `Function | null` 调整为 `any | null`, 支持传入 `uni.$on`、`uni.$once` 返回的事件监听器 id, 移除指定事件监听器。 GitCode GitHub

# $off 兼容性

Web	微信小程序	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	3.91	4.11	4.31	4.61

# 参数

名称	类型	必填	默认值	兼容性	描述
eventName	string	是	-	-	事件名称
callback	any	否	-	-	要移除的事件回调或事件监听器 id

# 参见

相关 Bug

# uni.$once(eventName, callback)

监听一个自定义事件。事件只触发一次，在第一次触发之后移除事件监听器。 4.31+ 开始支持返回事件监听器 id, 用于 off 事件监听器。 GitCode GitHub

# $once 兼容性

Web	微信小程序	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	3.91	4.11	4.31	4.61

# 参数

名称	类型	必填	默认值	兼容性	描述
eventName	string	是	-	-	事件名称
callback	() => void	是	-	-	事件回调

# 返回值

类型
number

# 参见

相关 Bug

# uni.$emit(eventName, args?)

触发自定义事件，附加的参数会传递给事件监听器。在iOS平台UTS环境下或者UTS和JS通信时参数仅支持基础类型、string、Array、UTSJSONObject,其中Array，UTSJSONObject也仅支持包含上述类型,on和emit类型需匹配否则会产生异常 GitCode GitHub

# $emit 兼容性

Web	微信小程序	Android	Android uni-app x UTS 插件	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	3.91	4.11	4.31	4.61

# 参数

名称	类型	必填	默认值	兼容性	描述
eventName	string	是	-	-	事件名称
args	Array<any>	否	-	-	触发事件时传递的参数

WARNING

参数 args 为对象字面量时，4.25 前需要通过 as 明确类型，例如：

uni.$emit('fn', {"a": 1} as UTSJSONObject)

4.25+ 编译器会自动将对象字面量推断为 UTSJSONObject 类型，不再需要通过 as 明确类型。如果需要传递其他自定义类型的对象字面量，仍需要通过 as 明确类型。

# 参见

相关 Bug

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
    <!-- #endif -->
    <view class="box">
      <button class="uni-btn" @click="on">开始监听</button>
      <button class="uni-btn" @click="once">监听一次</button>
      <button class="uni-btn" @click="off">取消监听</button>
      <!-- <button @click="offAll">取消全部监听</button> -->
      <button class="uni-btn" @click="emit">触发监听</button>
      <button class="uni-btn" @click="clear">清空消息</button>
      <view>
        <view class="uni-btn">收到的消息：</view>
        <view class="uni-btn">
          <view v-for="(item, index) in log" :key="index">{{ item }}</view>
        </view>
        <button class="uni-btn" @click="onObj">开始监听 obj 参数</button>
        <button class="uni-btn" @click="emitWithObj">触发监听 obj 参数</button>
        <view class='uni-btn'>
          <text>接收到的 obj 参数：</text>
          <text>{{ JSON.stringify(objArg) }}</text>
        </view>
        <button class='uni-btn' @click="testReturnId">测试返回 id</button>
        <button class='uni-btn' @click="testEmitNoArgs">测试 $emit 无参</button>
        <button class='uni-btn' @click="testEmitMultipleArgs">测试 $emit 多个参数</button>
      </view>
    </view>
    <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>



<style>
.box {
  padding: 10px;
}
</style>