ue-webview-bridge

UE WebView Bridge 核心库，提供 Unreal Engine 与 Web View 之间的双向通信桥梁。

📦 安装

npm install ue-webview-bridge

💡 推荐使用方式

强烈推荐搭配 ue-webview-bridge-vite 插件使用：

npm install ue-webview-bridge ue-webview-bridge-vite

使用 Vite 插件后，无需手动初始化，插件会自动处理所有配置和初始化工作。

⚠️ 重要提示： 如果你的项目使用了路由（如 Vue Router、React Router 等），必须使用哈希模式（Hash Mode），而不是 History 模式。这是因为 UE WebView 环境的限制。

如果不使用 Vite 或需要手动集成，请继续阅读下面的手动初始化说明。

🚀 快速开始

方式一：使用 Vite 插件（推荐）

在 vite.config.ts 中配置插件：

import { defineConfig } from 'vite';
import ueWebViewBridge from 'ue-webview-bridge-vite';

export default defineConfig({
  plugins: [ueWebViewBridge()],
});

然后直接在代码中使用 API：

import { sendToGame, registerGameInterface } from 'ue-webview-bridge';

// 直接使用，无需初始化
sendToGame('PlayerAction', { action: 'jump' });

方式二：手动集成

如果不使用 Vite 插件，需要在页面中手动引入 jstoue.js 初始化脚本（由 ue-webview-bridge-vite 包提供），然后使用 API：

import { sendToGame, registerGameInterface } from 'ue-webview-bridge';

sendToGame('PlayerAction', { action: 'jump' });

发送消息到 UE

使用 sendToGame 向 Unreal Engine 发送消息：

import { sendToGame } from 'ue-webview-bridge';

// 发送简单事件
sendToGame('PlayerAction');

// 发送带数据的事件
sendToGame('UpdateScore', { score: 100, level: 5 });

// 发送带回调的事件
sendToGame('QueryData', { id: 1 }, (result) => {
  console.log('UE 返回:', result);
});

接收来自 UE 的消息

使用 registerGameInterface 注册回调函数来接收 UE 发送的消息：

import { registerGameInterface, unregisterGameInterface } from 'ue-webview-bridge';

// 注册接口
registerGameInterface('OnGameStateChanged', (data) => {
  console.log('游戏状态改变:', data);
});

// 取消注册
unregisterGameInterface('OnGameStateChanged');

📖 API 文档

isUEAvailable(): boolean

检查 UE WebView 接口是否可用。

返回值: boolean - UE 接口就绪时返回 true

sendToGame(eventName: string, data?: Record<string, unknown>, callback?: unknown, timeout?: number): void

向 Unreal Engine 发送消息。

参数:

• eventName - 事件名称
• data - 可选的数据负载，会与 eventName 合并后发送
• callback - 可选的回调函数，接收 UE 的返回数据
• timeout - 可选的回调超时时间（秒），默认 6 秒

示例:

sendToGame('PlayerJump');
sendToGame('UpdateInventory', { itemId: 123, count: 5 });
sendToGame('QueryPlayerInfo', {}, (data) => console.log(data), 10);

registerGameInterface<T>(eventName: string, callback: (data: T) => void): string

注册一个接口函数，用于接收来自 UE 的调用。

参数:

• eventName - 事件名称，需要与 UE 端调用的名称一致
• callback - 处理函数，接收来自 UE 的数据，支持自动 JSON 解析

返回值: string - 注册的事件名称

示例:

registerGameInterface('OnPlayerDeath', (data) => {
  console.log('玩家死亡:', data);
});

unregisterGameInterface(eventName: string): void

取消注册接口函数。

参数:

• eventName - 要取消注册的事件名称

示例:

unregisterGameInterface('OnPlayerDeath');

🔧 工作原理

该库通过以下方式实现 Web View 与 UE 的通信：

1. 初始化阶段: 由 jstoue.js（随 ue-webview-bridge-vite 提供）在页面加载时自动初始化 window.ue 及 WebView 通信通道
2. 发送消息: 调用 ue.call(type, json, callback, timeout) 向 UE 发送消息，支持异步回调
3. 接收消息: UE 通过调用 window.ue.interface 上注册的函数向 Web View 发送消息，数据自动完成 JSON 解析

📝 TypeScript 支持

本库完全使用 TypeScript 编写，提供完整的类型定义：

declare global {
  interface Window {
    ue: {
      call: (type: string, json: unknown, callback?: unknown, timeout?: number) => void;
      webview?: unknown;
      interface?: Record<string, (data: unknown) => void>;
      [key: string]: unknown;
    };
    ue4: (type: string, json: unknown, callback?: unknown, timeout?: number) => void;
  }
}

🔗 相关项目

• ue-webview-bridge-vite - Vite 插件，用于构建时自动集成（推荐）

📄 许可证

GPL-3.0 © kongziming