@yagolive/event-kit

@yagolive/event-kit

YAGO App Action 创建与通信工具库，支持浏览器、React、Vue 等多种环境。

架构

┌─────────────────────────────────────────────────────┐
│                   应用层 (Frameworks)                │
├───────────────────┬───────────────────┬─────────────┤
│  React            │  Vue 3            │  原生 JS     │
├───────────────────┴───────────────────┴─────────────┤
│                   桥接层 (Bridge)                     │
│               ActionBridge (注入适配器)               │
├─────────────────────────────────────────────────────┤
│                   适配器层 (Adapters)                 │
│        RNWebViewAdapter  │  MockAdapter              │
├─────────────────────────────────────────────────────┤
│                   核心层 (Core)                       │
│   ActionCreator  │  ActionType  │  ActionData       │
└─────────────────────────────────────────────────────┘

更新日志

详细更新日志请查看 CHANGELOG。

安装

npm install @yagolive/event-kit

AI 技能（Agent Skill）

包内自带一份自包含的 H5 接入规范技能，供 AI 编码助手（Claude Code、Codex 等支持 SKILL.md 约定的宿主）在开发 H5 活动页时直接使用。

加载方式（任选其一，把技能目录复制到宿主的技能目录）：

# 全局：对当前用户的所有项目生效
mkdir -p ~/.claude/skills ~/.codex/skills
cp -r node_modules/@yagolive/event-kit/skills/event-kit-h5-integration ~/.claude/skills/
cp -r node_modules/@yagolive/event-kit/skills/event-kit-h5-integration ~/.codex/skills/

# 项目级：随项目提交，团队共享
mkdir -p .claude/skills .agents/skills
cp -r node_modules/@yagolive/event-kit/skills/event-kit-h5-integration .claude/skills/
cp -r node_modules/@yagolive/event-kit/skills/event-kit-h5-integration .agents/skills/

Windows 下将 cp -r 换成 Copy-Item -Recurse。加载后向 AI 提出「开发 H5 活动页」「H5 接入 event-kit」类需求会自动触发该技能。

维护约束：Action 签名或通信协议变化时，需同步更新包内 skills/event-kit-h5-integration/SKILL.md 的内嵌定义与示例。

快速开始

浏览器（Script 标签）

<!-- 引入完整功能包 -->
<script src="https://unpkg.com/@yagolive/event-kit/dist/js/action_bridge.umd.js"></script>
<script>
  var { ActionBridge } = window.__action_bridge__;

  // 自动检测环境并创建桥接实例
  var bridge = ActionBridge.createDefault();

  // 发送导航 Action
  bridge
    .navigate('profile', { userId: 123 })
    .then(function (result) {
      console.log('导航成功', result);
    })
    .catch(function (error) {
      console.error('导航失败', error);
    });
</script>

<!-- 仅引入核心包（不需要通信功能时） -->
<script src="https://unpkg.com/@yagolive/event-kit/dist/js/action_creator.umd.js"></script>
<script>
  var { ActionCreator } = window.__action_creator__;

  var action = ActionCreator.createNavigateAction('home');
  console.log(action.toJson());
  // {"type":"navigate","data":{"screen":"home"}}
</script>

也可使用 jsdelivr：

<script src="https://cdn.jsdelivr.net/npm/@yagolive/event-kit/dist/js/action_bridge.umd.js"></script>

React

import {
  ActionBridgeProvider,
  useActionBridge,
} from '@yagolive/event-kit/react';
import { RNWebViewAdapter } from '@yagolive/event-kit/adapters';

// 1. 在根组件配置 Provider
function App() {
  return (
    <ActionBridgeProvider adapter={new RNWebViewAdapter()}>
      <MyPage />
    </ActionBridgeProvider>
  );
}

// 2. 在子组件中使用 Hook
function MyPage() {
  const bridge = useActionBridge();

  const goToProfile = async () => {
    try {
      const result = await bridge.navigate('profile', { userId: 123 });
      console.log('导航成功', result);
    } catch (error) {
      console.error('导航失败', error);
    }
  };

  return <button onClick={goToProfile}>查看个人资料</button>;
}

Vue 3

import { createActionBridgePlugin, useActionBridge } from '@yagolive/event-kit/vue';
import { RNWebViewAdapter } from '@yagolive/event-kit/adapters';

// 1. 安装插件
const adapter = new RNWebViewAdapter();
app.use(createActionBridgePlugin(adapter));

// 2. 在组件中使用 Composition API
export default {
  setup() {
    const bridge = useActionBridge();

    const goToProfile = async () => {
      try {
        const result = await bridge.navigate('profile', { userId: 123 });
        console.log('导航成功', result);
      } catch (error) {
        console.error('导航失败', error);
      }
    };

    return { goToProfile };
  }
}

// 3. 也可通过 $actionBridge 访问（Options API）
export default {
  methods: {
    async goToProfile() {
      const result = await this.$actionBridge.navigate('profile', { userId: 123 });
    }
  }
}

ESM / CommonJS

// ESM
import { ActionBridge, RNWebViewAdapter } from '@yagolive/event-kit';
const adapter = new RNWebViewAdapter();
const bridge = new ActionBridge(adapter);

// CommonJS
const { ActionBridge, RNWebViewAdapter } = require('@yagolive/event-kit');
const adapter = new RNWebViewAdapter();
const bridge = new ActionBridge(adapter);

API 参考

ActionCreator

纯逻辑工厂，无环境依赖。用于创建各种 Action 对象。

import { ActionCreator } from '@yagolive/event-kit';

属性

工厂方法

使用示例

// 简单导航
const action = ActionCreator.createNavigateAction('home');
// {"type":"navigate","data":{"screen":"home"}}

// 带参数导航
const action = ActionCreator.createNavigateActionWithParams('profile', {
  userId: 123,
});
// {"type":"navigate","data":{"screen":"profile","params":{"userId":123}}}

// 进房（带回调配置）
const enterRoom = ActionCreator.buildEnterRoom()
  .setId(1001)
  .setBack(true)
  .setText('我的房间')
  .addOpenGiftPopupCallback(
    new ActionCreator.ActionData.EnterRoom.OpenGiftPopupCallback().setId(1),
  );
const action = ActionCreator.createEnterRoomActionWithData(enterRoom);
// {"type":"enter_room","data":{"text":"我的房间","id":1001,"back":true,"callbacks":{"open_gift_popup":{"id":1}}}}

// Onelink
const action = ActionCreator.createOnelinkAction('https://yago.app/room/123');

ActionType

Action 类型枚举。

import { ActionType } from '@yagolive/event-kit';

ActionType.JUMP; // 'jump'
ActionType.NAVIGATE; // 'navigate'
ActionType.REPLACE; // 'replace'
ActionType.GOBACK; // 'goback'
ActionType.ENTER_ROOM; // 'enter_room'
ActionType.LIVE_DETECT; // 'live_detect'
ActionType.ONELINK; // 'onelink'
ActionType.ASK; // 'ask'
ActionType.AGENCY_INVITE; // 'agency_invite'
ActionType.RECHARGE; // 'recharge'
ActionType.REFRESH_USER_INFO; // 'refresh_user_info'
ActionType.CLOSE; // 'close'   (addon)
ActionType.CONFIG; // 'config'  (addon)
ActionType.TRACK; // 'track'
ActionType.GRANT_BENEFITS; // 'grant_benefits'
ActionType.VERIFY_TRADE_PASSWORD; // 'verify_trade_password'
ActionType.UPLOAD_IMAGE; // 'upload_image'

ActionBridge

统一桥接接口，通过注入适配器实现跨环境通信。

import { ActionBridge, RNWebViewAdapter } from '@yagolive/event-kit';

const adapter = new RNWebViewAdapter();
const bridge = new ActionBridge(adapter);

构造函数

new ActionBridge(adapter, options?)

属性

核心方法

便捷方法

每个便捷方法返回 Promise，内部自动创建对应 Action 并发送。返回值类型详见「返回值与结果数据」。

静态方法

使用示例

// Promise 风格（推荐）
const result = await bridge.navigate('profile', { userId: 123 });

// 回调风格（向后兼容）
bridge.sendAction(action, function (result, error) {
  if (error) console.error(error);
  else console.log(result);
});

// 复杂进房配置
const enterRoom = bridge.buildEnterRoom();
enterRoom.setId(1001).setUseReplace(true);
enterRoom.addOpenGiftPopupCallback(
  new bridge.ActionCreator.ActionData.EnterRoom.OpenGiftPopupCallback().setId(
    1,
  ),
);
const action = bridge.createEnterRoomActionWithData(enterRoom);
const result = await bridge.sendAction(action);

// 自定义单次超时(毫秒);timeout<=0 表示禁用超时
const result2 = await bridge.sendAction(action, { timeout: 5000 });
const result3 = await bridge.sendAction(action, { timeout: -1 }); // 不超时

// 销毁
bridge.destroy();

适配器

RNWebViewAdapter

用于 React Native WebView 环境，通过 window.ReactNativeWebView.postMessage 与原生端通信。

import { RNWebViewAdapter } from '@yagolive/event-kit/adapters';

构造函数选项：

示例：

const adapter = new RNWebViewAdapter({ timeout: 15000 });
const bridge = new ActionBridge(adapter);

// 或使用快捷方法
const bridge = ActionBridge.createDefault({ timeout: 15000 });

工作原理：

1. init() 时自动检测 Android/iOS 平台并注册对应的 message 事件监听
2. sendAction() 通过 window.ReactNativeWebView.postMessage() 发送 JSON 数据
3. 原生端处理完毕后通过 postMessage 回传结果，适配器自动匹配回调/Promise
4. 超时未收到回复自动 reject Promise

MockAdapter

用于测试和开发环境，无需真实 WebView 即可模拟通信。

import { MockAdapter } from '@yagolive/event-kit/adapters';

构造函数选项：

方法：

示例：

const mock = new MockAdapter({ delay: 100 });
const bridge = new ActionBridge(mock);

// Mock 返回值
mock.mockResult('navigate', { success: true, screen: 'profile' });

// Mock 错误
mock.mockError('enter_room', new Error('房间不存在'));

// 验证调用
await bridge.navigate('profile');
const calls = mock.getCalls();
console.log(calls[0]);
// { type: 'navigate', data: { screen: 'profile' }, messageId: 'msg_...', timestamp: 1716364800000 }

// 清理
mock.clearCalls();
mock.clearMocks();

自定义适配器

实现以下接口即可创建自定义适配器：

class CustomAdapter {
  // 必须实现
  sendAction(action) {
    // action.type - Action 类型
    // action.data - Action 数据对象（有 toMap() 方法）
    // action.messageId - 消息 ID
    // 必须返回 Promise
    return new Promise((resolve, reject) => {
      // 发送 action 到目标环境
      // 收到回复后 resolve(result) 或 reject(error)
    });
  }

  sendActionNoReply(action) {
    // 发送 action 不期待回复
  }

  // 可选实现
  init() {
    // 初始化逻辑（ActionBridge 构造时自动调用）
  }

  destroy() {
    // 清理逻辑（bridge.destroy() 时自动调用）
  }
}

const bridge = new ActionBridge(new CustomAdapter());

React 集成

import {
  ActionBridgeProvider,
  useActionBridge,
} from '@yagolive/event-kit/react';

ActionBridgeProvider

Context Provider 组件，为子组件提供 ActionBridge 实例。

Props：

行为：

• 传入 adapter 时，Provider 内部创建 ActionBridge 实例，卸载时自动 destroy
• 传入 bridge 时，Provider 直接使用该实例，卸载时不会 destroy
• 都不传时，自动使用 ActionBridge.createDefault() 创建

useActionBridge

Hook，获取当前 ActionBridge 实例。必须在 ActionBridgeProvider 内使用，否则抛出错误。

示例：

function ProfileButton() {
  const bridge = useActionBridge();

  const handleClick = async () => {
    await bridge.navigate('profile', { userId: 123 });
  };

  return <button onClick={handleClick}>查看资料</button>;
}

Vue 3 集成

import {
  createActionBridgePlugin,
  useActionBridge,
} from '@yagolive/event-kit/vue';

createActionBridgePlugin

创建 Vue 插件，安装后提供 ActionBridge 实例。

参数：

安装后提供：

• inject(BRIDGE_KEY) — 通过依赖注入获取
• app.config.globalProperties.$actionBridge — 全局属性访问

useActionBridge

Composition API Hook，获取当前 ActionBridge 实例。必须在安装 createActionBridgePlugin 后使用。

示例：

// Composition API
export default {
  setup() {
    const bridge = useActionBridge();

    const enterRoom = async (roomId) => {
      await bridge.enterRoom(roomId);
    };

    return { enterRoom };
  }
}

// Options API（通过 $actionBridge）
export default {
  methods: {
    async enterRoom(roomId) {
      await this.$actionBridge.enterRoom(roomId);
    }
  }
}

参数与枚举

枚举与字面量类型

常用参数对象

运行时注意：GrantBenefitsOptions.theme 和 UploadImageOptions.cropping 需要传入包内提供的 GrantBenefits.Theme、UploadImage.Cropping 实例，以便 toMap() 正确序列化。TS 结构类型 GrantBenefitsThemeData、UploadImageCroppingData 仅描述序列化后的数据形状。

返回值与结果数据

ActionEventResultMap 按 Action 类型描述执行结果，ActionEventResult<T> 可用于按类型提取结果。

EnterRoomResult

LiveDetectResult

RechargeOrder

UploadImageResult

数据类型

Jump

跳转 Action 数据。

Navigate

导航 Action 数据。

Replace

替换导航 Action 数据，继承自 Navigate，API 相同。

Goback

返回上一页 Action 数据。

EnterRoom

进房 Action 数据。

静态属性：

LiveDetect

活体检测 Action 数据。

Onelink

Onelink Action 数据。

Ask

通用询问 Action 数据，用于邀请、审核等需要用户确认/拒绝的场景。

App 侧消费语义：当 title 或 message 任一非空时，app 侧弹出 ConfirmDialog 让用户确认；均为空则进入静默模式，由调用方（如系统消息卡片）在界面上直接展示 Accept/Reject 按钮。

AgencyInvite

工会邀请 Action 数据。

静态属性：

AgencyInfo 内部类：

Recharge

充值操作 Action 数据。携带 sku 时（Android）跳过充值弹窗直接发起 Google 内购，执行结果返回创建的订单；iOS 暂不支持直接内购。

RefreshUserInfo

刷新用户信息 Action 数据。触发宿主重新拉取用户信息（如领奖后金币入账）。

Close（addon 附加）

关闭 WebView 窗口 Action 数据。来源于 addon.ts 的 AddonAction，由宿主容器扩展。

Config（addon 附加）

配置 WebView 主题色等参数 Action 数据。来源于 addon.ts 的 AddonAction，由宿主容器扩展。

静态属性:

• Config.Theme.DARK = 'dark'
• Config.Theme.LIGHT = 'light'

Track

统计事件上报 Action 数据。

GrantBenefits

权益下发 Action 数据。

静态属性：

Theme 内部类：

VerifyTradePassword

验证交易密码 Action 数据。

UploadImage

图片上传 Action 数据。

静态属性：

• UploadImage.FileType.USER_AVATAR = 'user_avatar'
• UploadImage.FileType.ROOM_IMAGE = 'room_image'
• UploadImage.FileType.OTHER = 'other'
• UploadImage.Sources.PICKER = 'picker'
• UploadImage.Sources.CAMERA = 'camera'
• UploadImage.Sources.BOTH = 'both'
• UploadImage.Cropping | 裁剪配置内部类

Cropping 内部类：

Action

Action 对象，封装类型和数据。

构建

# 构建所有 UMD 文件
npm run build

# 仅构建核心包
npm run build:core

# 仅构建完整包
npm run build:bridge

# 监听模式（开发时使用）
npm run build:watch

产出文件：