在 Vue 中嵌入 Unity WebGL 并实现双向通信-171主机测评

本文专为前端开发者撰写，将深入介绍如何在 Vue.js 项目中，通过 <iframe> 集成 Unity WebGL 应用，并建立一套基于 postMessage 的高级双向通信架构。本文不仅会展示 Vue 端的代码实现，还将独家揭秘如何改造 Unity 默认生成的 index.html 文件，将其从一个静态页面升级为一个功能强大的“通信桥梁”，最终实现 Vue 与 Unity 之间的完美解耦和高效交互。

一、前言

在现代 Web 开发中，我们常常需要将 Unity 开发的复杂 3D 场景嵌入到 Vue 应用中。一个常见的痛点是前后端的紧密耦合。本文将为你呈现一套业界领先的解决方案，其核心在于改造 Unity 的 index.html，构建一个“通信桥梁”，让你告别直接调用 API 的脆弱模式，进入一个更优雅、更易维护的集成世界。

二、核心架构：解耦的“通信桥梁”模式

我们集成的核心思想，不是让 Vue 直接与 Unity 对话，而是通过一个中间层——一个被精心改造过的 Unity index.html 文件——来充当“通信桥梁”

vue 应用 (父窗口): 我们的主应用，负责 2D UI 和业务逻辑。

通信桥梁 (<iframe> 中的 index.html): 这是 Unity 团队交付给我们的 index.html，但它经过了改造。它的职责是：

接收 Vue 的指令: 监听来自 Vue 的 postMessage，并将其翻译成 Unity 能听懂的 unityInstance.SendMessage() API调用。

转发 Unity 的事件: 监听来自 Unity 内部的事件调用，并将其翻译成 postMessage 发送给 Vue。

Unity 应用 (在 <iframe> 中运行): 纯粹的 3D 引擎，专注于 3D 逻辑。

通过这种方式，Vue 和 Unity 互相不知道对方的技术细节，它们只通过标准的 postMessage “信件”与中间的桥梁沟通，实现了完美的解耦。

三、揭秘“通信桥梁”：如何改造 Unity 的 index.html

这是整个架构的精髓所在。Unity 默认生成的 index.html 是一个孤岛，我们需要通过以下改造，将它变为通信枢纽。

Unity 内部可以通过调用全局 JavaScript 函数来对外“喊话”。默认情况下，这些函数是空的，我们需要让它们把话传出去。

改造前 (Unity 原始代码)

//原代码是 Unity 构建出的标准模板，

<!DOCTYPE html>
<html lang="en-us">
<head>
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Unity Web Player | YangShanGang</title>
</head>
<body style="text-align: center; padding: 0; border: 0; margin: 0;">
<canvas id="unity-canvas" width=3200 height=1800 tabindex="-1" style="width: 3200px; height: 1800px; background: #231F20"></canvas>

if (/iPhone|iPad|iPod|Android/i.test(navigator.userAgent)) {
var meta = document.createElement('meta');
meta.name = 'viewport';
meta.content = 'width=device-width, height=device-height, initial-scale=1.0, user-scalable=no, shrink-to-fit=yes';
document.head.appendChild(meta);

var canvas = document.querySelector("#unity-canvas");
canvas.style.width = "100%";
canvas.style.height = "100%";
canvas.style.position = "fixed";
document.body.style.textAlign = "left";
}

function loadUnity() {
createUnityInstance(document.querySelector("#unity-canvas"), {
arguments: [],
dataUrl: "Build/YSG.data",
frameworkUrl: "Build/YSG.framework.js",
codeUrl: "Build/YSG.wasm",
streamingAssetsUrl: "StreamingAssets",
companyName: "DefaultCompany",
productName: "YangShanGang",
productVersion: "0.1.0",
}).then((instance) => {
unityInstance = instance;
console.log(" Unity 实例已加载");

// 绑定全屏按钮（如果有的话）
var fullscreenButton = document.querySelector("#unity-fullscreen-button");
if (fullscreenButton) {
fullscreenButton.onclick = () => {
unityInstance.SetFullscreen(1);
};
}
}).catch((message) => {
console.error("❌ Unity 加载失败: ", message);
});
}
document.addEventListener("DOMContentLoaded", loadUnity);
//________________________

function HtmlCurrentPlotIndex(index) {
}
function GetCursorMoveData(jsonData) {
if (unityInstance) {
unityInstance.SendMessage("MockCursor", "GetCursorMoveData", jsonData);
}
}
</script>
</body>
</html>

核心目标：实现应用解耦与双向通信

原始的 index.html 只能单向地被外部调用（通过全局 JS 函数），并且无法主动通知外部发生了什么。下面的修改实现了两个关键目标。

建立从 Unity 到 Vue 的消息通道 (postMessage 发送)
建立从 Vue 到 Unity 的消息通道 (postMessage 接收)

这使得 Vue 应用和 Unity 应用可以作为两个独立的实体进行开发，它们之间通过一个标准化的、类似 API 的方式进行对话，大大降低了耦合度。

实现 “Unity → Vue” 的消息转发

这是最重大的修改之一。

原始状态: 在原始文件中，所有以 Html 开头的函（如 HtmlCurrentPlotIndex, HtmlSendEventId）都是空函数体。

// 原始代码
function HtmlCurrentPlotIndex(index) {
// (这里是空的)
}
function HtmlSendEventId(index) {
// (这里是空的)
}

这意味着，当 Unity 内部调用这些函数时，什么都不会发生。Unity 只是在“喊话”，但没人把它的话传出去。

修改后：将它们变成了消息转发器。

// 您的修改后代码
function HtmlCurrentPlotIndex(index) {
window.parent.postMessage({
name: 'HtmlCurrentPlotIndex', // 自定义消息名称，用于Vue中识别
data: index // 传递的参数
}, '*');
}

function HtmlSendEventId(index) {
window.parent.postMessage({
name: 'HtmlSendEventId',
data: index
}, '*');
}

修改逻辑: 我们为所有 Unity 需要对外发送事件的 Html… 函数都填充了 window.parent.postMessage 的实现，使其成为一个消息转发器。

实现 “Vue → Unity” 的指令接收与分发

这是让架构变得非常优雅和解耦的关键。

原始状态: 原始文件只能通过直接调用全局函数（如 GotoShip('id-123')）来与 Unity 交互。这意味着前端必须知道所有这些全局函数的具体名称。

修改后：在 index.html 中添加了一个全局的 message 事件监听器，使其成为一个指令接收和分发中心。

// 新增代码
window.addEventListener('message', function(event) {
let data = event.data;
// 如果是 unityCommand 类型的消息
if (data.type === 'unityCommand') {
if (typeof window[data.method] === 'function') {
window[data.method](data.param); // 调用相应的方法并传递参数
}
}
// … (还可以处理其他类型的消息)
});

这段代码使 index.html 成为了一个指令分发中心。它监听所有来自 Vue 的消息，如果消息类型是 unityCommand，它就会根据消息中的 method 字段，动态地执行页面中已经存在的同名全局函数（如 GotoShip、SetVolume 等），从而触发对 unityInstance.SendMessage 的最终调用。

修改逻辑:

监听消息: 这段代码会监听所有来自父窗口（Vue）的 postMessage 请求。
协议解析: 它检查消息是否符合您定义的协议，即 data.type === 'unityCommand'。
动态调用: 如果协议匹配，它会取出 data.method（例如，字符串 "GotoShip"）和 data.param，然后动态地在当前 window 对象上查找并执行同名函数，即 window['GotoShip'](data.param)。
执行指令: GotoShip 函数内部再调用 unityInstance.SendMessage，最终将指令送达 Unity 场景。

增加 Unity 加载完成的通知

为了让 Vue 知道何时可以安全地与 Unity 通信，我们需要在 Unity 实例加载完成后，主动通知 Vue。

原始状态: 原始文件加载完 Unity 实例后，只是在控制台打印一条日志。外部应用无法确切知道 Unity 何时准备就绪。

修改后：在 createUnityInstance 的 .then() 回调中，增加了一条 postMessage。

// 修改后代码
.then((instance) => {
unityInstance = instance;
// console.log(" Unity 实例已加载");
window.top.postMessage({
name: 'LoadSceneOver'
}, '*')
})

修改逻辑: 当 Unity 实例成功加载后，立刻向父窗口（Vue）发送一个名为 LoadSceneOver 的消息。Vue 应用在监听到这个消息后，就可以安全地开始向 Unity 发送初始化指令或执行其他依赖 Unity 的操作，避免了在 Unity 未准备好时调用而出错的问题。

修改后的整体代码：

<!DOCTYPE html>
<html lang="en-us">

<head>
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Unity Web Player | YangShanGang</title>
<style>
html,
body {
width: 100%;
height: 100%;
padding: 0;
margin: 0;
overflow: hidden;
}

#unity-container {
position: absolute;
width: 100% !important;
height: 100% !important;
overflow: hidden;
}

#unity-container.unity-desktop {
left: 50%;
top: 50%;
transform: translate(-50%, -50%)
}

#unity-container.unity-mobile {
position: fixed;
width: 100% !important;
height: 100% !important;
}

#unity-canvas {
background: #231F20;
width: 100% !important;
height: 100% !important;
}

.unity-mobile #unity-canvas {
width: 100% !important;
height: 100% !important;
}
</style>
</head>
<body style="text-align: center; padding: 0; border: 0; margin: 0;">
<canvas id="unity-canvas" tabindex="-1" style="width: 1920px; height: 1120px; background: #231F20"></canvas>

var canvas = document.querySelector("#unity-canvas");
canvas.style.width = "100%";
canvas.style.height = "100%";
canvas.style.position = "fixed";
document.body.style.textAlign = "left";
}

// 绑定全屏按钮（如果有的话）
var fullscreenButton = document.querySelector("#unity-fullscreen-button");
if (fullscreenButton) {
fullscreenButton.onclick = () => {
unityInstance.SetFullscreen(1);
};
}
}).catch((message) => {
// console.error("❌ Unity 加载失败: ", message);
});
}
document.addEventListener("DOMContentLoaded", loadUnity);
window.addEventListener('message', function(event) {
let data = event.data;

// 根据 data.name 来区分不同的消息类型
if (data.name === 'loadInit') {
// 处理初始化
if (typeof window[data.method] === 'function') {
window[data.method](data.param); // 调用传递的方法并传参
}
}

// 如果是 unityCommand 类型的消息
if (data.type === 'unityCommand') {
if (typeof window[data.method] === 'function') {
window[data.method](data.param); // 调用相应的方法并传递参数
}
}

// 针对其他消息类型（例如警告数据处理）
if (data.name === 'warnProps') {
setTimeout(() => {
if (typeof window[data.method] === 'function') {
window[data.method](data.param);
}
}, 1000); // 延时处理，避免冲突
}

// 根据不同的消息执行不同的处理
if (data.name === 'callEvent') {
if (typeof window[data.method] === 'function') {
window[data.method](data.param);
}
}

if (data.name === 'callOverId') {
if (typeof window[data.method] === 'function') {
window[data.method](data.param);
}
}
});
function HtmlCurrentPlotIndex(index) {
console.log(" unity当前情节索引————-：" + index);
window.parent.postMessage({
name: 'HtmlCurrentPlotIndex', // 自定义消息名称，用于Vue中识别
data: index // 传递的参数（例如点击的UI名称）
}, '*');
}
function HideOrShowHeatPointData(jsonData) {
// console.log(jsonData, 'yjshu哈哈哈哈哈');

if (unityInstance) {
unityInstance.SendMessage("SceneManager", "HideOrShowHeatPointData", jsonData);
// console.log(" unity热力图显隐———" + jsonData);
}
}
//…..
</script>
</body>

</html>

四、步骤一：在 Vue 中嵌入 Unity 应用

集成 Unity 应用的第一步是让它在我们的页面中正确地显示出来。

1.文件放置

首先，将 Unity 团队提供的整个 WebGL 构建文件夹（通常包含一个 index.html 和其他资源目录）直接复制到你的 Vue 项目的 public 目录下。这样做可以确保在项目启动后，该文件夹内的所有内容都能作为静态资源被直接访问。下面是我的项目中unity给到的文件结构

– public/
– UnityBuild/ <– 将 Unity 构建文件夹放在这里
– index.html
– Build/
– StreamingAssets/
– …
– favicon.ico
– src/
– …

2.使用 <iframe> 作为容器

在你的 Vue 组件中，使用 <iframe> 标签来加载 Unity 的入口 HTML 文件。<iframe> 是最理想的选择，因为它创建了一个独立的沙箱环境，可以有效避免 CSS 样式污染和 JavaScript 变量冲突。

<!– 用于承载 Unity 的 Iframe –>
<iframe
ref="unityFrame"
:src="unityUrl"
class="unity-iframe"
frameborder="0"
></iframe>
</div>
</template>

// Unity 应用的访问路径，相对于 public 目录
const unityUrl = ref('/UnityBuild/index.html');

// 创建一个 ref 来获取 iframe DOM 元素
const unityFrame = ref<HTMLIFrameElement | null>(null);
</script>

.header {
position: absolute;
top: 0;
left: 0;
width: 100%;
z-index: 10; /* 确保 UI 在 iframe 上方 */
}

.unity-iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
border: none; /* 移除边框 */
}
</style>

五、步骤二：接收来自 Unity 的消息 (Unity → Vue)

当 Unity 场景中发生特定事件时（例如，一段介绍动画播放到某个节点），它会通过 window.parent.postMessage() 向我们的 Vue 应用发送消息。我们需要做的就是监听这些消息。

1.注册全局消息监听器

最佳实践是在组件挂载 (onMounted) 时添加监听器，并在组件卸载 (onUnmounted) 时移除它，以防止内存泄漏。

import { ref, onMounted, onUnmounted } from 'vue';
import { Store} from '@/store'; // 假设你使用 Pinia

const store = Store();

// 消息处理函数
const handleMessage = (event: MessageEvent) => {
// 安全起见，可以检查消息来源是否可信
// if (event.origin !== "http://your-expected-origin.com") return;

const { name, data } = event.data;

// 使用 switch 根据消息名称分发任务
switch (name) {
case 'LoadSceneOver':
console.log("Unity 场景已加载完毕！");
// 可以在此时进行一些初始化调用
break;

case 'HtmlCurrentPlotIndex':
console.log(`Unity 正在讲解图表: ${data}`);
store.setActiveChart(data); // 更新状态管理中的当前图表
break;

case 'HtmlSendEventId':
console.log(`接收到 Unity 预警事件 ID: ${data}`);
store.showWarningPopup(data); // 触发显示预警弹窗
break;

// …可以处理更多其他类型的消息
default:
break;
}
};

onMounted(() => {
// 注册一个全局的 message 事件监听器
window.addEventListener('message', handleMessage);
});

onUnmounted(() => {
// 移除监听器，避免内存泄漏
window.removeEventListener('message', handleMessage);
});

核心解读:

window.addEventListener('message', …) 是浏览器提供的标准 API，用于监听跨窗口消息。

event.data 就是 Unity 发送过来的消息对象。我们通常会约定一个格式，比如 { name: '消息类型', data: '具体数据' }，这样在 handleMessage 函数中就可以通过 name 来判断如何处理 data。四、步骤三：向 Unity 发送指令。（我们监听 window 的 message 事件，并根据 event.data 中约定的 name 字段来执行不同的前端逻辑。）

六、步骤三：向 Unity 发送指令

反向通信——从 Vue 控制 Unity 场景——是实现动态交互的核心。不同于直接调用 Unity 的 API，我们将采用一种更为优雅的 postMessage 机制，以实现彻底的前后端解耦。

前端通信接口的约定

我们与 Unity 侧约定，所有从 Vue 发往 Unity 的指令都将通过 postMessage 发送，并遵循以下数据结构：

interface UnityCommand {
type: 'unityCommand'; // 一个固定的标识符
method: string; // 要调用的方法名
param?: any; // 传递的参数
}

在 Pinia Store 中封装发送函数

为了方便在项目的任何组件中调用，我们将发送逻辑封装在状态管理（如 Pinia）中。

// src/store/store.ts
import { defineStore } from 'pinia';

export const useUnityStore = defineStore('unity', {
state: () => ({
unityFrame: null as HTMLIFrameElement | null,
}),
actions: {
setUnityFrame(frame: HTMLIFrameElement) {
this.unityFrame = frame;
},

/**
* 向 Unity 发送指令
* @param methodName 要在 Unity 的 index.html 中调用的全局函数名
* @param parameter 要传递的参数，如果是对象会自动转为 JSON 字符串
*/
sendToUnity(methodName: string, parameter?: any) {
if (!this.unityFrame || !this.unityFrame.contentWindow) {
console.warn('Unity iframe 尚未初始化！');
return;
}

try {
// 如果参数是对象，则字符串化
const paramToSend = typeof parameter === 'object' && parameter !== null
? JSON.stringify(parameter)
: parameter;

// 使用 postMessage 发送标准格式的指令
this.unityFrame.contentWindow.postMessage(
{
type: 'unityCommand',
method: methodName,
param: paramToSend
},
'*' // 注意：生产环境应指定为 Unity 应用的域名
);
} catch (error) {
console.error('发送消息到 Unity Iframe 失败:', error);
}
},
},
});

注意: 在你的主组件 (index.vue) 的 onMounted 中，需要调用 store.setUnityFrame(unityFrame.value) 来初始化 unityFrame。

onMounted(() => {
// store.warningId = 1;//测试预警播报
store.setUnityFrame(unityFrame.value)
shipType()
window.addEventListener('message', handleMessage);//注册一个全局的 message 事件监听器
})

在业务逻辑中调用

现在，从任何组件中向 Unity 发送指令都变得非常简单和清晰

<template>
<!– … –>
<div class="controls">
<button @click="focusOnShip('Ship_007')">聚焦 007 号船</button>
<button @click="toggleHeatmap(true)">显示热力图</button>
</div>
</template>

const store = Store();

function focusOnShip(shipId: string) {
// 我们只需要知道方法名是 'GotoShip'
store .sendToUnity('GotoShip', shipId);
}

function toggleHeatmap(show: boolean) {
// 我们只需要知道方法名是 'HideOrShowHeatPointData'
const params = { isShow: true};
store .sendToUnity('HideOrShowHeatPointData', String(params .isShow);
}
</script>

核心解读:

前端的视角: 作为前端开发者，我们完全不需要关心 Unity 的内部实现。我们的通信接口就是 unityStore.sendToUnity。我们只需查阅与 Unity 团队约定好的“方法名”列表，就可以自由地控制 3D 场景了。

架构的优雅: 这种基于 postMessage 的双向通信模型，让 Vue 和 Unity 成了两个通过标准化信件（消息对象）沟通的独立应用，大大提升了项目的可维护性和扩展性。

在 Vue 中嵌入 Unity WebGL 并实现双向通信

一、前言

二、核心架构：解耦的“通信桥梁”模式

三、揭秘“通信桥梁”：如何改造 Unity 的 index.html

核心目标：实现应用解耦与双向通信

实现 “Unity → Vue” 的消息转发

实现 “Vue → Unity” 的指令接收与分发

增加 Unity 加载完成的通知

四、步骤一：在 Vue 中嵌入 Unity 应用

1.文件放置

2.使用 <iframe> 作为容器

五、步骤二：接收来自 Unity 的消息 (Unity → Vue)

1.注册全局消息监听器

六、步骤三：向 Unity 发送指令

前端通信接口的约定

在 Pinia Store 中封装发送函数

在业务逻辑中调用

相关推荐

评论抢沙发

热门标签

热门文章

最新文章

归档

分类

一、 前言

二、 核心架构：解耦的“通信桥梁”模式

三、揭秘“通信桥梁”：如何改造 Unity 的 index.html

核心目标：实现应用解耦与双向通信

实现 “Unity → Vue” 的消息转发

实现 “Vue → Unity” 的指令接收与分发

增加 Unity 加载完成的通知

四、 步骤一：在 Vue 中嵌入 Unity 应用

1.文件放置

2.使用 <iframe> 作为容器

五、 步骤二：接收来自 Unity 的消息 (Unity → Vue)

1.注册全局消息监听器

六、 步骤三：向 Unity 发送指令

前端通信接口的约定

在 Pinia Store 中封装发送函数

在业务逻辑中调用

相关推荐

评论 抢沙发

热门标签

热门文章

最新文章

归档

分类

一、前言

二、核心架构：解耦的“通信桥梁”模式

四、步骤一：在 Vue 中嵌入 Unity 应用

五、步骤二：接收来自 Unity 的消息 (Unity → Vue)

六、步骤三：向 Unity 发送指令

评论抢沙发