React Native 鸿蒙化集成 react-native-webview 实战

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 && typeof webViewRef.current.goBack === 'function') {
      webViewRef.current.goBack();
    }
  };

  const handleGoForward = () => {
    if (webViewRef.current && typeof webViewRef.current.goForward === 'function') {
      webViewRef.current.goForward();
    }
  };

  const handleReload = () => {
    webViewRef.current?.reload();
  };

  const handleLoad = () => {
    webViewRef.current?.injectJavaScript(`
      (function() {
        window.ReactNativeWebView.postMessage(JSON.stringify({ type: 'pageInfo', title: document.title, url: window.location.href }));
      })();
      true;
    `);
  };

  const handleMessage = (event) => {
    try {
      const data = JSON.parse(event.nativeEvent.data);
      console.log('收到网页消息:', data);
    } catch (e) {
      console.log('收到网页消息:', event.nativeEvent.data);
    }
  };

  const loadUrl = () => {
    if (url.trim()) {
      setError(null);
    }
  };

  const useDefaultUrl = () => {
    setUrl('https://reactnative.dev/');
    setError(null);
  };

  return (
    <SafeAreaView style={styles.container}>
      <View style={styles.container}>
        {/* 顶部工具栏 */}
        <View style={styles.toolbar}>
          <TouchableOpacity
            style={[styles.navButton, !canGoBack && styles.disabledButton]}
            onPress={handleGoBack}
            disabled={!canGoBack}
          >
            <Text style={styles.navButtonText}>←</Text>
          </TouchableOpacity>
          <TouchableOpacity
            style={[styles.navButton, !canGoForward && styles.disabledButton]}
            onPress={handleGoForward}
            disabled={!canGoForward}
          >
            <Text style={styles.navButtonText}>→</Text>
          </TouchableOpacity>
          <TouchableOpacity style={styles.navButton} onPress={handleReload}>
            <Text =>↻
          
          
          
            前往
          
        
        {/* 进度条 */}
        {loading && progress > 0 && progress < 1 && (
          
            
          
        )}
        {/* 错误提示 */}
        {error && (
          
            {error}
          
        )}
        {/* WebView */}
        
          {loading && (
            
              
              加载中...
            
          )}
           {
              setCanGoBack(navState.canGoBack);
              setCanGoForward(navState.canGoForward);
              setCurrentUrl(navState.url);
            }}
            onLoadStart={() => {
              setLoading(true);
              setError(null);
            }}
            onLoadEnd={() => {
              setLoading(false);
              setTimeout(() => {
                handleLoad();
              }, 100);
            }}
            onLoadProgress={({ nativeEvent }) => {
              setProgress(nativeEvent.progress);
            }}
            onHttpError={(syntheticEvent) => {
              const { nativeEvent } = syntheticEvent;
              setError(`HTTP 错误：${nativeEvent.statusCode}`);
              setLoading(false);
            }}
            onError={(syntheticEvent) => {
              const { nativeEvent } = syntheticEvent;
              setError(`加载错误：${nativeEvent.description}`);
              setLoading(false);
            }}
            onMessage={handleMessage}
            injectedJavaScriptBeforeContentLoaded={`
              window.addEventListener('load', function() {
                window.ReactNativeWebView.postMessage(JSON.stringify({ type: 'loaded', timestamp: new Date().toISOString() }));
              });
            `}
            ignoreSilentHardwareSwitch={true}
          />
        
        {/* 当前 URL 显示 */}
        {currentUrl && (
          
            当前页面:
            {currentUrl}
          
        )}
        {/* 功能按钮 */}
        
          
            React Native 官网
          
           {
              webViewRef.current?.injectJavaScript(` alert('这是一个来自 React Native 的注入消息！'); true; `);
            }}
          >
            注入 JS
          
           {
              if (webViewRef.current && typeof webViewRef.current.clearCache === 'function') {
                webViewRef.current.clearCache(true);
              }
            }}
          >
            清除缓存
          
        
        {/* 说明 */}
        
          功能说明：
           • 支持加载网络 URL 和本地 HTML 文件 
           • 支持注入 JavaScript 代码 
           • 支持网页与原生通信 
           • 支持前进、后退、刷新等导航功能 
           • 支持加载进度显示 
           • 支持错误处理 
        
        {/* 注意事项 */}
        
          注意事项：
           • ignoreSilentHardwareSwitch 需要设置为 true，网页播放才有声音 
           • 需要配置网络权限才能访问网络 
           • 部分属性 HarmonyOS 暂不支持 
           • 编译需要 DevEco Studio 6.0.0(API20) 及以上版本 
        
      
    
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#f5f5f5',
  },
  toolbar: {
    flexDirection: 'row',
    alignItems: 'center',
    padding: 10,
    backgroundColor: '#fff',
    borderBottomWidth: 1,
    borderBottomColor: '#e0e0e0',
    gap: 5,
  },
  navButton: {
    width: 40,
    height: 40,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#f5f5f5',
    borderRadius: 8,
  },
  disabledButton: {
    opacity: 0.3,
  },
  navButtonText: {
    fontSize: 20,
    fontWeight: 'bold',
    color: '#333',
  },
  urlInput: {
    flex: 1,
    height: 40,
    borderWidth: 1,
    borderColor: '#ddd',
    borderRadius: 8,
    paddingHorizontal: 10,
    backgroundColor: '#f9f9f9',
    fontSize: 14,
  },
  goButton: {
    paddingHorizontal: 15,
    paddingVertical: 8,
    backgroundColor: '#42a5f5',
    borderRadius: 8,
  },
  goButtonText: {
    color: '#fff',
    fontSize: 14,
    fontWeight: 'bold',
  },
  progressBarContainer: {
    height: 2,
    backgroundColor: '#e0e0e0',
  },
  progressBar: {
    height: '100%',
    backgroundColor: '#42a5f5',
  },
  errorContainer: {
    padding: 10,
    backgroundColor: '#ffebee',
    borderBottomWidth: 1,
    borderBottomColor: '#ffcdd2',
  },
  errorText: {
    color: '#c62828',
    fontSize: 14,
    textAlign: 'center',
  },
  webviewContainer: {
    flex: 1,
    backgroundColor: '#fff',
  },
  webview: {
    flex: 1,
  },
  loadingContainer: {
    position: 'absolute',
    top: 0,
    left: 0,
    right: 0,
    bottom: 0,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: 'rgba(255, 255, 255, 0.8)',
  },
  loadingText: {
    marginTop: 10,
    fontSize: 16,
    color: '#666',
  },
  urlDisplay: {
    padding: 10,
    backgroundColor: '#fff',
    borderBottomWidth: 1,
    borderBottomColor: '#e0e0e0',
  },
  urlLabel: {
    fontSize: 12,
    color: '#666',
    marginBottom: 5,
  },
  urlText: {
    fontSize: 14,
    color: '#333',
  },
  buttonContainer: {
    flexDirection: 'row',
    flexWrap: 'wrap',
    padding: 10,
    gap: 10,
    backgroundColor: '#fff',
    borderBottomWidth: 1,
    borderBottomColor: '#e0e0e0',
  },
  actionButton: {
    paddingHorizontal: 15,
    paddingVertical: 10,
    backgroundColor: '#42a5f5',
    borderRadius: 8,
    minWidth: 100,
    alignItems: 'center',
  },
  actionButtonText: {
    color: '#fff',
    fontSize: 14,
    fontWeight: '500',
  },
  infoSection: {
    margin: 10,
    padding: 15,
    backgroundColor: '#e3f2fd',
    borderRadius: 8,
    borderLeftWidth: 4,
    borderLeftColor: '#42a5f5',
  },
  infoTitle: {
    fontSize: 14,
    fontWeight: 'bold',
    marginBottom: 8,
    color: '#1565c0',
  },
  infoText: {
    fontSize: 13,
    color: '#1976d2',
    marginBottom: 4,
  },
  noteSection: {
    margin: 10,
    padding: 15,
    backgroundColor: '#fff3cd',
    borderRadius: 8,
    borderLeftWidth: 4,
    borderLeftColor: '#ffc107',
  },
  noteTitle: {
    fontSize: 14,
    fontWeight: 'bold',
    marginBottom: 8,
    color: '#856404',
  },
  noteText: {
    fontSize: 13,
    color: '#856404',
    marginBottom: 4,
  },
});

export default WebViewDemo;

实际应用场景

react-native-webview 可以应用于以下实际场景：

1. 混合开发: 在原生应用中嵌入 H5 页面
2. 在线文档: 查看 PDF、Word 等在线文档
3. 第三方登录: 集成微信、支付宝等第三方登录
4. 内容展示: 展示富文本、图表等复杂内容
5. 广告展示: 加载第三方广告页面

注意事项与最佳实践

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

总结

通过集成 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 体验！