uni-app x 事件通信插件重磅上线

v0.6.0 为 MINOR 版本，核心能力是新增 EventsPlugin 页面间事件通信插件：对齐 uni-app 官方 navigateTo 的 events 语义，补齐 uni-app x 缺失的"页面间定向通信"能力（打开方携带监听表、被打开页回传 / 推送）。本版本无破坏性变更。

一、背景：uni-app x 缺失的 events 能力

uni-app 官方 navigateTo 支持 events（页面间通信接口）：打开方注册监听表，被打开页向打开方回传数据。但 uni-app x 下该效果不完整：

• navigateTo
   参数表虽含 events，但 success 回调没有回传通道；
• 被打开页的接收端（getOpenerEventChannel）未收录；
• 官方 uni.$on 全局总线存在版本门槛与全局污染问题。

unix-router 以插件形式补齐这一能力，且不依赖官方 uni.$on。

二、新增：EventsPlugin 页面间事件通信

0.5.1 → 0.6.0 的定位差异

用法

import { createRouter, EventsPlugin, useOpenerEventChannel } from '@meng-xi/unix-router'const router = createRouter({ routes, plugins: [EventsPlugin] })// 打开方：注册监听表，监听被打开页回传的数据await router.push({  path: 'pages/detail/detail',  events: new Map([    ['acceptDataFromOpenedPage', (data: any) => console.log('收到回传', data)]  ])})// 被打开页：emit 回传数据 / on 接收打开方推送（onShow 内即可使用）const channel = useOpenerEventChannel() // EventChannel | nullif (channel !== null) {  channel.emit('acceptDataFromOpenedPage', { result: 'ok' })  channel.on('someEvent', (data: any) => {})}

API 一览

EventChannel API：on / once / off（按 on/once 返回的 id 移除）/ emit。

实现要点

三、时序设计：onShow 内即可回传

被打开页的 onShow 执行早于路由状态同步（onRouteSync），若仅依赖同步写入的内存 key，useOpenerEventChannel() 在 onShow 中会拿到 null、回传静默失败。

为此 useOpenerEventChannel() 采用双层读取：

1. 优先取 onRouteSync 写入的内存 key；
2. 为空时按当前页面 URL 查询串（__evt__）兜底读取（通道 key 本就在本页 URL 中，按页读取天然无时序依赖）；
3. onRouteSync
    无 __evt__ 时同步清空内存 key，避免返回上级页后残留旧通道误用。

四、升级指南

从 ≤ 0.5.1 升级无需任何改动（无破坏性变更）。按需启用事件通信：

1. 注册插件：plugins: [EventsPlugin]；
2. 打开方 push 携带 events 监听表；
3. 被打开页 useOpenerEventChannel() 回传 / 接收。

不注册插件时，携带 events 的导航抛 PLUGIN_REQUIRED 提示注册，而非静默忽略。

版本兼容性

五、相关链接

• 更新日志
• EventsPlugin 文档
• 安装文档

欢迎反馈与共建：GitHub