CH3-HarmonyOS开发基础

背景

• 移动应用前端界面的定制需要引用很多定制化的图片资源，包括系统图标等；
• 应用还需要考虑国际化和本地化，这也需要应用中定义的资源限定词文件；
• 此 外，第三方库也是增强应用能力的有力工具。这些内容需要涉及到资源和库文件如何存储，以及在应用中如何引用这些资源

目标

• 深入理解HarmonyOS APP和HAP的组成及工作原理
• 掌握对应用关键资源的配置和访问方法

一、APP

• HarmonyOs的应用软件包以APP Pack ( Application Package ）形式发布，它是由一个或多个HAP( HarmonyOS Ability Package )以及描述每个HAP属性的pack.info组成。
  • HAP是Ability的部署包，HarmonyOS应用代码围绕Ability组件展开。

1.1 APP包组成

• 一个HAP是由代码、资源、第三方库及应用配置文件组成的模块包，可分为entry和feature两种模块类型。
  • entry: 应用的主模块。一个APP中，对于同一设备类型必须有且只有一个entry类型的HAP，可独立安装运行;
  • feature: 应用的动态特性模块。一个APP可以包含一个或多个feature类型的HAP，也可以不含。只有包含Ability的HAP才能够独立运行。
• HAP是由一个或多个Ability组成。

1.2 APP和HAP结构

二、Ability

2.1 Ability

• Ability是应用所具备的能力的抽象，一个应用可以包含一个或多个Ability。Ability分为两种类型:FA( Feature Ability)和PA( Particle Ability )。FA/PA是应用的基本组成单元，能够实现特定的业务功能。FA有UI界面，而PA无UI界面。
• libs(库文件)是应用依赖的第三方代码（例如so、jar、bin、har等二进制文件），存放在libs目录。
• 配置文件(config.json)包含应用中Ability的配置信息，用于声明应用的Ability，以及应用所需权限等信息。

2.2 pack.info

• 描述应用软件包中每个HAP的属性，由IDE编译生成，应用市场根据该文件进行拆包和HAP的分类存储。HAP的具体属性包括:
  • delivery-with-install表示该HAP是否支持随应用安装。“true”表示支持随应用安装;“false”表示不支持随应用安装;
  • name: HAP文件名;
  • module-type︰模块类型，entry或feature;device-type:表示支持该HAP运行的设备类型。

三、libs库文件

3.1 HAR

HAR(HarmonyOS Ability Resources)可以提供构建应用所需的所有内容，包括源代码、资源文件和config.json文件。HAR不同于HAP，HAR不能独立安装运行在设备上，只能作为应用模块的依赖项被引用。

四、resources资源文件

4.1 resources目录

• 应用的资源文件（字符串、图片、音频等）统一存放于resources目录下，便于开发者使用和维护。resources目录包括base目录与限定词目录。

• 目录结构

限定词目录

• 限定词目录可以由一个或多个表征应用场景或设备特征的限定词组合而成，包括语言、文字、国家或地区、横竖屏、设备类型和屏幕密度等六个维度，限定词之间通过下划线(_）或者中划线( -)连接。开发者在创建限定词目录时，需要掌握限定词目录的命名要求以及与限定词目录与设备状态的匹配规则。

• 类型

base目录

• 在应用开发的hml和js文件中使用$r的语法，可以对Js模块内的resources目录下的json资源进行格式化，获取相应的资源内容。

  • res-defaults.json文件内容为

  {strings: {
  hello: 'hello world')
  

  • 对于js页面对象的属性$r，可以使用string类型的key参数，返回值为string类型，如:

    this.$r('strings.hello')
    

4.2 系统资源文件

• 目前支持的系统资源文件

五、config配置文件

• 应用的每个HAP的根目录下都存在一个“config.json”配置文件，文件内容主要涵盖以下三个方面:
  • 应用的全局配置信息，包含应用的包名、生产厂商、版本号等基本信息;
  • 应用在具体设备上的配置信息，包含应用的备份恢复、网络安全等能力;
  • HAP包的配置信息，包含每个Ability必须定义的基本属性（如包名、类名、类型以及Ability提供的能力)，以及应用访问系统或其他应用受保护部分所需的权限等。

包含元素

• “config.json”的内部结构;
  • app对象的内部结构;
  • deviceConfig对象的内部结构;
  • module对象的内部结构;
• HAP与HAR的配置文件的合并。

“config.json”

• 应用的配置文件“config.json”中由“app”.“deviceConfig”和“module”三个部分组成，缺一不可。

1. app对象

• app对象包含应用的全局配置信息

"app": {
    "bundleName":"com.huawei.hiworld.example",
    "vendor": "huawei",
    "version":{ 
        "code": 2,
        "name": "2.0"
        }
}

2. deviceConfig对象

• deviceConfig包含在具体设备上的应用配置信息，可以包含default、phone、tablet、tv、car、wearable、liteWearable和smartVision等属性。default标签内的配置是适用于所有设备通用。

"deviceConfig": {
    "default": {
        "process": "com.huawei.hiworld.example",
        "supportBackup": false,
        "network": {
            "cleartextTraffic": true,
            "securityConfig": {
                "domainSettings": { 
                    "cleartextPermitted": true,
                    "domains": [
                        {
                            "subdomains": true,
                            "name": "example.ohos.com"
                        }
                    ]
                }
            }
        }
    }
}

phone对象

3. module对象

module对象包含HAP包的配置信息

"module": {
    "mainAbility": "MainAbility",
    "package": "com.example.myapplication.entry",
    "name": ".MyOHOSAbilityPackage",
    "description": "$string:description_application",
    "supportedModes": ["drive"],
    "deviceType": ["car"],
    "distro": {
        "deliveryWithlnstall": true,
        "moduleName": "ohos_entry",
        "moduleType": "entry",
		...
    }
}

内部结构

3.1 distro对象

"distro": {
    "deliveryWithInstall":true,
    "moduleName":"ohos_entry",
    "moduleType":"entry",
    "installationFree":true
}

3.2 js对象

"js": [
    {
        "name": "default",
        "pages": [
            "pages/index/index",
            "pages/detail/detail"],
        "window": {
        	"designWidth": 750,
            "autoDesignWidth":false
        },
		"type": "form"
    }
]

3.3 abilities对象

"abilities": [
    {
        "name": ".MainAbility",
        "description": "himusic main ability",
        "icon": "$media:ic_launcher",
        "label": "HiMusic",
        "launchType": "standard",
        "orientation": "unspecified",
        "permissions": [], 
        "visible": true,
        "skills": [...],
        "type": "page"
    },
]

• abilities对象的次要属性

skills对象

"skills": [
    {
        "actions": ["action.system.home"], 
        "entities": ["entity.system.home"],
        "uris": [
            {
                "scheme": "http",
                "host": "www.xxx.com",
                "port": "8080",
                "path": "query/student/name",
                "type": "text/*"
            }
        ]
    }
]

forms对象

"forms": [
    {
        "name": "Form_Js",
        "description": "It's Js Form",
        "type": "JS",
        "jsComponentName": "card",
        "colorMode": "auto",
        "isDefault": true,
        "updateEnabled": true,
        "scheduledUpdateTime": "11:00",
        "updateDuration": 1,
        "defaultDimension": "2*2",
        "supportDimensions": ["2*2","2*4","4*4"]
    },
]

配置文件的合并

• 如果应用模块中调用了HAR，在编译构建HAP时，需要将HAP的“config.json”文件与 一个或多个HAR的“config.json”文件，合并为一个“config.json”文件。在合并过程中， 不同文件的同一个标签的取值可能发生冲突，此时，需要通过配置mergeRule来解决冲 突

合并规则

• HAP与HAR的“config.json”文件合并时，需要将HAR的配置信息全部合并到HAP的配 置文件。系统定义了详细的合并规则；
• HAP的优先级总是高于HAR。当HAP依赖于多个HAR时，先加载的HAR的优先级高于后 加载的HAR，按照HAR的加载顺序依次合并到HAP文件

六、HAR

6.1 在工程中添加Module

• Module是HarmonyOS应用的基本功能单元，包含了源代码、资源文件、第三方库及应用清单文件，每一个Module都可以独立进行编译和运行。一个HarmonyOS应用通常会 包含一个或多个Module，因此，可以在工程中，创建多个Module，每个Module分为 Ability和Library（HarmonyOS Library和Java Library）两种类型

Module类型

• 在一个APP中，对于同一类型设备有且只有一个Entry Module，其余Module的类型均 为Feature。因此，在创建一个类型为Ability的Module时，遵循如下原则：
• 若新增Module的设备类型为已有设备时，则Module的类型将自动设置为“Feature” 。
• 若新增Module的设备类型为当前还没有创建Module，则Module的类型将自动设置为 “Entry”

6.2 新建空Module

6.3 创建HarmonyOS库

• 创建库模块
• 将库模块编译为HAR
• 发布Har包到Maven仓
• 为应用模块添加依赖

创建库Module

将库模块编译为HAR

• 利用Gradle可以将HarmonyOS Library库模块构建为HAR包，以便在工程中引用HAR或 者将HAR包提供给其它开发者进行调用；
• 构建HAR包的方法：在Gradle构建任务中，双击debugHarmonyHar或 releaseHarmonyHar任务，构建Debug类型或Release类型的HAR。

编译并输出库模块

发布Har包到Maven仓

• 借助Gradle提供的Maven-publish插件，可以将Har包发布到本地或远程Maven仓，方 法如下：
  • 在工程根目录下，点击鼠标右键New > File，创建一个以“.gradle”结尾的文件，如 upload.gradle；
  • 在创建的upload.gradle文件中，添加一定代码；
  • 在Har模块的build.gradle中，添加HAR发布脚本。添加完成后，请点击Sync Now进行同步。
  • 同步完成后，会在Gradle任务中增加publishing的任务列表；
  • 双击执行publishMavenPublicationToMavenRepository任务，将HAR包发布到指定的Maven地 址

为应用模块添加依赖

• 在应用模块中调用HAR，常用的添加依赖的方式包括如下两种：

  • 调用同一个工程中的HAR：HAR包和应用模块在同一个工程，打开应用模块的build.gradle文 件，在dependencies闭包中，添加如下代码。添加完成后，请点击Sync Now同步工程。

     dependencies { 
     	implementation project(":mylibrary") 
     }
    

  • 调用Maven仓中的HAR：无论Har包是本地Maven仓还是远程Maven仓，均可以在工程的 build.gradle的allprojects闭包中，添加HAR所在的Maven仓地址。

    repositories { 
    	maven { 
    		url 'file://D:/01.localMaven/' 
    	}
    }
    

本章总结

• 本章主要介绍了HarmonyOS APP和HAP包的组成，通过对这些包主要成分的介绍，引出如何构建HAR库文件，如何在项目中引用库文件；
• 接着分析了重要成分资源文件和配置文件的内容和作用，以及如何对它们进行访问和配置

  * `调用Maven仓中的HAR`：无论Har包是本地Maven仓还是远程Maven仓，均可以在工程的 build.gradle的`allprojects闭包`中，添加HAR所在的Maven仓地址。 

    ```
    repositories { 
    	maven { 
    		url 'file://D:/01.localMaven/' 
    	}
    }
    ```

    





# 本章总结 

* 本章主要介绍了HarmonyOS `APP和HAP包的组成`，通过对这些包主要成分的介绍，引出`如何构建HAR库文件`，`如何在项目中引用库文件`；
* 接着分析了`重要成分资源文件`和`配置文件`的内容和作用，以及`如何对它们进行访问和配置`