Uniapp与原生App集成详解Android和iOS的SDK与WebView方案-开发者社区-阿里云

Uniapp 与原生 App（Android/iOS）的集成主要分为“原生 App 嵌入 Uniapp 页面”和“Uniapp 调用原生功能”两大场景，核心是通过 SDK 或 WebView 实现两者的资源融合与通信。以下是详细的集成流程，分 Android 和 iOS 平台说明：

一、集成前的准备工作

Uniapp 端：
- 确保项目已在 HBuilderX 中开发完成，需明确哪些页面/功能需要嵌入原生 App，或需要调用原生能力（如蓝牙、自定义硬件交互）。
- 生成 Uniapp 资源包：
  - 若通过 SDK 集成（深度混合开发）：在 HBuilderX 中执行“发行 → 原生 App-本地打包 → 生成本地打包 App 资源”，得到 __UNI__XXX 开头的资源文件夹（含 www 目录，存放编译后的前端资源）。
  - 若通过 WebView 集成（轻量混合开发）：发行 H5 版本（“发行 → 网站-H5 手机版”），得到 H5 静态资源（可部署到服务器或放入原生 App 的本地目录）。
原生 App 端：
- Android：准备 Android Studio 项目，确保 SDK 版本 ≥ 21（Android 5.0+）。
- iOS：准备 Xcode 项目，确保支持 iOS 10.0+，并配置开发者证书（用于调试和打包）。
- 下载 Uniapp 对应平台的 SDK：
  - Android SDK：DCloud 原生 SDK 下载
  - iOS SDK：DCloud 原生 SDK 下载

二、Android 原生 App 集成 Uniapp 流程

方案 1：通过 Uniapp SDK 深度集成（推荐，支持原生功能扩展）

适合需要在原生 App 中直接运行 Uniapp 页面，并实现复杂原生交互的场景。

导入 Uniapp SDK 到原生项目
- 解压下载的 Android SDK，将 libs 目录下的 uniapp-v8-release.aar、lib.5plus.base-release.aar 等 AAR 包复制到原生项目的 app/libs 目录。
- 在 app/build.gradle 中配置依赖：
```
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])
    implementation 'androidx.appcompat:appcompat:1.4.1'
    // 其他必要依赖（如 okhttp、glide 等，SDK 可能依赖）
}
```
- 同步项目（Sync Now），确保 SDK 依赖生效。
配置 Uniapp 资源
- 将 HBuilderX 生成的 Uniapp 资源包（__UNI__XXX 文件夹）复制到原生项目的 app/src/main/assets/apps 目录下（若没有 apps 文件夹则创建）。
- 在 assets/data 目录下创建 dcloud_control.xml 文件，配置 Uniapp 应用信息：
```
<?xml version="1.0" encoding="UTF-8"?>
<dcloud-control>
    <apps>
        <app appid="__UNI__XXX" appver="1.0.0" /> 
    </apps>
</dcloud-control>
```

在原生页面中加载 Uniapp 页面

创建一个继承自 UniActivity 的 Activity（Uniapp SDK 提供的基类），用于承载 Uniapp 页面：

import io.dcloud.feature.uniapp.UniActivity;

public class UniappContainerActivity extends UniActivity {
       
    @Override
    public void onCreate(Bundle savedInstanceState) {
       
        super.onCreate(savedInstanceState);
        // 加载 Uniapp 首页（默认加载 pages.json 中配置的首页）
        // 若需指定页面，可通过 intent 传递参数：loadUrl("pages/detail/detail?param=123")
    }
}

在 AndroidManifest.xml 中注册该 Activity，并添加必要权限（如网络、存储等）：

<activity
    android:name=".UniappContainerActivity"
    android:configChanges="orientation|keyboardHidden|screenSize"
    android:theme="@style/Theme.AppCompat.Light.NoActionBar" />

实现 Uniapp 与原生的通信

Uniapp 调用原生方法：

原生端创建一个类实现 IUniModule 接口，定义供 Uniapp 调用的方法：

import io.dcloud.feature.uniapp.common.UniModule;

public class NativeModule extends UniModule {
         
    // 注解 @UniJSMethod 标记该方法可被 Uniapp 调用
    @UniJSMethod(uiThread = true)
    public void openNativePage(String param, UniJSCallback callback) {
         
        // 处理参数，打开原生页面或执行原生逻辑
        callback.invoke("原生处理结果：" + param); // 回调结果给 Uniapp
    }
}

在 Uniapp 中通过 uni.requireNativePlugin 调用：

const nativeModule = uni.requireNativePlugin('NativeModule'); // 名称需与原生类名一致
nativeModule.openNativePage('test', (res) => {
         
    console.log(res); // 输出：原生处理结果：test
});

原生调用 Uniapp 方法：
原生端通过 UniSDKEngine 发送事件，Uniapp 监听事件：

// 原生端发送事件
UniSDKEngine.sendEvent("nativeEvent", "{\"data\":\"来自原生的数据\"}");

// Uniapp 端监听事件
uni.onNativeEventReceive((res) => {
       
    console.log("收到原生事件：", res.data); // 输出：来自原生的数据
}, "nativeEvent");

方案 2：通过 WebView 轻量集成（适合简单页面嵌入）

若只需在原生 App 中展示 Uniapp 开发的 H5 页面，无需复杂原生交互，可直接用 WebView 加载 H5 资源。

在原生布局中添加 WebView

<!-- activity_main.xml -->
<WebView
    android:id="@+id/webview"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

加载 Uniapp H5 资源

WebView webView = findViewById(R.id.webview);
WebSettings webSettings = webView.getSettings();
webSettings.setJavaScriptEnabled(true); // 允许 JS 执行
webSettings.setDomStorageEnabled(true); // 支持 localStorage

// 加载本地 H5 资源（放在 assets 目录下）
webView.loadUrl("file:///android_asset/uniapp_h5/index.html");
// 或加载远程 H5 地址
// webView.loadUrl("https://your-domain/uniapp-h5");

WebView 与 Uniapp 通信
通过 addJavascriptInterface 注入原生对象，供 H5 调用：

webView.addJavascriptInterface(new Object() {
     
    @JavascriptInterface
    public void callNative(String data) {
     
        // 处理 H5 传递的数据
    }
}, "NativeBridge");

Uniapp H5 中通过 window.NativeBridge 调用：

window.NativeBridge.callNative("hello from uniapp");

三、iOS 原生 App 集成 Uniapp 流程

方案 1：通过 Uniapp SDK 深度集成

导入 SDK 到 Xcode 项目
- 解压 iOS SDK，将 SDK 目录下的 DCUniSDK.framework、liblibWeex.a 等文件拖拽到 Xcode 项目中（勾选“Copy items if needed”）。
- 在项目 Build Settings 中配置：
  - Framework Search Paths：添加 SDK 所在目录。
  - Other Linker Flags：添加 -ObjC（确保静态库中的分类被正确加载）。
配置 Uniapp 资源
- 将 HBuilderX 生成的 Uniapp 资源包（__UNI__XXX 文件夹）复制到 Xcode 项目的 Resources/apps 目录（需在 Xcode 中右键“Add Files to Project”）。
- 在 Resources/data 目录下创建 dcloud_control.xml，配置内容同 Android（appid 需匹配）。

加载 Uniapp 页面

在原生 ViewController 中初始化 SDK 并加载 Uniapp 页面：

#import <DCUniSDK/DCUniSDK.h>

@interface UniContainerViewController () <DCUniSDKDelegate>
@end

@implementation UniContainerViewController
- (void)viewDidLoad {
    [super viewDidLoad];
    // 初始化 SDK
    [DCUniSDK sharedInstance].delegate = self;
    // 加载 Uniapp 应用（appid 为 __UNI__XXX）
    [DCUniSDK sharedInstance].launchOptions = @{@"appid": @"__UNI__XXX"};
    [DCUniSDK sharedInstance] loadAppWithCompletion:^(BOOL success, NSError * _Nullable error) {
        if (success) {
            // 加载成功后获取 Uniapp 视图并添加到当前页面
            UIView *uniView = [DCUniSDK sharedInstance].rootView;
            uniView.frame = self.view.bounds;
            [self.view addSubview:uniView];
        }
    }];
}
@end

通信实现

Uniapp 调用原生：

原生端创建继承自 DCUniModule 的类，用 DC_EXPORT_METHOD 暴露方法：

#import <DCUniSDK/DCUniSDK.h>

@interface NativeModule : DCUniModule
DC_EXPORT_METHOD(@selector(openNativePage:callback:))
- (void)openNativePage:(NSString *)param callback:(DCUniJSCallback)callback;
@end

@implementation NativeModule
- (void)openNativePage:(NSString *)param callback:(DCUniJSCallback)callback {
    // 处理逻辑
    callback(@{@"result": [NSString stringWithFormat:@"处理：%@", param]});
}
@end

Uniapp 中调用方式同 Android：

const nativeModule = uni.requireNativePlugin('NativeModule');
nativeModule.openNativePage('test', (res) => {
          console.log(res); });

原生调用 Uniapp：
原生通过 postMessage 发送事件，Uniapp 监听：
```
[[DCUniSDK sharedInstance] postMessageToUniApp:@"nativeEvent" data:@{@"data": @"来自iOS原生"}];
```
Uniapp 监听方式同 Android。

方案 2：通过 WKWebView 轻量集成

类似 Android WebView 方案，使用 iOS 的 WKWebView 加载 Uniapp H5 资源，通过 WKScriptMessageHandler 实现通信：

// 初始化 WKWebView
WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
[config.userContentController addScriptMessageHandler:self name:@"NativeBridge"];
WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
[self.view addSubview:webView];

// 加载 H5 资源
NSURL *url = [[NSBundle mainBundle] URLForResource:@"index" withExtension:@"html" subdirectory:@"uniapp_h5"];
[webView loadRequest:[NSURLRequest requestWithURL:url]];

// 接收 H5 调用
- (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message {
    if ([message.name isEqualToString:@"NativeBridge"]) {
        NSDictionary *data = message.body; // 处理 H5 数据
    }
}

四、集成后的调试与打包

调试：
- Uniapp 端：在 HBuilderX 中通过“运行 → 运行到手机/模拟器”调试页面逻辑，结合 console.log 输出日志。
- 原生端：使用 Android Studio 的 Logcat 或 Xcode 的 Console 查看原生代码日志，通过断点调试通信逻辑。
- 混合调试：通过 Chrome DevTools（Android）或 Safari 开发者工具（iOS）调试 Uniapp 页面的 JS 代码。
打包：
- Android：生成签名 APK 或 App Bundle，需在 build.gradle 中配置签名信息。
- iOS：通过 Xcode 生成 IPA 文件，需配置正确的开发者证书和描述文件。

五、关键注意事项

权限一致性：Uniapp 中用到的权限（如相机、定位）需在原生 App 的配置文件中同步声明（Android 的 AndroidManifest.xml，iOS 的 Info.plist）。
版本兼容性：确保 Uniapp SDK 版本与 HBuilderX 版本匹配，避免因版本差异导致功能异常。
性能优化：减少频繁的 JS 与原生通信，大数据交互建议通过文件或内存共享实现；原生页面与 Uniapp 页面切换时注意释放资源，避免内存泄漏。
插件依赖：若 Uniapp 项目使用了原生插件（如地图、支付），需在原生项目中同步集成对应的插件 SDK。

通过以上流程，可实现 Uniapp 与原生 App 的深度融合，既保留 Uniapp 跨平台开发的效率，又能灵活扩展原生功能。

Uniapp与原生App集成的流程

一、集成前的准备工作

二、Android 原生 App 集成 Uniapp 流程

方案 1：通过 Uniapp SDK 深度集成（推荐，支持原生功能扩展）

方案 2：通过 WebView 轻量集成（适合简单页面嵌入）

三、iOS 原生 App 集成 Uniapp 流程

方案 1：通过 Uniapp SDK 深度集成

方案 2：通过 WKWebView 轻量集成

四、集成后的调试与打包

五、关键注意事项

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

Uniapp与原生App集成的流程

一、集成前的准备工作

二、Android 原生 App 集成 Uniapp 流程

方案 1：通过 Uniapp SDK 深度集成（推荐，支持原生功能扩展）

方案 2：通过 WebView 轻量集成（适合简单页面嵌入）

三、iOS 原生 App 集成 Uniapp 流程

方案 1：通过 Uniapp SDK 深度集成

方案 2：通过 WKWebView 轻量集成

四、集成后的调试与打包

五、关键注意事项

热门文章

最新文章

相关电子书