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 的定位差异

版本	定位
≤ 0.5.1	core + ParamsPlugin / InterceptorPlugin / AnimationPlugin
0.6.0	+ EventsPlugin（页面间定向事件通信）

用法

ts 复制代码

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 | null
if (channel !== null) {
  channel.emit('acceptDataFromOpenedPage', { result: 'ok' })
  channel.on('someEvent', (data: any) => {})
}

API 一览

导出	说明
`EventsPlugin`	插件本体（注册后 `events` 生效；未注册携带 `events` 抛 `PLUGIN_REQUIRED`）
`useOpenerEventChannel()`	被打开页获取通道（`EventChannel` / `null`）
`eventBus`	自研全局事件总线（`$on` / `$once` / `$off` / `$emit`，按 id 移除监听）
`EventsMap`	事件监听表类型（`Map<事件名, 回调>`）

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

实现要点

环节	实现
通道创建	`onAfterResolve`：检测 `events` 建通道，把监听表注册进通道
跨页桥接	`onPrepareNavigation`：通道 key 注入 URL 查询串（内部 `__evt__`），状态同步时剔除，不暴露给用户
被打开页取通道	`onRouteSync` 写内存 key；并保证不依赖同步时机
资源清理	`onNavigationAbort`：移除本次通道
未注册防护	`performNavigation` 检测 `events` 未注册 → `PLUGIN_REQUIRED` 明确引导

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

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

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

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

四、升级指南

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

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

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

版本兼容性

功能	≤0.5.1	0.6.0
页面间事件通信（events 回传 / 推送）	❌	✅ EventsPlugin
`useOpenerEventChannel()` / `eventBus`	❌	✅
`RawLocation.events` 可选字段	❌	✅
未注册插件携带 `events`	静默	✅ `PLUGIN_REQUIRED` 明确引导

五、相关链接

欢迎反馈与共建：GitHub