# @azesmway/react-native-unity 中文文档

规范地址：https://npmcn.com/package/%40azesmway/react-native-unity/

版本：1\.1\.1
npm 元数据更新时间：2026-08-07T13:19:41.528Z
中文译文更新时间：2026-11-07T15:38:59.045Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azesmway/react-native-unity
原文对照：https://npmcn.com/package/%40azesmway/react-native-unity/?lang=original
项目主页：https://github.com/azesmway/react-native-unity#readme
源码仓库：https://github.com/azesmway/react-native-unity

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：96.2 kB，47 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.0\.0
- 运行依赖：0 个
- peer 依赖：react \*，react-native \*
- 首次发布：2022-03-29T15:59:21.025Z
- 最新版本发布：2026-08-07T13:19:41.341Z
- 近 30 天下载量：7229（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 2 个）

## 中文简介

反应原生团结

## 安装

```sh
npm install @azesmway/react-native-unity
```

也可以使用：`pnpm add @azesmway/react-native-unity`、`yarn add @azesmway/react-native-unity`、`bun add @azesmway/react-native-unity`

## README

# @azesmway/反应-本土-团结

允许您将 Unity 工程嵌入 React Natural 作为完整组件的插件 。 插件现在支持新架构.

### 机器人

请注意! 增加了对团结2023及以上的支持

> \[大 对于iOS来说,不再需要嵌入一个和Unity一起创建的项目. 只有建筑 `UnityFramework` 已使用。 它应该放在路径的插件文件夹中 - `<YOUR_RN_PROJECT>/unity/builds/ios`

## 设备支持 :

| 平台 | 支助 |
| --- | --- |
| iOS 模拟器 | 备选(参见 [iOS 模拟器支持](https://npmcn.com/package/%40azesmway/react-native-unity/#readme-ios-simulator-support-optional)(中文(简体) ) |
| iOS 设备 | ✅ |
| Android 模拟器 | ✅ |
| Android 设备 | ✅ |

> IOS 模拟器只使用下面描述的可选 XCF框架导出; 默认设备 `UnityFramework.framework` 不在模拟器上链接.

# 安装

## 在您的反应内置工程中安装此软件包 :

```sh
npm install @azesmway/react-native-unity

or

yarn add @azesmway/react-native-unity
```

## 配置您的团结项目 :

1.  复制文件夹的内容 `unity` 到您的团结项目根。 此文件夹包含团结项目所需的脚本和设置 。 您可以在您的反应内置工程中找到这些文件 `node_modules/@azesmway/react-native-unity/unity`。这是确保iOS能够访问 `NativeCallProxy` 这个图书馆的课.
    
2.  (可选) 如果你跟随这个例子,你可以把以下代码添加到 `ButtonBehavior.cs` 团结计划中的脚本 。 这使得Unity中的按钮按下可以与您的反应-内置应用程序进行通信.
    

按钮行为.cs

```csharp
using System;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using UnityEngine.UI;
using UnityEngine;

public class NativeAPI {
#if UNITY_IOS && !UNITY_EDITOR
  [DllImport("__Internal")]
  public static extern void sendMessageToMobileApp(string message);
#endif
}

public class ButtonBehavior : MonoBehaviour
{
  public void ButtonPressed()
  {
    if (Application.platform == RuntimePlatform.Android)
    {
      using (AndroidJavaClass jc = new AndroidJavaClass("com.azesmwayreactnativeunity.ReactNativeUnityViewManager"))
      {
        jc.CallStatic("sendMessageToMobileApp", "The button has been tapped!");
      }
    }
    else if (Application.platform == RuntimePlatform.IPhonePlayer)
    {
#if UNITY_IOS && !UNITY_EDITOR
      NativeAPI.sendMessageToMobileApp("The button has been tapped!");
#endif
    }
  }
}
```

## 导出 iOS 团结工程 :

在你把文件搬走之后 `unity` 文件夹中,您可以通过这些步骤导出 iOS 统一项目 :

1.  打开您的团结项目
2.  在任何文件夹中为 ios 构建团结项目 - 只是不是主 RN 项目文件夹! !
3.  在 XCode 中打开创建的工程
4.  选择数据文件夹并在“目标成员”栏目中设置一个复选框到“团结框架” ![image info](https://npmcn.com/package/%40azesmway/react-native-unity/docs/step1.jpg)
5.  您需要选择本地CallProxy.h `Unity-iPhone/Libraries/Plugins/iOS` unity-iPhone项目的文件夹,并将UnityFramework的目标成员从项目改为公共。 别忘了这个步骤! (如果你在Xcode项目中没有看到这些文件,你没有复制到 `unity` 文件夹,在前几个步骤中正确显示团结项目) ![image info](https://npmcn.com/package/%40azesmway/react-native-unity/docs/step2.jpg)
6.  如果需要 - 在项目上签名 `UnityFramework.framework` 建立一个框架 ![image info](https://npmcn.com/package/%40azesmway/react-native-unity/docs/step3.jpg)
7.  用已建框架打开文件夹( 右键单击) 并移动到插件文件夹( Q)`<YOUR_RN_PROJECT>/unity/builds/ios`(中文(简体) ) ![image info](https://npmcn.com/package/%40azesmway/react-native-unity/docs/step4.jpg)
8.  删除您的 `Pods` 在 RN 主工程的根中含有此命令的缓存和锁定文件 `rm -rf ios/Pods && rm -f ios/Podfile.lock && npx pod-install`

### 机器人

1.  打开您的团结项目
2.  导出团结应用程序到 `<YOUR_RN_PROJECT>/unity/builds/android`
3.  删除 `<intent-filter>...</intent-filter>` 从 `<YOUR_RN_PROJECT>/unity/builds/android/unityLibrary/src/main/AndroidManifest.xml` 统一图书馆只保留集成版本.

若用博览相取已. 内置的 expo 插件将处理其余部分 。 如果你不使用博览会,你需要遵循下面的步骤.

1.  添加以下行为 `android/settings.gradle`数字 :
    
    ```groovy
    include ':unityLibrary'
    project(':unityLibrary').projectDir=new File('..\\unity\\builds\\android\\unityLibrary')
    ```
    
2.  添加到 `android/build.gradle`
    
    ```groovy
    allprojects {
      repositories {
        // this
        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
        // ...
      }
    }
    ```
    
3.  添加到 `android/gradle.properties`
    
    ```gradle
    unityStreamingAssets=.unity3d
    ```
    
4.  添加字符串到 `android/app/src/main/res/values/strings.xml`
    
    ```javascript
    <string name="game_view_content_description">Game view</string>
    ```
    

# 已知问题

-   不使用默认设备唯一框架的iOS模拟器。 见 [iOS 模拟器支持( 可选)](https://npmcn.com/package/%40azesmway/react-native-unity/#readme-ios-simulator-support-optional) 用于XCF框架工作.
-   在iOS上,Unity视图正在等待一个尺寸大于0的母体(来自RN侧). 请照顾好这个,因为如果不是,你的应用会随着本地信息崩溃 `MTLTextureDescriptor has width of zero`。 。 。 .

# 使用量

## 样本代码

```jsx
import React, { useRef, useEffect } from 'react';

import UnityView from '@azesmway/react-native-unity';
import { View } from 'react-native';

interface IMessage {
  gameObject: string;
  methodName: string;
  message: string;
}

const Unity = () => {
  const unityRef = useRef<UnityView>(null);

  useEffect(() => {
    if (unityRef?.current) {
      const message: IMessage = {
        gameObject: 'gameObject',
        methodName: 'methodName',
        message: 'message',
      };
      unityRef.current.postMessage(
        message.gameObject,
        message.methodName,
        message.message
      );
    }
  }, []);

  return (
    <View style={{ flex: 1 }}>
      <UnityView
        ref={unityRef}
        style={{ flex: 1 }}
        onUnityMessage={(result) => {
          console.log('onUnityMessage', result.nativeEvent.message);
        }}
      />
    </View>
  );
};

export default Unity;
```

## 道具

-   `style: ViewStyle` - 统一维尤的风格 (不会在没有维度的Android上出现. 建议给予 `flex: 1` (例如例子)
-   `onUnityMessage?: (event: { nativeEvent: { message: string } }) => void` - 收到Unity的留言 该有效载荷作为 `event.nativeEvent.message`
-   `onPlayerUnload?: (event) => void` - 当Unity玩家被卸下时开火
-   `onPlayerQuit?: (event) => void` - 统一玩家退出时被解雇
-   `androidKeepPlayerMounted?: boolean` - 如果设置为真, 即使在包含此内容的视图失去焦点时, 仍保留玩家挂载 。 玩家会被暂停在模糊上并恢复焦点. **仅安地鲁**
-   `fullScreen?: boolean` - 默认为真实。 如果设置为虚假, 将不会请求全屏访问 . **仅安地鲁**

## 方法

-   `postMessage(gameObject, methodName, message)` - 向统一军发出信息. **给监督厅:** 使用本土的统一方法发送信息 `sendMessageToGOWithName:(const char*)goName functionName:(const char*)name message:(const char*)msg;`中,可以在 [文档](https://docs.unity3d.com/2021.1/Documentation/Manual/UnityasaLibrary-iOS.html)
-   `unloadUnity()` - 当反应-内在组件被卸载时,团结会自动卸载,但如果想要卸载团结,可以使用这种方法
-   `pauseUnity(pause: boolean)` - 暂停(`true`或恢复(`false`团结玩家
-   `resumeUnity()` - 暂停后恢复团结播放器
-   `windowFocusChanged(hasFocus: boolean = true)` - 模拟焦点变化(打算在重载Unity视图后用于从黑屏幕中恢复(不渲染)) `resumeUnity` 无效) **仅安地鲁**

# 捐款

见 [贡献指南](https://npmcn.com/package/%40azesmway/react-native-unity/CONTRIBUTING.md) 学习如何为储存库和发展工作流程作出贡献.

# 许可证

麻省理工学院

## iOS 模拟器支持( 可选)

经典的销售商设置一个设备 `UnityFramework.framework`,这就是为什么 支持表格将 iOS 模拟器列为不支持的: 模拟器构建失败连接 设备- arm64 dylib. 团结本身可以瞄准模拟器——将两片都打入一个 XCF框架和插件自动取出:

1.  在Unity中,导出 iOS 项目两次:一次 **目标SDK:设备SDK** 一次 与 **目标 SDK:模拟器 SDK** (Player设置 → iOS → 目标 SDK).
2.  构建 `UnityFramework` 从每个导出并创建 XCF 框架 :

```sh
xcodebuild -project device-export/Unity-iPhone.xcodeproj -scheme UnityFramework \
  -configuration Release -sdk iphoneos BUILD_DIR="$PWD/device-build" build
xcodebuild -project simulator-export/Unity-iPhone.xcodeproj -scheme UnityFramework \
  -configuration Release -sdk iphonesimulator BUILD_DIR="$PWD/simulator-build" build
xcodebuild -create-xcframework \
  -framework device-build/Release-iphoneos/UnityFramework.framework \
  -framework simulator-build/Release-iphonesimulator/UnityFramework.framework \
  -output <YOUR_RN_PROJECT>/unity/builds/ios/UnityFramework.xcframework
```

3.  莱因斯通舱。 Xcode 只链接设备切片, 因此运出应用大小不变.

## 常见问题

### @azesmway/react-native-unity 是什么？

反应原生团结

### 如何安装 @azesmway/react-native-unity？

在项目目录运行 npm install @azesmway/react-native-unity，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @azesmway/react-native-unity 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azesmway/react-native-unity 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azesmway/react-native-unity 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azesmway/react-native-unity 可以商用吗？

@azesmway/react-native-unity 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azesmway/react-native-unity 的下载量有多少？

根据 npm 官方下载统计，@azesmway/react-native-unity 在 2026/10/08 – 2026/11/06 这 30 天内被下载 7,229 次，日均约 241 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azesmway/react-native-unity 还在维护吗？

最新版本 1\.1\.1 发布于 2026/08/07（3 个月前）；至今共发布 37 个版本，其中过去 12 个月发布了 2 个；首次发布于 2022/03/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。