Cordova 开发鸿蒙应用完全指南

Cordova 开发鸿蒙应用完全指南

使用 Cordova-OpenHarmony 将您的 Cordova 应用移植到华为鸿蒙系统

---

📋 目录

• 前置要求
• 集成步骤
  • [步骤 1：创建鸿蒙项目](#步骤 1：创建鸿蒙项目)
  • [步骤 2：集成 Cordova HAR 包](#步骤 2：集成 Cordova HAR 包)
  • [步骤 3：配置项目依赖](#步骤 3：配置项目依赖)
  • [步骤 4：迁移 Android 项目资源](#步骤 4：迁移 Android 项目资源)
  • [步骤 5：配置主页面](#步骤 5：配置主页面)
  • [步骤 6：初始化 WebView 引擎](#步骤 6：初始化 WebView 引擎)
  • [步骤 7：编译运行](#步骤 7：编译运行)
• 目录结构说明
• 常见问题
• 进阶配置

---

🔧 前置要求

在开始之前，请确保您已准备好以下环境：

工具	版本要求	说明
DevEco Studio	最新版本	华为官方 IDE
HarmonyOS SDK	API 9+	鸿蒙操作系统 SDK
Node.js	14.x 或更高	用于包管理
ohpm	内置于 DevEco	鸿蒙包管理器

前置知识：

• ✅ 熟悉 Cordova 基础开发
• ✅ 了解 ArkTS 语法（鸿蒙开发语言）
• ✅ 有 Android 或 iOS 移动开发经验

---

🚀 集成步骤

步骤 1：创建鸿蒙项目

1.1 打开 DevEco Studio

启动 DevEco Studio，选择创建新项目。

1.2 选择项目模板

在项目模板中选择 Empty Ability（空白模板）：

1.3 配置项目信息

点击 Next 进入下一步，填写以下必要信息：

字段	说明	示例
Project name	项目名称	MyCordovaApp
Bundle name	包名（反向域名格式）	com.example.mycordovaapp
Save location	项目保存路径	选择合适的目录
Language	开发语言	ArkTS

填写完成后，点击 Finish 完成项目创建。

💡 提示：项目创建完成后，DevEco Studio 会自动进行初始化和同步。

---

步骤 2：集成 Cordova HAR 包

2.1 下载 Cordova HAR 工程

从官方或指定渠道下载 cordova-openharmony HAR 包工程。

2.2 解压并重命名

1. 解压下载的 HAR 包
2. 将顶级目录重命名为 cordova
3. 将整个 cordova 文件夹复制到主工程的根目录

目录结构示例：

MyCordovaApp/
├── entry/               # 主应用模块
├── cordova/             # ← Cordova HAR 包（新添加）
├── oh_modules/
└── build-profile.json5

完成后，在 DevEco Studio 的项目面板中应该能看到 cordova 模块：

---

步骤 3：配置项目依赖

3.1 安装依赖

打开 DevEco Studio 的 Terminal（终端），执行以下命令：

# 进入 entry 目录
cd entry

# 安装 cordova 依赖
ohpm install ../cordova

3.2 修改构建配置

打开项目根目录的 build-profile.json5 文件，在 modules 节点中添加 Cordova 模块配置：

{
  "app": {
    "products": [
      // ... 现有配置
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry"
    },
    // ⬇️ 添加以下配置
{
      "name": "cordova",
      "srcPath": "./cordova"
    }
  ]
}

✅ 完成标记：至此，Cordova HAR 源码包已成功集成到主工程中。

---

步骤 4：迁移 Android 项目资源

如果您是从现有的 Android Cordova 项目迁移，需要复制 Web 资源文件。

4.1 复制资源文件

将 Android 项目的 assets 目录下的所有文件复制到鸿蒙工程的以下路径：

entry/src/main/resources/rawfile/

4.2 必需的文件结构

确保 rawfile 目录包含以下必需文件和目录：

rawfile/
└── www/                        ← 必需目录
    ├── index.html             ← 必需文件（应用入口）
    ├── cordova.js             ← 必需文件（Cordova 核心）
    ├── cordova_plugins.js     ← 必需文件（插件配置）
    ├── plugins/               ← 必需目录（插件代码）
    ├── css/                   ← 可选（样式文件）
    │   └── index.css
    ├── js/                    ← 可选（业务逻辑）
    │   └── index.js
    └── img/                   ← 可选（图片资源）

4.3 文件说明

文件/目录	是否必需	说明
www/	✅ 必需	Web 应用根目录
index.html	✅ 必需	应用主页面
cordova.js	✅ 必需	Cordova 框架核心文件
cordova_plugins.js	✅ 必需	插件注册配置
plugins/	✅ 必需	插件实现代码
css/, js/, img/	⚠️ 可选	应用资源文件

⚠️ 注意 ：如果要指定加载自定义页面（非默认 index.html），请参考进阶配置部分。

4.4 安装鸿蒙版插件

复制文件后，还需要安装 Android 项目中使用的插件的鸿蒙版本。请参考各插件的鸿蒙版本文档进行安装。

---

步骤 5：配置主页面

5.1 修改 Index.ets 文件

打开主页面文件：

entry/src/main/ets/pages/Index.ets

5.2 替换页面代码

将以下代码完整复制到 Index.ets 文件中：

import { 
  MainPage, 
  pageBackPress, 
  pageHideEvent, 
  pageShowEvent, 
  PluginEntry 
} from '@magongshou/harmony-cordova/Index';

// 如果有自定义插件，取消下面的注释并导入
// import { TestPlugin } from "../plugins/TestPlugin"

@Entry
@Component
struct Index {
  /**
   * ArkTS 侧的自定义插件配置
   * 配置插件名称和对象，详见自定义插件开发部分
   */
  cordovaPlugs: Array<PluginEntry> = [];
  
  // 自定义插件配置示例（如需使用，取消下面的注释）
  /*
  cordovaPlugs: Array<PluginEntry> = [
    {
      pluginName: 'TestPlugin',        // 插件名称
      pluginObject: new TestPlugin()   // 实例化插件对象
      }
  ];
  */

  /**
   * 页面显示生命周期
   * 通知 Cordova 页面已显示
   */
  onPageShow() {
    pageShowEvent();
  }

  /**
   * 返回键拦截
   * 由 Cordova 处理返回键逻辑
   */
  onBackPress() {
    pageBackPress();
    return true;  // 返回 true 拦截默认行为
  }

  /**
   * 页面隐藏生命周期
   * 通知 Cordova 页面已隐藏
   */
  onPageHide() {
    pageHideEvent();
  }

  /**
   * 构建页面 UI
   */
  build() {
    RelativeContainer() {
      // 默认加载 rawfile/www/index.html
      // 自定义加载页面请参考进阶功能部分
      MainPage({ 
        isWebDebug: false,           // 是否开启 Web 调试
        cordovaPlugs: this.cordovaPlugs  // 传入插件配置
      });
    }
    .height('100%')
    .width('100%')
  }
}

5.3 代码说明

方法/属性	说明
cordovaPlugs	自定义插件数组，用于注册 ArkTS 插件
onPageShow()	页面显示时触发，通知 Cordova
onBackPress()	拦截返回键，交由 Cordova 处理
onPageHide()	页面隐藏时触发，通知 Cordova
MainPage	Cordova 主组件，加载 Web 应用
isWebDebug	是否开启 Web 调试（开发阶段可设为 true）

---

步骤 6：初始化 WebView 引擎

6.1 修改 EntryAbility.ets 文件

打开应用入口文件：

entry/src/main/ets/entryAbility/EntryAbility.ets

6.2 添加必要导入

在文件顶部添加以下导入语句：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { webview } from '@kit.ArkWeb';  // ← 引入 webview 模块
import { ConfigurationConstant } from '@kit.AbilityKit';  // ← 添加此行

6.3 修改 onCreate 方法

找到 onCreate 方法，修改为以下代码：

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // 设置应用颜色模式（跟随系统）
  try {
    this.context
      .getApplicationContext()
      .setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
  } catch (err) {
    hilog.error(
      DOMAIN, 
      'testTag', 
      'Failed to set colorMode. Cause: %{public}s', 
      JSON.stringify(err)
    );
  }
  
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
  
  // ⭐ 重要：初始化 WebView 引擎
  webview.WebviewController.initializeWebEngine();
}

🔑 关键步骤 ：webview.WebviewController.initializeWebEngine() 必须在应用启动时调用，用于初始化 WebView 引擎。

6.4 完整的 EntryAbility.ets 示例

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { webview } from '@kit.ArkWeb';
import { ConfigurationConstant } from '@kit.AbilityKit';

const DOMAIN = 0x0001;  // 日志域标识

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      this.context
        .getApplicationContext()
        .setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    } catch (err) {
      hilog.error(
        DOMAIN, 
        'testTag', 
        'Failed to set colorMode. Cause: %{public}s', 
        JSON.stringify(err)
      );
    }
    
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
    webview.WebviewController.initializeWebEngine();
  }

  onDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(
          DOMAIN,
          'testTag',
          'Failed to load the content. Cause: %{public}s',
          JSON.stringify(err) ?? ''
        );
        return;
      }
      hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
    });
  }

  onWindowStageDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
  }
}

---

步骤 7：编译运行

7.1 选择运行目标

在 DevEco Studio 顶部工具栏选择运行目标：

📱 真机：连接鸿蒙设备并开启 USB 调试

🖥️ 模拟器：使用鸿蒙模拟器（需预先配置）

7.4 验证运行

应用启动后，您应该看到：

• ✅ Cordova 应用正常加载
• ✅ index.html 页面正确显示
• ✅ JavaScript 逻辑正常执行
• ✅ Cordova 插件可正常调用

🎉 恭喜：鸿蒙移植已经完成！现在您可以在鸿蒙设备上运行 Cordova 应用了。

---

📁 目录结构说明

完成所有步骤后，您的项目结构应该如下：

MyCordovaApp/
├── entry/                              # 主应用模块
│   ├── src/
│   │   └── main/
│   │       ├── ets/                    # ArkTS 源代码
│   │       │   ├── entryAbility/
│   │       │   │   └── EntryAbility.ets  # 应用入口（已修改）
│   │       │   └── pages/
│   │       │       └── Index.ets         # 主页面（已修改）
│   │       └── resources/
│   │           └── rawfile/            # Web 资源目录
│   │               └── www/            # Cordova Web 应用
│   │                   ├── index.html
│   │                   ├── cordova.js
│   │                   ├── cordova_plugins.js
│   │                   ├── plugins/
│   │                   ├── css/
│   │                   ├── js/
│   │                   └── img/
│   ├── build-profile.json5
│   └── oh-package.json5
├── cordova/                            # Cordova HAR 包（新增）
│   └── ...
├── oh_modules/                         # 鸿蒙依赖模块
├── build-profile.json5                 # 项目构建配置（已修改）
└── oh-package.json5                    # 项目依赖配置

---

❓ 常见问题

问题 1：找不到 cordova 模块

症状 ：编译时提示找不到 @magongshou/harmony-cordova

解决方案：

1. 确认已执行 ohpm install ../cordova
2. 检查 build-profile.json5 中是否添加了 cordova 模块配置
3. 尝试清理项目：Build → Clean Project
4. 重新同步：File → Sync and Refresh Project

问题 2：WebView 无法加载页面

症状：应用启动后显示空白页面

可能原因和解决方案：

1. 未初始化 WebView 引擎

   • 检查 EntryAbility.ets 中是否调用了 webview.WebviewController.initializeWebEngine()

2. 资源文件路径错误

   • 确认 www 目录位于 entry/src/main/resources/rawfile/ 下
   • 检查 index.html 文件是否存在

3. 文件权限问题

   • 确保 rawfile 目录下的所有文件具有读取权限

问题 3：插件调用失败

症状：JavaScript 调用 Cordova 插件时报错

解决方案：

1. 确认插件的鸿蒙版本已正确安装
2. 检查 cordova_plugins.js 中是否正确注册了插件
3. 确保在 deviceready 事件后调用插件
4. 查看 DevEco Studio 的日志输出

问题 4：返回键无效

症状：按返回键无反应或直接退出应用

解决方案：

• 确认 Index.ets 中的 onBackPress() 方法返回了 true
• 检查是否正确调用了 pageBackPress()

问题 5：ohpm install 失败

症状 ：执行 ohpm install ../cordova 时报错

解决方案：

1. 检查网络连接
2. 确认 cordova 目录路径正确
3. 尝试清理缓存：ohpm cache clean
4. 检查 DevEco Studio 版本是否为最新

---

🚀 进阶配置

自定义加载页面

如果不想使用默认的 index.html，可以指定自定义页面：

// 在 Index.ets 中
MainPage({ 
  isWebDebug: false,
  cordovaPlugs: this.cordovaPlugs,
  startPath: 'rawfile/www/custom.html'  // ← 自定义页面路径
});

开启 Web 调试

开发阶段建议开启 Web 调试模式：

MainPage({ 
  isWebDebug: true,  // ← 设置为 true
  cordovaPlugs: this.cordovaPlugs
});

开启后可以使用 Chrome DevTools 进行远程调试。

添加自定义插件

1. 创建插件类

在 entry/src/main/ets/plugins/ 目录下创建插件文件：

// TestPlugin.ets
import { CordovaPlugin } from '@magongshou/harmony-cordova';

export class TestPlugin extends CordovaPlugin {
  execute(action: string, args: Array<any>, callbackId: string): boolean {
    if (action === 'echo') {
      const message = args[0];
      this.success(callbackId, message);
      return true;
    }
    return false;
  }
}

2. 在 Index.ets 中注册插件

import { TestPlugin } from "../plugins/TestPlugin";

@Entry
@Component
struct Index {
  cordovaPlugs: Array<PluginEntry> = [
    {
      pluginName: 'TestPlugin',
      pluginObject: new TestPlugin()
    }
  ];
  // ... 其他代码
}

3. 在 JavaScript 中调用

// 在 www/js/index.js 中
cordova.exec(
  function(result) {
    console.log('Success:', result);
  },
  function(error) {
    console.error('Error:', error);
  },
  'TestPlugin',  // 插件名称
  'echo',        // 方法名
  ['Hello from HarmonyOS!']  // 参数
);

配置应用权限

在 entry/src/main/module.json5 中添加所需权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.CAMERA"
      },
      {
        "name": "ohos.permission.READ_MEDIA"
      },
      {
        "name": "ohos.permission.WRITE_MEDIA"
      },
      {
        "name": "ohos.permission.LOCATION"
      }
    ]
  }
}

---

📚 总结

通过本指南，您已经学会了：

✅ 在 DevEco Studio 中创建鸿蒙项目

✅ 集成 Cordova-OpenHarmony HAR 包

✅ 配置项目依赖和构建脚本

✅ 迁移 Android Cordova 项目资源

✅ 配置主页面和应用入口

✅ 编译运行鸿蒙 Cordova 应用

✅ 处理常见问题

✅ 进行高级配置和自定义插件开发

下一步

• 🔌 探索更多鸿蒙版 Cordova 插件
• 🎨 优化应用 UI 适配鸿蒙设计规范
• 📱 测试应用在不同鸿蒙设备上的兼容性
• 🚀 准备发布到华为应用市场

---

🔗 相关资源

• HarmonyOS 开发者官网
• DevEco Studio 下载
• Apache Cordova 官方文档
• ArkTS 语言参考

---

作者 : 坚果
更新日期 : 2025年11月7日
版本 : 2.0
许可证: Apache-2.0

---

让 Cordova 应用在鸿蒙上焕发新生！🌟