HarmonyOS配置文件config.json配置详解以及资源文件操作

简介

开发一个HAP应用可以说是由多个Ability组成，那么我们直接new File创建Ability之后会在config.json的module里面添加相应的配置信息，这就需要我们去搞清楚这些配置信息有什么作用，然后可以通过修改不同的配置信息达到不同的效果；这里就创建一个新的项目进行讲解，更多的配置信息以及属性可以查阅harmonyOS官方文档。

config.json文件详解

config.json是一个HAP项目主要的配置文件，所有相关配置信息都配置在该文件下；配置文件采用JSON文件格式，每个配置项由属性和值两部分组成；属性的出现不分先后顺序，且只出现一次；值是由JSON的基础数据类型组成。

config.json文件组成部分

每一个config.json文件都由app、deviceConfig、module三部分组成，三个部分都不可或缺。

• app 应用全局配置信息
• deviceConfig 具体设备上的配置信息
• module HAP包基本配置信息

app

整个项目的全局配置信息，比如版本号、版本名称等全局信息就配置在该项下面，这里就简单列举几个常用到的配置信息进行展示：

• bundleName 应用包名
• version code 版本号
• version name 版本名称(多展示于用户)
• apiVersion 引用依赖的api版本

"app": {//全局配置信息
    "bundleName": "com.example.demo1",//应用包名，应用唯一标识符
    "vendor": "example",//应用开发厂商的描述
    "version": {
      "code": 1000000,//版本号
      "name": "1.0.0"//版本名称
    },
    "apiVersion": {//应用依赖harmonyOS的api版本
      "compatible": 3,//应用运行需要的最小版本
      "target": 3 //应用运行的目标版本
    }
},
1
2
3
4
5
6
7
8
9
10
11
12

deviceConfig

该配置信息表示应用运行到具体设备上的配置信息，作用于具体设备，可选值如下：

• default 表示该配置信息作用于所有设备
• phone 表示该配置信息作用于手机设备
• tablet 表示该配置信息作用于平板设备
• tv 表示该配置信息作用于智慧屏设备
• car 表示该配置信息作用于车机设备
• wearable 表示该配置信息作用于智能穿戴设备
• liteWearable 表示该配置信息作用于轻量级智能穿戴设备
• smartVision 表示该配置信息作用于智能摄像头

几个常用信息：

• default 配置信息作用域
• process 进程名称
• network 网络
• usesCleartext 明文访问

这里简单列举几条配置信息，deviceConfig更多配置信息可以查阅官方文档。

"deviceConfig": {//具体设备上的配置信息
    "default": {//表示该配置使用与所有应用，可以配置成phone(手机)、tv(智能屏)、car(车机特有信息)、wearable(只能穿戴设备)等
      "process": "com.huawei.example",//应用或者ability进程名称，应用所有的ability都在这个进程中运行
      "directLaunch": false,//应用是否可以在设备未解锁的状态下启动(电话在未解锁下可以直接启动)
      "supportBackup": false,//应用是否支持备份和恢复
      "network": {//网络配置
        "usesCleartext": true,//应用是否允许明文网络流量(不加密的网络通信)
        "securityConfig": {//应用网络安全配置信息
          "domainSettings": {//自定义的网域范围安全配置，支持多层嵌套
            "cleartextPermitted": true,//自定义的网域是否支持明文流量传输
            "domains": [{//域名配置信息
              "subdomains": true,//是否包含子域
              "name": "www.xxx.com"//域名名称
            }]
          }
        }
      }
    }
},
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

module

HAP包的配置信息，主要作用于项目内的ability文件，配置不同ability不同信息，实现不同功能。

常用配置信息：

• package HAP包名，应用的唯一性
• name HAP类的名称，程序主入口
• mainAbility HAP包入口名称
• deviceType 支持的设备类型，可多个，装在一个集合里面
• distro HAP包发布的具体信息
• abilities 当前模块内的所有ability，同样装在一个集合里面

发布的具体信息配置：

• deliveryWithInstall 当前HAP是否支持随应用安装，取值true 或者 false,设置false可能导致最终应用上架应用市场异常。
• moduleName 当前HAP名称
• moduleType 当前HAP类型,取值范围entry和feature;entry表示应用的主模块。一个APP中，对于同一设备类型必须有且只有一个entry类型的HAP，可独立安装运行。feature表示应用的动态特性模块。一个APP可以包含一个或多个feature类型的HAP，也可以不含。只有包含Ability的HAP才能够独立运行。
• installationFree 当前HAP是否支持免安装特性

abilities相关配置信息:

• name 当前ability文件名称
• orientation 当前ability的显示模式
• icon 当前ability显示的icon图标
• description 当前ability的描述
• label 当前ability显示在页面上的名称
• type 当前ability的类型，取值范围 page、service、data等
• formsEnabled 当前ability是否支持表单操作
• launchType 当前ability的启动模式，取值范围standard、singleton
• skills 当前ability可以接收的intent特性

skills相关配置信息：

• actions 能够接收的intent的action行为值，可以包含一个或者多个，取值范围通常为系统定义的action值，可以理解为Intent类源码中定义的常量值。
• entities 能够接收的intent的ability类别，可以包含一个或者多个，取值范围同actions。

可能不是很好理解，看到config.json文件中的配置，这里的entities的取值为entity.system.home，系统主页的意思，当前这个ability的intent的ability类型是系统主页，那么打开HAP应用的时候这个页面就是主页面，这样说就比较好理解了。

"abilities": [//表示当前模块内的所有Ability
      {
        "skills": [//ability能够接收的intent特征
          {
            "entities": [//能够接收的intent的ability类别
              "entity.system.home"//这里Ability设置可以接收的intent的类型为系统主页的类型
            ],
            "actions": [//接收的intent的action行为
              "action.system.home"//这个值代表返回主页的行为
            ]
          }
        ],
        "orientation": "unspecified",//显示模式 unspecified(由系统判定显示方向) landscape(横屏) portrait(竖屏)
        "name": "com.example.demo1.MainAbility",//ability名称
        "icon": "$media:icon",//ability图标资源文件
        "description": "$string:mainability_description",//ability的描述
        "label": "$string:entry_MainAbility",//ability对用户(显示在页面上)的名称
        "type": "page",//ability的类型 page  service  data
        "formsEnabled": true,//ability是否支持表单(登录  注册提交)
        "launchType": "standard"//ability的启动模式  standard  singleton
      },
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

以上就是HAP应用的config.json配置文件部分详解了，更多配置信息可以查阅官方文档进行了解。

资源文件目录结构

通过应用目录结构我们可以很清楚的看到HAP项目的资源文件是存放在resources文件下面的、包括布局、图片、媒体、json文件等信息，文件结构如下：

图片、媒体、布局等文件都存放在base目录下，base目录结构：

–base

• element 存放元素资源文件，多为json文件
• graphic 存放shape等绘制的xml资源，比如按钮样式等
• layout 存放布局文件
• media 存放媒体资源，包括图片、音频、视频等非文本格式的文件
• profile 存放其他自定义文件
• animation 存放动画文件的xml资源

资源文件的引用

HAP的资源文件分为base目录、限定词目录以及rawfile目录，三种目录文件；而对不同文件目录访问的方式也不一样，大致可分为base目录和rawfile目录两种访问方式。

base目录限定词目录文件引用

在HAP项目中，要访问base目录和限定词目录下的文件需要用到资源管理器ResourceManager进行访问，这里以访问element下面的string.json文件里面的值作为例子，操作步骤如下：

1.在string.json文件里面添加一个测试的值:

"string": [{
      "name": "test_name",
      "value": "我是测试名称"
},
1
2
3
4

2.获取ResourceManager实例对象：

ResourceManager resourceManager = this.getResourceManager();
1

3.通过资源管理器获取element下面的数据：

//getElement 获取
//ResourceTable.String 获取element下string.json文件中类型为string 
//test_name 名称为test_name的元素资源
//getString 获取的值类型为String类型
String name = resourceManager.getElement(ResourceTable.String_test_name).getString();
System.out.print(name);
1
2
3
4
5
6

4.通过上面的方法创建一个存放color值的json文件并获取

//ResourceTable.Color 获取资源类型为Color  
//red 值为red的资源
//getColor 资源类型为color
int color = resourceManager.getElement(ResourceTable.Color_red).getColor();
1
2
3
4

xml布局引用资源文件

在xml布局文件中访问资源文件采用以下格式进行引用：

引用base下文件：
$type.name

引用系统文件：
$ohos:type.name

在xml文件中的text组件引用string.json和color.json里面的资源：

<Text
   ohos:id="$+id:text_helloworld"
   ohos:height="match_content"
   ohos:width="match_content"
   //系统资源 $ohos:资源类型type:资源name
   ohos:background_element="$ohos:color:id_color_activated"
   ohos:layout_alignment="horizontal_center"
   //$资源类型type:资源name
   ohos:text="$string:test_name"
   //$资源类型type:资源name
   ohos:text_color="$color:red"
   ohos:text_size="20fp"
/>
1
2
3
4
5
6
7
8
9
10
11
12
13

rawfile目录资源引用

引用rawfile资源需要通过指定文件路径和文件名称进行访问，同样需要使用到资源管理器ResourceManager，并且返回的数据是一个RawFileEntry。

//获取ResourceManager 实例
ResourceManager resourceManager = this.getResourceManager();
//通过resourceManager的getRawFileEntry方法获取rawfile文件
//文件路径为resources/rawfile/example.js
//获得的结果为RawFileEntry 
RawFileEntry rawFileEntry = resourceManager.getRawFileEntry("resources/rawfile/example.js");
1
2
3
4
5
6

资源文件创建规则

element下的资源文件都是以json的方式进行存放，最外层对象为该资源文件的数据类型，取值范围就是基本的数据类型，然后是一个集合，集合里面是对象，实例如下：

• boolean

{
    "boolean":[//资源类型type
        {
            "name":"exm_boolean",
            "value":true
        }
    ]
}
1
2
3
4
5
6
7
8

• color

{
    "color":[
        {
            "name":"red",
            "value":"#ff0000"
        }
    ]
}
1
2
3
4
5
6
7
8

• strarray

{
    "strarray":[
       {
           "name":"size",
           "value":[
               {
                   "value":"small"
               },
               {
                   "value":"$string:hello"
               },
               {
                   "value":"large"
               },
               {
                   "value":"extra large"
               }
            ]
       }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

如果要创建int、string、float等数据类型就和上面的boolean、color差不多了；要创建pattern、plural、strarray等类型可以仿照上面的strarray进行创建，也可以访问官方文档，查看具体例子。

资源文件官方文档地址：资源文件官方文档