📋 前言
react-native-webview 是 React Native 社区最流行的 WebView 组件，提供了一套完整的网页加载和交互解决方案。它支持加载网络 URL、本地 HTML 文件、注入 JavaScript、处理网页事件等多种功能，并且完全兼容 Android、iOS 和 HarmonyOS 三端。
🎯 库简介
基本信息
- 库名称: @react-native-ohos/react-native-webview
- 版本信息:
13.10.5: 支持 RN 0.72 版本13.15.1: 支持 RN 0.77 版本
- 官方仓库: https://github.com/react-native-oh-library/react-native-webview
- 主要功能:
- 加载网络 URL 和本地 HTML
- 注入 JavaScript 代码
- 处理网页加载事件
- 网页与原生通信
- 支持多种配置选项
- 兼容 Android、iOS 和 HarmonyOS
- 兼容性验证:
- 鸿蒙化版本 13.10.4-rc.4 及之后需要 DevEco Studio 6.0.0 (API20) 及以上版本
为什么需要这个库？
- 功能完整: 提供完整的 WebView 功能
- 跨平台: 在三端提供一致的体验
- 易于使用: API 简单直观
- 性能优异: 原生实现，高效稳定
- 灵活配置: 支持多种配置选项
📦 安装步骤
1. 使用 npm 安装
根据您的 RN 版本选择对应的包名：
npm install @react-native-ohos/[email protected]
2. 验证安装
安装完成后，检查 package.json 文件，应该能看到新增的依赖：
{
"dependencies": {
"@react-native-ohos/react-native-webview": "^13.10.5-rc.1",
// ... 其他依赖
}
}
🔧 HarmonyOS 平台配置 ⭐
1. 在工程根目录的 oh-package.json5 添加 overrides 字段
首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony
打开 harmony/oh-package.json5，添加以下配置：
{
...
"overrides": {
"@rnoh/react-native-openharmony": "^0.72.90"
}
}
2. 引入原生端代码
方法一：通过 har 包引入（不推荐）
[!TIP] har 包位于三方库安装路径的
harmony文件夹下。
打开 entry/oh-package.json5，添加以下依赖：
"dependencies": {
"@rnoh/react-native-openharmony": "0.72.90",
"@react-native-ohos/react-native-webview": "file:../../node_modules/@react-native-ohos/react-native-webview/harmony/rn_webview.har"
}
点击右上角的 sync 按钮
或者在终端执行：
cd entry && ohpm install
方法二：直接链接源码
步骤 1: 把 <RN 工程>/node_modules/@react-native-ohos/react-native-webview/harmony 目录下的源码 rn_webview 复制到 harmony（鸿蒙壳工程）工程根目录下。
步骤 2: 在 harmony 工程根目录的 build-profile.template.json5（若存在）和 build-profile.json5 添加以下模块：
modules: [
...
{
name: 'rn_webview',
srcPath: './rn_webview'
}
]
步骤 3: 打开 rn_webview/oh-package.json5，修改 react-native-openharmony 和项目的版本一致。
步骤 4: 打开 entry/oh-package.json5，添加以下依赖：
"dependencies": {
"@rnoh/react-native-openharmony": "0.72.90",
"@react-native-ohos/react-native-webview": "file:../rn_webview"
}
步骤 5: 点击 DevEco Studio 右上角的 sync 按钮
3. 配置 CMakeLists 和引入 WebViewPackage
打开 entry/src/main/cpp/CMakeLists.txt，添加：
project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp")
set(CMAKE_ASM_FLAGS "-Wno-error:unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,noexecstack -s -fPIE -pie")
add_compile_definitions(WITH_HITRACE_SYSTRACE)
set(WITH_HITRACE_SYSTRACE 1)
# for other CMakeLists.txt files to use
add_subdirectory("${RNOH_CPP_DIR}" ./rn)
add_library(rnoh_app SHARED "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp" "./PackageProvider.cpp")
target_link_libraries(rnoh_app PUBLIC rnoh)
set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-webview/src/main/cpp" ./webview)
target_link_libraries(rnoh_app PUBLIC rnoh_webview)
打开 entry/src/main/cpp/PackageProvider.cpp，添加：
#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
#include "WebViewPackage.h"
using namespace rnoh;
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
return {
std::make_shared<RNOHGeneratedPackage>(ctx),
std::make_shared<SamplePackage>(ctx),
std::make_shared<WebViewPackage>(ctx)
};
}
4. 在 ArkTs 侧引入 WebView 组件
找到 function buildCustomComponent()，一般位于 entry/src/main/ets/pages/index.ets 或 entry/src/main/ets/rn/LoadBundle.ets，添加：
import { WebView, WEB_VIEW } from "@react-native-ohos/react-native-webview"
@Builder function buildCustomComponent(ctx: ComponentBuilderContext) {
if (ctx.componentName === WEB_VIEW) {
WebView({
ctx: ctx.rnComponentContext,
tag: ctx.tag
})
}
...
}
[!TIP] 本库使用了混合方案，需要添加组件名。
在 entry/src/main/ets/pages/index.ets 或 entry/src/main/ets/rn/LoadBundle.ets 找到常量 arkTsComponentNames 在其数组里添加组件名：
const arkTsComponentNames: Array<string> = [
WEB_VIEW
];
5. 在 ArkTs 侧引入 WebViewPackage
打开 entry/src/main/ets/RNPackagesFactory.ts，添加：
import { WebViewPackage } from '@react-native-ohos/react-native-webview/ts';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
return [
new SamplePackage(ctx),
new WebViewPackage(ctx)
];
}
6. 运行
点击右上角的 sync 按钮
或者在终端执行：
cd entry && ohpm install
然后编译、运行即可。
💻 完整代码示例
下面是一个完整的示例，展示了 react-native-webview 的各种使用场景：
import React, { useRef, useState } from 'react';
import { View, Text, StyleSheet, TouchableOpacity, TextInput, ScrollView, SafeAreaView, ActivityIndicator } from 'react-native';
import { WebView, WebViewNavigation } from 'react-native-webview';
function WebViewDemo() {
const webViewRef = useRef(null);
const [url, setUrl] = useState('https://reactnative.dev/');
const [canGoBack, setCanGoBack] = useState(false);
const [canGoForward, setCanGoForward] = useState(false);
const [loading, setLoading] = useState(false);
const [currentUrl, setCurrentUrl] = useState('');
const [error, setError] = useState(null);
const [progress, setProgress] = useState(0);
const handleGoBack = () => {
if (webViewRef.current && webViewRef.. === ) {
webViewRef..();
}
};
= () => {
(webViewRef. && webViewRef.. === ) {
webViewRef..();
}
};
= () => {
webViewRef.?.();
};
= () => {
webViewRef.?.();
};
= () => {
{
data = .(event..);
.(, data);
} (e) {
.(, event..);
}
};
= () => {
(url.()) {
();
}
};
= () => {
();
();
};
(
);
}
styles = .({
: {
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
},
: {
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
},
: {
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
: ,
},
: {
: ,
: ,
: ,
},
});
;
🎨 实际应用场景
react-native-webview 可以应用于以下实际场景：
- 混合开发: 在原生应用中嵌入 H5 页面
- 在线文档: 查看 PDF、Word 等在线文档
- 第三方登录: 集成微信、支付宝等第三方登录
- 内容展示: 展示富文本、图表等复杂内容
- 广告展示: 加载第三方广告页面
⚠️ 注意事项与最佳实践
1. 网络权限配置
在使用 WebView 之前，需要在 HarmonyOS 的 module.json5 中配置网络权限：
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]
}
}
2. 重要属性配置
// ✅ 推荐：启用声音播放
<WebView ignoreSilentHardwareSwitch={true} />
// ✅ 推荐：启用 JavaScript
<WebView javaScriptEnabled={true} domStorageEnabled={true} />
// ✅ 推荐：处理加载状态
<WebView startInLoadingState={true} onLoadStart={() => setLoading(true)} onLoadEnd={() => setLoading(false)} />
3. JavaScript 注入
// ✅ 推荐：页面加载完成后注入
<WebView onLoad={() => {
webViewRef.current?.injectJavaScript(`
// 你的 JavaScript 代码
true;
`);
}}/>
// ✅ 推荐：页面加载前注入
<WebView injectedJavaScriptBeforeContentLoaded={`
// 在页面加载前执行的 JavaScript 代码
`} />
4. 网页与原生通信
// 在网页中发送消息
window.ReactNativeWebView.postMessage(JSON.stringify({ type: 'message', data: 'hello from web' }));
// 在 React Native 中接收消息
<WebView onMessage={(event) => {
const data = JSON.parse(event.nativeEvent.data);
console.log('收到消息:', data);
}} />
5. 性能优化
// ✅ 推荐：启用缓存
<WebView cacheEnabled={true} />
// ✅ 推荐：清除缓存
webViewRef.current?.clearCache(true);
// ✅ 推荐：减少不必要的渲染
6. HarmonyOS 特殊处理
在 HarmonyOS 上，需要注意：
- 声音播放:
ignoreSilentHardwareSwitch需要设置为true，网页播放才有声音 - 编译版本: 需要使用 DevEco Studio 6.0.0 (API20) 及以上版本
- 部分属性: 部分属性 HarmonyOS 暂不支持
- 混合方案: 需要在 ArkTs 侧添加组件名和 WebView 组件
🧪 测试验证
1. Android 平台测试
npm run android
测试要点:
- 测试网页加载
- 测试导航功能
- 验证 JavaScript 注入
- 检查音频播放
2. iOS 平台测试
npm run ios
测试要点:
- 测试网页加载质量
- 验证 JavaScript 执行
- 测试通信功能
- 检查缓存机制
3. HarmonyOS 平台测试
npm run harmony
测试要点:
- 验证网页加载功能
- 测试声音播放（需要设置 ignoreSilentHardwareSwitch）
- 检查 JavaScript 注入
- 验证网页与原生通信
4. 常见问题排查
问题 1: 网页无法加载
- 检查网络权限配置
- 确认 URL 是否正确
- 验证网络连接
问题 2: 音频没有声音
- 确认
ignoreSilentHardwareSwitch设置为true - 检查设备音量设置
- 验证音频文件格式
问题 3: JavaScript 不执行
- 确认
javaScriptEnabled设置为true - 检查 JavaScript 代码语法
- 验证注入时机
📊 对比：原生 WebView vs react-native-webview
| 特性 | 原生 WebView | react-native-webview |
|---|---|---|
| 跨平台一致性 | ❌ | ✅ 完全一致 |
| API 简洁性 | ⚠️ 复杂 | ✅ 简洁 |
| JavaScript 注入 | ✅ 支持 | ✅ 支持 |
| 网页通信 | ⚠️ 复杂 | ✅ 简单 |
| 导航控制 | ✅ 完整 | ✅ 完整 |
| 缓存管理 | ✅ 完整 | ✅ 完整 |
📝 总结
通过集成 react-native-webview，我们为项目添加了强大的 WebView 功能。这个库提供了完整的网页加载和交互解决方案，支持多种配置选项，并且完全跨平台兼容。
关键要点回顾
- ✅ 安装依赖:
npm install @react-native-ohos/react-native-webview - ✅ 配置平台: 通过 har 包或直接链接源码，配置 CMakeLists.txt、PackageProvider.cpp、RNPackagesFactory.ts 和 buildCustomComponent
- ✅ 集成代码: 使用
WebView组件 - ✅ 支持功能: 加载 URL、注入 JS、网页通信、导航控制等
- ✅ 重要: 本库使用了混合方案，需要在 ArkTs 侧添加组件名和 WebView 组件
- ✅ 注意: ignoreSilentHardwareSwitch 需要设置为 true，网页播放才有声音
实际效果
- Android: 原生 WebView 体验
- iOS: 高质量的 WebView 体验
- HarmonyOS: 一致的 WebView 体验
已知限制
- ⚠️ 部分属性 HarmonyOS 暂不支持
- ⚠️ 需要使用 DevEco Studio 6.0.0 (API20) 及以上版本
- ⚠️ 中文乱码问题已修复
- ⚠️ 部分属性未实现 HarmonyOS 化
遗留问题
- webview 部分属性未实现 HarmonyOS 化
- webview 部分属性未实现 HarmonyOS 化
- 中文乱码（已修复）
希望这篇教程能帮助你顺利集成 react-native-webview，构建出色的 WebView 体验！
