HarmonyOS 应用开发指南（二）

Dan_2024-01-10 14:20

认识 HarmonyOS 应用工程结构

面向开发者，HarmonyOS 推出了 DevEco Studio 和 Dev Device Tool 两款开发工具，前者目前迭代至 3.1 版本（对外开放版本），用于开发 HarmonyOS 应用；后者用于开发智能设备

下面将以开源的 HarmonyOS 应用 "Today 新闻客户端" 为例介绍 HarmonyOS 应用工程结构。

应用工程目录

应用的工程主体结构如上图，可以忽略掉上图中 file、Users 和 Volumes 目录，这几个和项目无关。

  • AppScope 目录 包含一个 app.json5 文件和 resources 文件夹。

    • app.json5 用来配置应用的 bundle 名称（可以理解为应用包名）、bundleType 可以设置为 app 和 atomicService，用于标识应用是普通应用或元服务；其他信息主要是应用的版本信息、SDK 支持版本、应用图标和名称、设备特殊配置以及是否支持多工程联合开发等

    • resources 目录 存放公共类型资源文件，module 中 media 的图片 icon 资源不能和该目录下 media 中的 icon 重名

  • entry 目录是当前工程中的一个 module，一个工程允许包含一个 entry 类型 module 和 多个 feature 类型module，前者表示是应用的主模块，后者是应用的动态特性模块；该目录下包含了这个module所有的代码、文本、多媒体、图片、配置等各种资源；

  • hvigor 目录：hvigor 是一款基于任务管理机制实现的一套自动化构建工具（基于TypeScript + npm 包管理机制实现的轻量化前端构建工具），HarmonyOS 在迭代时，使用它替代 Gradle。该目录下有2个配置文件：

    • hvigor-config.json5：会以插件形式引入 hvigor 构建工具并且标识其版本；

    • hvigor-wrapper.js：是一个 js 脚本文件，与 hvigor相关的包装器

  • build-profile.json5：是应用的构建配置脚本，其中配置了应用签名信息、编译和适配 SDK 版本，构建产物以及多个 module 信息，在这里还可以配置不同 module 的多 target 构建信息

  • hvigorfile.ts：应用级的编译构建人物脚本

  • hvigorw 和 hvigorw.bat： Hvigor 构建工具的可执行文件和批处理文件

  • local.properties：项目的私有属性配置文件，默认会配置 nodejs 的安装目录以及 harmonyOS SDK；

  • oh-package.json5：用于编译和构建项目，内部配置了模块级的依赖文件（即三方库声明文件的入口和包名）

  • oh-package-lock.json5：是一个树形结构文件，用于描述项目依赖关系。文件包含了项目的所有依赖项和它们的版本信息。通过该文件，可以确保项目在不同环境中的构建一致性，并避免潜在的版本冲突问题。

  • oh_modules：用于存放三方库依赖信息

注：在DevEco Studio 3.1 Beta2上新建API 9及以上版本的工程使用了 ohpm作为默认包管理器

Module 目录

module 模块编译后会生成一个 HAP 安装文件。

  • src：目录存放模块代码、多媒体、图片、字符串等资源文件

    • src > main > ets：源代码目录

    • src > main > resources ：存放应用运行中使用到的各种资源文件

  • module.json5：模块的配置文件，涵盖以下信息：模块中各种 Ability 组件、需要申请的权限、模块类型、主 Ability以及入口页面的配置等

  • oh-package.json5：module级别, 配置三方包声明文件的入口及包名

  • build-profile.json5：配置当前模块的构建参数:如 编程模型类型/so 文件过滤规则/native(cpp) 开发编译配置/多目标构建产物等相关配置;

  • hvigorfile.ts：模块级别任务构建脚本

HarmonyOS 应用程序包结构

HarmonyOS 应用/服务的发布形态是 APP Pack(Application Package)，由至少1个 HAP(Harmony Ability Package) 包和描述 App Pack 属性的 pack.info 组成，pack.info 描述了应用包的 版本、bundleName、modules、abilties 以及应用支持的设备类型等信息。

一个 HAP 对应一个 Module，HarmonyOS 的 module 分为 entry 主应用/服务模块和 Feature 动态特性模块。

一个APP中，对于同一类型的设备，可以包含一个或多个Entry类型的HAP，如果同一类型的设备包含多个Entry模块，需要配置distroFilter分发规则，使得应用市场在做应用的云端分发时，对该设备类型下不同规格的设备进行分发。
一个APP可以包含零到多个Feature类型的HAP。只有包含Ability的HAP才能够独立运行。

Stage 模型的应用包结构：

HarmonyOS 应用配置

编译构建是将应用/服务的源代码、资源、第三方库等，通过编译工具转换为可直接在硬件设备上运行的二进制机器码，然后再将二进制机器码封装为HAP/APP软件包，并为HAP/APP包进行签名的过程。

HAP是可以直接运行在模拟器或真机设备中的软件包；

APP则是用于应用/服务上架到华为应用市场，华为应用市场在分发应用包时以 HAP 为单位进行分发。

HarmonyOS API Version 8 ~ 9 采用 Hvigor构建工具和构建插件（hvigor-ohos-plugin）组成，该插件利用Hvigor的任务编排机制实现应用/服务构建任务流的执行，完成HAP/APP的构建打包，应用于应用/服务的构建。使用该插件需要在 hvigor 目录下 hvigor-config.json5 中配置。

json5 复制代码 
{
  "hvigorVersion": "2.2.1",
  "dependencies": {
        "@ohos/hvigor-ohos-plugin": "2.2.1"
  }
}

Module 配置文件

module.json5：

json5 复制代码 
{
  "module": {
    "name": "entry", //module 名称 
    "type": "entry", // module 类型，另外一种是 feature
    "description": "$string:module_desc",
    "mainElement": "EntryAbility", //主 UIAbility 配置
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "srcEntry": "./ets/abilitystage/NewsAbilityStage.ts", //AbilityStage 的路径配置
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages", // 应用中页面的配置
    "virtualMachine": "ark",
    "abilities": [ // module 中所有的 UIAbility 
      {
        "name": "EntryAbility",
        //开发者定义的UIAbility 的路径配置
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:ic_news",
        "orientation": "auto_rotation",
        "launchType": "singleton",
        "supportWindowMode": [
          "floating",
          "fullscreen",
          "split"
        ],
        "label": "$string:app_name",
        "startWindowIcon": "$media:ic_news",
        "startWindowBackground": "$color:primaryRed",
        "exported": true,
        //该标签标识UIAbility组件或者ExtensionAbility组件能够接收的Want的特征
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],
    // 应用中扩展类型 Ability 的配置信息
    "extensionAbilities": [
      {
        "name": "NewsFormAbility",
        "srcEntry": "./ets/newsformability/NewsFormAbility.ets",
        "label": "$string:NewsFormAbility_label",
        "description": "$string:NewsFormAbility_desc",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ],
    // 所需权限配置，部分权限需要向官方提申请
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      //...
    ]
  }
}

build-profile.json5

下面的 build-profile.json5 文件配置了 应用模型为 stageMode，还支持了多 target 构建，不同的 target 可以通过 deviceType 选择支持不同的设备，通过 source 标签可以为指定 target 选择特定的代码资源，resource 能够为不同target module 选择特定资源目录。

build-profile.json5 的 buildOption 中还可以配置 HAP 依赖的/需要排除的 .so 文件以及CPP相关配置。

json5 复制代码 
{
  "apiType": 'stageMode',
  "buildOption": {
  },
  //使用 target 构建多目标产物
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS"
    },
    {
      "name": "free",
      "runtimeOS": "HarmonyOS",
      "config": {
        "deviceType": [
          "phone"
        ]
      }
    },
    {
      "name": "pay",
      "runtimeOS": "HarmonyOS",
      "config": {
        "deviceType": [
          "phone"
        ]
      },
      "source": {
        //定义多目标产物的源码集,不同版本产物,可定义不同的源码集
        "pages": [
          "pages/Index",
          "pages/home/AbilityPage",
          "pages/home/NewsPage"
        ]
      },
//      定义多目标构建产物的资源目录
      "resource": {
        "directories": [
          "./src/main/resources_default"
        ]
      }
    },
    {
      "name": "ohosTest",
    }
  ]
}

oh-package.json5

oh-package.json5 字段说明

oh-package.json5 是 module 配置第三方库依赖的文件，引用三方库资源 方式传送门。

json5 复制代码 
{
  "license": "",
  "devDependencies": {},
  "author": "",
  "name": "entry",
  "description": "Please describe the basic information.",
  "main": "",
  "version": "1.0.0",
  "dependencies": { //在大括号内添加依赖
     "@ohos/lottie": "^2.0.0"
    } 
}

工程配置文件

build-profile.json5

json5 复制代码 
{
  "app": {
    //工程的签名信息，可包含多个签名信息
    "signingConfigs": [
      {
        "name": "default", //标识签名方案的名称
        "type": "HarmonyOS", //标识HarmonyOS应用
         //该方案的签名材料
        "material": { 
          "certpath": "C:\\Users\\Pro\\.ohos\\config\\auto_debug_harmony-os-news_com.pro.box_260086000248135585.cer",
          "storePassword": "********",
          "keyAlias": "debugKey",
          "keyPassword": "********",
          "profile": "C:\\Users\\Pro\\.ohos\\config\\auto_debug_harmony-os-news_com.pro.box_260086000248135585.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:\\Users\\Pro\\.ohos\\config\\auto_debug_harmony-os-news_com.pro.box_260086000248135585.p12"
        }
      },
      {
        "name": "release",
        "type": "HarmonyOS",
        "material": {
          "certpath": "C:\\Users\\Pro\\.ohos\\config\\auto_debug_harmony-os-news_com.pro.box_260086000248135585.cer",
          "storePassword": "********",
          "keyAlias": "debugKey",
          "keyPassword": "********",
          "profile": "C:\\Users\\Pro\\.ohos\\config\\auto_debug_harmony-os-news_com.pro.box_260086000248135585.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:\\Users\\12481\\.ohos\\config\\auto_debug_harmony-os-news_com.pro.box_260086000248135585.p12"
        }
      }
    ],
    "compileSdkVersion": 9,
    "compatibleSdkVersion": 9,
    //定义构建的产品品类，如通用默认版、付费版、免费版等
    "products": [
    //定义产品的名称，支持定制多product目标产物，具体请参考定制多目标构建产物
      {
        "name": "default",
        "signingConfig": "release",
      },
      {
        "name": "productA",
        "signingConfig": "release"
      },
      {
        "name": "productPay",
        "signingConfig": "release"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",  //模块名称
      "srcPath": "./entry", //标明模块根目录相对工程根目录的相对路径
      "targets": [ //定义构建的APP产物，由product和各模块定义的targets共同定义
        {
          "name": "default", //target名称，由各个模块的build-profile.json5中的targets字段定义
          "applyToProducts": [
            "default" //表示将该模块下的"default" Target打包到"default" Product中
          ]
        },
        {
          "name": "free",
          "applyToProducts": [
            "productA"
          ]
        },
        {
          "name": "pay",
          "applyToProducts": [
            "productPay"
          ]
        }
      ]
    }
  ]
}

多目标构建产物配置文档 传送门。

工程级 oh-package.json5 配置三方依赖可参考官方文档。

签名信息申请和配置

HarmonyOS 要求在工程级别 build-profile.json5 文件中配置调试或发布证书、密钥库文件和密钥等信息。

json5 复制代码 
"material": {
          "certpath": "abc.cer", //华为颁发的数字证书
          "storePassword": "********", //密钥库密码，会以密文形式呈现
          "keyAlias": "alias",
          "keyPassword": "********",  //密钥密码，会以密文形式呈现
          "profile": "abc.p7b", //
          "signAlg": "SHA256withECDSA",
          "storeFile": "abc.p12" //本地生成密钥库
        }

签名配置流程和配置证书等信息说明

  1. 首先在 DevStudio 执行 Build -> Generate Key and CSR ， 分别生成本地密钥库（.p12 后缀文件）和 证书请求文件（.csr 后缀文件，Certificate Signing Request）

    1. 密钥库： 包含非对称加密中使用的公钥和私钥，存储在密钥库文件中，公钥和私钥对用于数字签名和验证；

    2. 证书请求文件：包含密钥对中的公钥和公共名称、组织名称、组织单位等信息，用于向AppGallery Connect申请数字证书；

  2. 申请华为数字证书：登录华为开发者联盟，向 AppGallery Connect -> 用户与访问 -> 证书管理 -> 新增证书 按照流程申请华为的数字证书，在申请时要选择提交本地 证书请求文件；

  3. 申请 Profile 文件：AppGallery Connect -> 我的项目 -> HAP Provision Profile 申请 Profile 文件，申请时要选择对应的华为数字证书

以上信息的配置还可以使用 DevEco Studio 的签名面板自动进行配置：

需要注意的是，使用签名面板自动配置，必须通过USB 接口连接可调试设备（可调试设备需要在 华为网站进行绑定）。

勾选 Automatically generate signature 后会自动生成相关信息，之后点击 apply 或 ok 即可。

注意：

构建 HarmonyOS 应用或服务

可以通过 DevEco Studio 一键式构建应用或服务，也可以通过命令行调用 Hvigor 任务进行构建。后一种方式需要安装命令行工具、JDK、node.js 等配置完整的构建环境。

热重载

在开发调试应用阶段，可以通过开启热重载提高开发效率，但是热重载也具有一定的使用限制。方式如下：

文末推荐

推荐一个学习数据结构和算法的优秀开源作品：hello，算法。该作品以动画图解和可视化方式演示算法计算的每个过程，且支持了多种编程语言。

  1. Hello,算法 Github 传送门
  2. 在线阅读 传送门
相关推荐
轻口味2 小时前
【每日学点HarmonyOS Next知识】tab对齐、相对布局、自定义弹窗全屏、动画集合、回到桌面
华为·harmonyos·harmonyosnext
小学生波波7 小时前
鸿蒙APP采用WebSocket实现在线实时聊天
websocket·华为·harmonyos·arkts·鸿蒙·实时聊天·在线聊天
轻口味7 小时前
【每日学点HarmonyOS Next知识】路由栈问题、图片圆角、颜色资源转十六进制字符串、数据集变化崩溃、组件声明周期
华为·harmonyos·harmonyosnext
一梦南柯11 小时前
HarmonyOS NEXT快速入手IBest-UI组件库
harmonyos
二流小码农12 小时前
鸿蒙开发：权限管理之权限声明
android·ios·harmonyos
全栈若城15 小时前
67.Harmonyos NEXT 图片预览组件之性能优化策略
性能优化·harmonyos·harmonyos next
觉醒法师15 小时前
HarmonyOS NEXT - 电商App实例三（ 网络请求axios）
前端·华为·typescript·axios·harmonyos·ark-ts
全栈若城18 小时前
63.Harmonyos NEXT 图片预览组件之手势处理实现
华为·harmonyos·harmonyos next
Bowen_J18 小时前
HarmonyOS架构详解
华为·harmonyos·arkts
蓝枫Amy19 小时前
HarmonyOS应用程序包概述
程序员·harmonyos
热门推荐
01从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑02如何在WPS和Word/Excel中直接使用DeepSeek功能03DeepSeek各版本说明与优缺点分析04Unity图形学之法线贴图原理05DeepSeek RAGFlow构建本地知识库系统06本地部署DeepSeek教程（Mac版本）07Windows 11 安装 Dify 完整指南 非docker环境08如何本地部署AI智能体平台，带你手搓一个AI Agent09本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程10KGG转MP3工具|非KGM文件|解密音频