HarmonyOS Developer 应用配置文件(Stage模型)

丶龙八夷
发布于 2023-3-21 19:17
浏览
0收藏

应用配置文件概述(Stage模型)

每个应用项目必须在项目的代码目录下加入配置文件,这些配置文件会向编译工具、操作系统和应用市场提供应用的基本信息。

在基于Stage模型开发的应用项目代码下,都存在一个app.json5及一个或多个module.json5这两种配置文件。

​app.json5​​主要包含以下内容:

  • 应用的全局配置信息,包含应用的包名、开发厂商、版本号等基本信息。
  • 特定设备类型的配置信息。

​module.json5​​主要包含以下内容:

  • Module的基本配置信息,例如Module名称、类型、描述、支持的设备类型等基本信息。
  • ​应用组件​​信息,包含UIAbility组件和ExtensionAbility组件的描述信息。
  • 应用运行过程中所需的权限信息。

app.json5配置文件

先通过一个示例,整体认识一下app.json5配置文件。

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "description": "$string:description_application",
    "distributedNotificationEnabled": true,
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "entityType": "media",
    "car": {
      "minAPIVersion": 8,
    }
  },
}

app.json5配置文件包含以下标签。

表1 app.json5文件配置标签说明

属性名称

含义

数据类型

是否可缺省

bundleName

标识应用的包名,用于标识应用的唯一性。该标签不可缺省。标签的值命名规则 :

- 字符串以字母、数字、下划线和符号“.”组成。

- 以字母开头。

- 最小长度7个字节,最大长度127个字节。

推荐采用反域名形式命名(如com.example.demo,建议第一级为域名后缀com,第二级为厂商/个人名,第三级为应用名,也可以多级)。

字符串

该标签不可缺省。

debug

标识应用是否可调试,该标签由IDE编译构建时生成。

- true:可调试。

- false:不可调试。

布尔值

该标签可以缺省,缺省为false。

icon

标识​​应用的图标​​,标签值为图标资源文件的索引。

字符串

该标签不可缺省。

label

标识​​应用的名称​​,标签值为字符串资源的索引。

字符串

该标签不可缺省。

description

标识应用的描述信息,标签值是字符串类型(最大255个字节)或对描述内容的字符串资源索引。

字符串

该标签可缺省,缺省值为空。

vendor

标识对应用开发厂商的描述。该标签的值是字符串类型(最大255个字节)。

字符串

该标签可以缺省,缺省为空。

versionCode

标识应用的版本号,该标签值为32位非负整数。此数字仅用于确定某个版本是否比另一个版本更新,数值越大表示版本越高。开发者可以将该值设置为任何正整数,但是必须确保应用的新版本都使用比旧版本更大的值。该标签不可缺省,versionCode值应小于2^31次方。

数值

该标签不可缺省。

versionName

标识应用版本号的文字描述,用于向用户展示。

该标签仅由数字和点构成,推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。

第一段:主版本号/Major,范围0-99,重大修改的版本,如实现新的大功能或重大变化。

第二段:次版本号/Minor,范围0-99,表示实现较突出的特点,如新功能添加或大问题修复。

第三段:特性版本号/Feature,范围0-99,标识规划的新版本特性。

第四段:修订版本号/Patch,范围0-999,表示维护版本,修复bug。

标签最大字节长度为127。

字符串

该标签不可缺省。

minCompatibleVersionCode

标识应用能够兼容的最低历史版本号,用于跨设备兼容性判断。













说明



当前版本暂不支持跨设备能力。






数值

该标签可缺省,缺省值等于versionCode标签值。

minAPIVersion

标识应用运行需要的SDK的API最小版本。

数值

由bundle-profile.json5中的compatibleSdkVersion生成。

targetAPIVersion

标识应用运行需要的API目标版本。

数值

由bundle-profile.json5中的compileSdkVersion生成。

apiReleaseType

标识应用运行需要的API目标版本的类型,采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”,其中,N代表大于零的整数。

- Canary:受限发布的版本。

- Beta:公开发布的Beta版本。

- Release:公开发布的正式版本。

该字段由DevEco Studio读取当前使用的SDK的Stage来生成。

字符串

该标签可缺省,由IDE生成并覆盖。

distributedNotificationEnabled

标识应用是否开启分布式通知,当开启分布式通知时,同一分布式组网下的两个设备(A和B),当设备A收到一条消息时,设备B会收到一天分布式消息用于设备B的使用者去查看设备A的消息。

- true:开启。

- false:不开启。

布尔值

该标签可缺省,缺省值为false。

entityType

标识应用的类别,分别有:

- game:游戏类。

- media:影音类。

- communication:社交通信类。

- news:新闻类。

- travel:出行类。

- utility:工具类。

- shopping:购物类。

- education:教育类。

- kids:少儿类。

- business:商务类。

- photography:拍摄类。

- unspecified:不属于上述的任何一类。

字符串

该标签可以缺省,缺省为unspecified。

multiProjects

标识当前工程是否支持多个工程的联合开发。

- true:当前工程支持多个工程的联合开发。

- false:当前工程不支持多个工程的联合开发。

布尔值

可缺省,缺省值为false。

tablet

标识对tablet设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。

如果使用该属性对tablet设备做了特殊配置,则应用在tablet设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。

对象

该标签可缺省,缺省时tablet设备使用app.json5公共区域配置的属性值。

tv

标识对tv设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。

如果使用该属性对tv设备做了特殊配置,则应用在tv设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。

对象

该标签可缺省,缺省时tv设备使用app.json5公共区域配置的属性值。

wearable

标识对wearable设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。

如果使用该属性对wearable设备做了特殊配置,则应用在wearable设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。

对象

该标签可缺省,缺省时wearable设备使用app.json5公共区域配置的属性值。

car

标识对car设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。

如果使用该属性对car设备做了特殊配置,则应用在car设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。

对象

该标签可缺省,缺省时car设备使用app.json5公共区域配置的属性值。

default

标识对default设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。

如果使用该属性对default设备做了特殊配置,则应用在default设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。

对象

该标签可缺省,缺省时default设备使用app.json5公共区域配置的属性值。

phone

标识对phone设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。

如果使用该属性对phone设备做了特殊配置,则应用在phone设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。

module.json5配置文件

先通过一个示例,整体认识一下module.json5配置文件。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "virtualMachine": "ark",
    "metadata": [
      {
        "name": "string",
        "value": "string",
        "resource": "$profile:distrofilter_config"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntrance": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "visible": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

module.json5配置文件包含以下标签。

表1 module.json5配置文件配置标签说明

属性名称

含义

数据类型

是否可缺省

name

标识当前Module的名称,标签值采用字符串表示(最大长度31个字节),该名称在整个应用要唯一。

字符串

该标签不可缺省。

type

标识当前Module的类型。类型有两种,分别:

- entry:应用的主模块。

- feature:应用的动态特性模块。

字符串

该标签不可缺省。

srcEntrance

标识当前Module所对应的代码路径,标签值为字符串(最长为127字节)。

字符串

该标签可缺省,缺省值为空。

description

标识当前Module的描述信息,标签值是字符串类型(最长255字节)或对描述内容的字符串资源索引。

字符串

该标签可缺省,缺省值为空。

process

标识当前Module的进程名,标签值为字符串类型(最长为31个字节)。如果在HAP标签下配置了process,该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。

说明:

- 仅支持系统应用配置,三方应用配置不生效。

字符串

可缺省,缺省为app.json5文件下app标签下的bundleName。

mainElement

标识当前Module的入口UIAbility名称或者ExtensionAbility名称。标签最大字节长度为255。

字符串

该标签可缺省,缺省值为空。

deviceTypes

标识当前Module可以运行在哪类设备上,标签值采用字符串数组的表示。

字符串数组

该标签不可缺省,可以为空值。

deliveryWithInstall

标识当前Module是否在用户主动安装的时候安装,表示该Module对应的HAP是否跟随应用一起安装。

- true:主动安装时安装。

- false:主动安装时不安装。

布尔值

该标签不可缺省。

installationFree

标识当前Module是否支持免安装特性。

- true:表示支持免安装特性,且符合免安装约束。

- false:表示不支持免安装特性。

说明:

- 当应用的entry类型Module的该字段配置为true时,该应用的feature类型的该字段也需要配置为true。

- 当应用的entry类型Module的该字段配置为false时,该应用的feature类型的该字段根据业务需求配置true或false。

布尔值

该标签不可缺省。

virtualMachine

标识当前Module运行的目标虚拟机类型,供云端分发使用,如应用市场和分发中心。

该标签值为字符串。如果目标虚拟机类型为ArkTS引擎,则其值为“ark+版本号”。

字符串

该标签由IDE构建HAP的时候自动插入。

uiSyntax(deprecated)

标识当前Module syntax定义该组件的语法类型。

- hml:标识该组件使用hml/css/js进行开发。

- ets:标识该组件使用ArkTS声明式语法进行开发。

字符串

该标签可缺省,默认值为hml,该标签从API9开始废弃。

pages

标识当前Module的profile资源,用于列举每个页面的信息。该标签最大长度为255个字节。

字符串

在有UIAbility的场景下,该标签不可缺省。

metadata

标识当前Module的自定义元信息,标签值为数组类型,只对当前Module、UIAbility、ExtensionAbility生效。

对象数组

该标签可缺省,缺省值为空。

abilities

标识当前Module中UIAbility的配置信息,标签值为数组类型,只对当前UIAbility生效。

对象

该标签可缺省,缺省值为空。

extensionAbilities

标识当前Module中ExtensionAbility的配置信息,标签值为数组类型,只对当前ExtensionAbility生效。

对象

该标签可缺省,缺省值为空。

requestPermissions

标识当前应用运行时需向系统申请的权限集合。

对象

该标签可缺省,缺省值为空。

testRunner

标识当前Module用于支持对测试框架的配置。

对象

该标签可缺省,缺省值为空。

deviceTypes标签

表2 deviceType标签配置说明

设备类型

枚举值

说明

平板

tablet

-

智慧屏

tv

-

智能手表

wearable

系统能力较丰富的手表,具备电话功能。

车机

car

-

手机

phone

-

默认设备

default

能够使用全部系统能力的HarmonyOS设备。













说明



当前,phone、default两个取值效果相同,即应用可以运行在手机设备上。






deviceTypes示例:

{
  "module": {
    "name": "myHapName",
    "type": "feature",
    "deviceTypes" : [
       "tablet"
    ]
  }
}

pages标签

该标签是一个profile文件资源,用于指定描述页面信息的配置文件。

{
  "module": {
    // ...
    "pages": "$profile:main_pages", // 通过profile下的资源文件配置
  }
}

在开发视图的resources/base/profile下面定义配置文件main_pages.json,其中文件名(main_pages)可自定义,需要和前文中pages标签指定的信息对应,配置文件中列举了当前应用组件中的页面信息。

{
  "src": [
    "pages/index/mainPage",
    "pages/second/payment",
    "pages/third/shopping_cart",
    "pages/four/owner"
  ]
}

metadata标签

该标签标识HAP的自定义元信息,标签值为数组类型,包含name,value,resource三个子标签。

表3 metadata标签说明

属性名称

含义

数据类型

是否可缺省

name

该标签标识数据项的键名称,字符串类型(最大长度255字节)。

字符串

该标签可缺省,缺省值为空。

value

该标签标识数据项的值,标签值为字符串(最大长度255字节)。

字符串

该标签可缺省,缺省值为空。

resource

该标签标识定义用户自定义数据格式,标签值为标识该数据的资源的索引值。该标签最大字节长度为255字节。

字符串

该标签可缺省,缺省值为空。

{
  "module": {
    "metadata": [{
      "name": "module_metadata",
      "value": "a test demo for module metadata",
      "resource": "$profile:shortcuts_config",
    }],

    "abilities": [{
      "metadata": [{
        "name": "ability_metadata",
        "value": "a test demo for ability",
        "resource": "$profile:config_file"
      },
      {
        "name": "ability_metadata_2",
        "value": "a string test",
        "resource": "$profile:config_file"
      }],
    }],

    "extensionAbilities": [{
      "metadata": [{
        "name": "extensionAbility_metadata",
        "value": "a test for extensionAbility",
        "resource": "$profile:config_file"
      },
      {
        "name": "extensionAbility_metadata_2",
        "value": "a string test",
        "resource": "$profile:config_file"
      }],
    }]
  }
}

abilities标签

ablities标签描述UIAbility组件的配置信息,标签值为数组类型,该标签下的配置只对当前UIAbility生效。

表4 abilities标签说明

属性名称

含义

数据类型

是否可缺省

name

标识当前UIAbility组件的名称,该名称在整个应用要唯一,标签值采用字符串表示(最大长度127个字节)。

字符串

该标签不可缺省。

srcEntrance

该标签标识入口UIAbility的代码路径,标签值为字符串(最长为127字节)。

字符串

该标签不可缺省。

​launchType​

标识当前UIAbility组件的启动模式,可选标签值:

- standard:标准实例模式,每次启动创建一个新的实例。

- singleton:单实例模式,仅第一次启动创建新实例。

- specified:指定实例模式,运行时由开发者决定是否创建新实例。

字符串

可缺省,该标签缺省为“singleton”。

description

标识当前UIAbility组件的描述信息,标签值是字符串类型(最长255字节)或对描述内容的资源索引,要求采用资源索引方式,以支持多语言。

字符串

该标签可缺省,缺省值为空。

icon

标识当前UIAbility组件的图标,标签值为图标资源文件的索引。

字符串

该标签可缺省,缺省值为空。

如果UIAbility被配置为MainElement,该标签必须配置。

label

标识当前UIAbility组件对用户显示的名称,标签值配置为该名称的资源索引以支持多语言。

如果UIAbility被配置当前Module的mainElement时,该标签必须配置,且应用内唯一。

字符串

该标签不可缺省。

permissions

标识当前UIAbility组件自定义的权限信息。当其他应用访问该UIAbility时,需要申请相应的权限信息。

一个数组元素为一个权限名称。通常采用反向域名格式(最大255字节),取值为系统预定义的权限。

字符串数组

该标签可缺省,缺省值为空。

metadata

标识当前UIAbility组件的元信息。

对象数组

该标签可缺省,缺省值为空。

visible

标识当前UIAbility组件是否可以被其他应用调用。

- true:表示可以被其他应用调用。

- false:表示不可以被其他应用调用。

布尔值

该标签可缺省,缺省值为false。

continuable

标识当前UIAbility组件是否可以迁移。

- true:表示可以被迁移。

- false:表示不可以被迁移。













说明



当前版本暂不支持跨设备能力。






布尔值

该标签可缺省,缺省值为false。

skills

标识当前UIAbility组件或ExtensionAbility组件能够接收的​​Want​​的特征集,为数组格式。

配置规则:

- 对于Entry类型的HAP,HarmonyOS应用可以配置多个具有入口能力的skills标签(即配置了action.system.home和entity.system.home)。

- 对于Feature类型的HAP,只有HarmonyOS应用可以配置具有入口能力的skills标签,HarmonyOS服务不允许配置。

对象数组

该标签可缺省,缺省值为空。

backgroundModes

标识当前UIAbility组件的长时任务集合。指定用于满足特定类型的长时任务。

长时任务类型有如下:

- dataTransfer:通过网络/对端设备进行数据下载、备份、分享、传输等业务。

- audioPlayback:音频输出业务。

- audioRecording:音频输入业务。

- location:定位、导航业务。

- bluetoothInteraction:蓝牙扫描、连接、传输业务(穿戴)。

- multiDeviceConnection:多设备互联业务。

- wifiInteraction:Wi-Fi扫描、连接、传输业务(克隆多屏)。

- voip:音视频电话,VoIP业务。

- taskKeeping:计算业务。

字符串数组

该标签可缺省,缺省值为空。

startWindowIcon

标识当前UIAbility组件启动页面图标资源文件的索引。取值示例:$media:icon。

该标签最大字节长度为255。

字符串

不可缺省。

startWindowBackground

标识当前UIAbility组件启动页面背景颜色资源文件的索引。取值示例:$color:red。

改标签最大字节长度为255。

字符串

不可缺省。

removeMissionAfterTerminate

标识当前UIAbility组件销毁后是否从任务列表中移除任务,为布尔类型:

- true表示销毁后移除任务。

- false表示销毁后不移除任务。

布尔值

该标签可缺省,缺省值为false。

orientation

标识当前UIAbility组件启动时的方向。该方向的取值范围包括:

- unspecified:未指定方向,由系统自动判断显示方向。

- landscape:横屏。

- portrait:竖屏。

- landscape_inverted:反向横屏。

- portrait_inverted:反向竖屏。

- auto_rotation:随传感器旋转。

- auto_rotation_landscape:传感器横屏旋转,包括了横屏和反向横屏。

- auto_rotation_portrait:传感器竖屏旋转,包括了竖屏和反向竖屏。

- auto_rotation_restricted:传感器开关打开,方向可随传感器旋转。

- auto_rotation_landscape_restricted:传感器开关打开,方向可随传感器旋转为横屏, 包括了横屏和反向横屏。

- auto_rotation_portrait_restricted:传感器开关打开,方向随可传感器旋转为竖屏, 包括了横屏和反向横屏。

- locked:传感器开关关闭,方向锁定。

字符串

该标签可缺省,缺省值为unspecified。

supportWindowMode

标识当前UIAbility组件所支持的窗口模式,包含:

- fullscreen:全屏模式。

- split:分屏模式。

- floating:悬浮窗模式。

字符串数组

该标签可缺省,缺省值为

["fullscreen", "split", "floating"]。

priority

标识当前UIAbility组件的优先级,仅支持系统应用配置,三方应用配置不生效。​​隐式查询​​时,优先级越高,UIAbility在返回列表越靠前。该标签取值为integer类型,取值范围0-10。数值越大,优先级越高。

数值

该标签可缺省,缺省值为0。

maxWindowRatio

标识当前UIAbility组件支持的最大的宽高比。该标签最小取值为0。

数值

该标签可缺省,缺省值为平台支持的最大的宽高比。

minWindowRatio

标识当前UIAbility组件支持的最小的宽高比。该标签最小取值为0。

数值

该标签可缺省,缺省值为平台支持的最小的宽高比。

maxWindowWidth

标识当前UIAbility组件支持的最大的窗口宽度,宽度单位为vp。该标签最小取值为0。

数值

该标签可缺省,缺省值为平台支持的最大的窗口宽度。

minWindowWidth

标识当前UIAbility组件支持的最小的窗口宽度, 宽度单位为vp。该标签最小取值为0。

数值

该标签可缺省,缺省值为平台支持的最小的窗口宽度。

maxWindowHeight

标识当前UIAbility组件支持的最大的窗口高度, 高度单位为vp。该标签最小取值为0。

数值

该标签可缺省,缺省值为平台支持的最大的窗口高度。

minWindowHeight

标识当前UIAbility组件支持的最小的窗口高度, 高度单位为vp。该标签最小取值为0。

数值

该标签可缺省,缺省值为平台支持的最小的窗口高度。

excludeFromMissions

标识当前UIAbility组件是否在最近任务列表中显示。

- true:表示不在任务列表中显示。

- false:表示在任务列表中显示。

说明:

- 仅支持系统应用配置,三方应用配置不生效。

布尔值

该标签可缺省,缺省值为false。

abilities示例:

{
  "abilities": [{
    "name": "EntryAbility",
    "srcEntrance": "./ets/entryability/EntryAbility.ts",
    "launchType":"standard",
    "description": "$string:description_main_ability",
    "icon": "$media:icon",
    "label": "Login",
    "permissions": [],
    "metadata": [],
    "visible": true,
    "continuable": true,
    "skills": [{
      "actions": ["action.system.home"],
      "entities": ["entity.system.home"],
      "uris": []
    }],
    "backgroundModes": [
      "dataTransfer",
      "audioPlayback",
      "audioRecording",
      "location",
      "bluetoothInteraction",
      "multiDeviceConnection",
      "wifiInteraction",
      "voip",
      "taskKeeping"
    ],
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:red",
    "removeMissionAfterTerminate": true,
    "orientation": " ",
    "supportWindowMode": ["fullscreen", "split", "floating"],
    "maxWindowRatio": 3.5,
    "minWindowRatio": 0.5,
    "maxWindowWidth": 2560,
    "minWindowWidth": 1400,
    "maxWindowHeight": 300,
    "minWindowHeight": 200,
    "excludeFromMissions": false
  }]
}

skills标签

该标签标识UIAbility组件或者ExtensionAbility组件能够接收的​​Want​​的特征。

表5 skills标签说明

属性名称

含义

数据类型

是否可缺省

actions

标识能够接收的Want的​​Action值的集合​​,取值通常为系统预定义的action值,也允许自定义。

字符串数组

可缺省,缺省值为空。

entities

标识能够接收Want的​​Entity值的集合​​。

字符串数组

可缺省,缺省值为空。

uris

标识与Want中URI(Uniform Resource Identifier)相匹配的集合。

对象数组

可缺省,缺省值为空。

表6 uris对象内部结构说明

属性名称

含义

数据类型

是否可缺省

scheme

标识URI的协议名部分,常见的有http、https、file、ftp等。

字符串

uris中仅配置type时可以缺省,缺省值为空,否则不可缺省。

host

标识URI的主机地址部分,该字段要在schema存在时才有意义。常见的方式:

- 域名方式,如example.com。

- IP地址方式,如10.10.10.1。

字符串

可缺省,缺省值为空。

port

标识URI的端口部分。如http默认端口为80,https默认端口是443,ftp默认端口是21。该字段要在schema和host都存在时才有意义。

字符串

可缺省,缺省值为空。

path | pathStartWith | pathRegex

标识URI的路径部分,path、pathStartWith和pathRegex配置时三选一。path标识URI与want中的路径部分全匹配,pathStartWith标识URI与want中的路径部分允许前缀匹配,pathRegex标识URI与want中的路径部分允许正则匹配。该字段要在schema和host都存在时才有意义。

字符串

可缺省,缺省值为空。

type

标识与Want相匹配的数据类型,使用MIME(Multipurpose Internet Mail Extensions)类型规范。可与schema同时配置,也可以单独配置。

字符串

可缺省,缺省值为空。

skills示例:

{
  "abilities": [
    {
      "skills": [
        {
          "actions": [
            "action.system.home"
          ],
          "entities": [
            "entity.system.home"
          ],
          "uris": [
            {
              "scheme":"http",
              "host":"example.com",
              "port":"80",
              "path":"path",
              "type": "text/*"
            }
          ]
        }
      ]
    }
  ]
}

extensionAbilities标签

描述extensionAbilities的配置信息,标签值为数组类型,该标签下的配置只对当前extensionAbilities生效。

表7 extensionAbilities标签说明

属性名称

含义

数据类型

是否可缺省

name

标识当前ExtensionAbility组件的名称,标签值最大长度为127个字节,该名称在整个应用要唯一。

字符串

该标签不可缺省。

srcEntrance

标识当前ExtensionAbility组件所对应的代码路径,标签值最大长度为127字节。

字符串

该标签不可缺省。

description

标识当前ExtensionAbility组件的描述,标签值最大长度为255字节,标签也可以是描述内容的资源索引,用于支持多语言。

字符串

该标签可缺省,缺省值为空。

icon

标识当前ExtensionAbility组件的图标,标签值为资源文件的索引。如果ExtensionAbility组件被配置为MainElement,该标签必须配置。

字符串

该标签可缺省,缺省值为空。

label

标识当前ExtensionAbility组件对用户显示的名称,标签值配置为该名称的资源索引以支持多语言。

说明:

- 如果ExtensionAbility被配置当前Module的mainElement时,该标签必须配置,且应用内唯一。

字符串

该标签不可缺省。

type

标识当前ExtensionAbility组件的类型,取值为:

- form:卡片的ExtensionAbility。

- workScheduler:延时任务的ExtensionAbility。

- inputMethod:输入法的ExtensionAbility。

- service:后台运行的service组件。

- accessibility:辅助能力的ExtensionAbility。

- dataShare:数据共享的ExtensionAbility。

- fileShare:文件共享的ExtensionAbility。

- staticSubscriber:静态广播的ExtensionAbility。

- wallpaper:壁纸的ExtensionAbility。

- backup:数据备份的ExtensionAbility。

- window:该ExtensionAbility会在启动过程中创建一个window,为开发者提供界面开发。开发者开发出来的界面将通过abilityComponent控件组合到其他应用的窗口中。

- thumbnail:获取文件缩略图的ExtensionAbility,开发者可以对自定义文件类型的文件提供缩略。

- preview:该ExtensionAbility会将文件解析后在一个窗口中显示,开发者可以通过将此窗口组合到其他应用窗口中。

说明:

- 其中service和dataShare类型,仅支持系统应用配置,三方应用配置不生效。

字符串

该标签不可缺省。

permissions

标识当前ExtensionAbility组件自定义的权限信息。当其他应用访问该ExtensionAbility时,需要申请相应的权限信息。

一个数组元素为一个权限名称。通常采用反向域名格式(最大255字节),可以是系统预定义的权限,也可以是该应用自定义的权限。如果是后者,需与defPermissions标签中定义的某个权限的name标签值一致。

字符串数组

该标签可缺省,缺省值为空。

uri

标识当前ExtensionAbility组件提供的数据URI,为字符数组类型(最大长度255),用反向域名的格式表示。

说明:

- 该标签在type为dataShare类型的ExtensionAbility时,不可缺省。

字符串

该标签可缺省,缺省值为空。

skills

标识当前ExtensionAbility组件能够接收的​​Want​​的特征集,为数组格式。

配置规则:entry包可以配置多个具有入口能力的skills标签(配置了action.system.home和entity.system.home)的ExtensionAbility,其中第一个配置了skills标签的ExtensionAbility中的label和icon作为HarmonyOS服务或应用的label和icon。

说明:

- HarmonyOS服务的Feature包不能配置具有入口能力的skills标签。

- HarmonyOS应用的Feature包可以配置具有入口能力的skills标签。

数组

该标签可缺省,缺省值为空。

metadata

标识当前ExtensionAbility组件的元信息。

对象

该标签可缺省,缺省值为空。

visible

标识当前ExtensionAbility组件是否可以被其他应用调用,为布尔类型。

- true:表示可以被其他应用调用。

- false:表示不可以被其他应用调用。

布尔值

该标签可缺省,缺省值为false。

extensionAbilities示例:

{
  "extensionAbilities": [
    {
      "name": "FormName",
      "srcEntrance": "./form/MyForm.ts",
      "icon": "$media:icon",
      "label" : "$string:extension_name",
      "description": "$string:form_description",
      "type": "form", 
      "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
      "readPermission": "",
      "writePermission": "",
      "visible": true,
      "uri":"scheme://authority/path/query",
      "skills": [{
        "actions": [],
        "entities": [],
        "uris": []
      }],
      "metadata": [
        {
          "name": "ohos.extension.form",
          "resource": "$profile:form_config", 
        }
      ]
    }
  ]
}

requestPermissions标签

该标签标识应用运行时需向系统申请的权限集合。

表8 requestPermissions标签说明

属性

含义

类型

取值范围

默认值

name

必须,填写需要使用的权限名称。

字符串

自定义。

无。

reason

可选,当申请的权限为user_grant权限时此字段必填,用于描述申请权限的原因。

说明:

- 当申请的权限为user_grant权限时,如果未填写该字段则不允许在应用市场上架,并且需要进行多语种适配。

字符串

使用string类资源引用。格式为$string: ***。

空。

usedScene

可选,当申请的权限为user_grant权限时此字段必填。描述权限使用的场景由abilities和when组成。其中abilities可以配置为多个UIAbility组件,when表示调用时机。

说明:

- 默认为可选,当申请的权限为user_grant权限时,abilities标签必填,when标签可选。

abilities:UIAbility或者ExtensionAbility名称的字符串数组

when:字符串

abilities:UIAbility或者ExtensionAbility组件的名称。

when:inuse(使用时)、always(始终)。

abilities:空。

when:空。

requestPermissions示例:

{
  "module" : {
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "EntryFormAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

shortcuts标签

shortcuts标识应用的快捷方式信息。标签值为数组,最多可以配置四个快捷方式。其包含四个子标签shortcutId、label、icon、wants。

metadata中指定shortcut信息,其中:

  • name:指定shortcuts的名称。使用ohos.ability.shortcuts作为shortcuts信息的标识。
  • resource:指定shortcuts信息的资源位置。

属性

含义

类型

默认值

shortcutId

标识快捷方式的ID。字符串的最大长度为63字节。

字符串

该标签不可缺省。

label

标识快捷方式的标签信息,即快捷方式对外显示的文字描述信息。取值可以是描述性内容,也可以是标识label的资源索引。字符串最大长度为255字节。

字符串

该标签可缺省,缺省值为空。

icon

标识快捷方式的图标,标签值为资源文件的索引。

字符串

该标签可缺省,缺省值为空。

​wants​

标识快捷方式内定义的目标wants信息集合,每个wants可配置bundleName和abilityName两个子标签。

bundleName:表示快捷方式的目标包名,字符串类型。

abilityName:表示快捷方式的目标组件名,字符串类型。

对象

该标签可缺省,缺省为空。

  1. 在/resource/base/profile/目录下配置shortcuts_config.json配置文件。

{
  "shortcuts": [
    {
      "shortcutId": "id_test1",
      "label": "$string:shortcut",
      "icon": "$media:aa_icon",
      "wants": [
        {
          "bundleName": "com.ohos.hello",
          "abilityName": "EntryAbility"
        }
      ]
    }
  ]
}
  1. 在module.json5配置文件的abilities标签中,针对需要添加快捷方式的UIAbility进行配置metadata标签,使shortcut配置文件对该UIAbility生效。

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntrance": "./ets/entryability/EntryAbility.ts",
        // ...
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ],
        "metadata": [
          {
            "name": "ohos.ability.shortcuts",
            "resource": "$profile:shortcuts_config"
          }
        ]
      }
    ]
  }
}

distroFilter标签

该标签下的子标签均为可选字段,在应用市场云端分发时做精准匹配使用,distroFilter用于定义HAP对应的细分设备规格的分发策略,以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Version、屏幕形状、屏幕尺寸、屏幕分辨率,设备的国家与地区码。在进行分发时,通过deviceType与这五个属性的匹配关系,唯一确定一个用于分发到设备的HAP。该标签需要配置在/resource/profile资源目录下。

表9 distroFilter标签配置说明

属性名称

含义

数据类型

是否可缺省

apiVersion

标识支持的apiVersion范围。

对象数组

该标签可缺省,缺省值为空。

screenShape

标识屏幕形状的支持策略。

对象数组

该标签可缺省,缺省值为空。

screenWindow

标识应用运行时窗口的分辨率支持策略。该字段仅支持对轻量级智能穿戴设备进行配置。

对象数组

该标签可缺省,缺省值为空。

screenDensity

标识屏幕的像素密度(dpi:Dot Per Inch)。该字段可选,如果配置了该字段,取值必须合法。该标签为字符串数组,字符串范围如下。

- sdpi:表示小规模的屏幕密度(Small-scale Dots per Inch),适用于dpi取值为(0,120]的设备。

- mdpi:表示中规模的屏幕密度(Medium-scale Dots Per Inch),适用于dpi取值为(120,160]的设备。

- ldpi:表示大规模的屏幕密度(Large-scale Dots Per Inch),适用于dpi取值为(160,240]的设备。

- xldpi:表示大规模的屏幕密度(Extra Large-scale Dots Per Inch),适用于dpi取值为(240,320]的设备。

- xxldpi:表示大规模的屏幕密度(Extra Extra Large-scale Dots Per Inch),适用于dpi取值为(320,480]的设备。

- xxxldpi:表示大规模的屏幕密度(Extra Extra Extra Large-scale Dots Per Inch),适用于dpi取值为(480, 640]的设备。

对象数组

该标签可缺省,缺省值为空。

countryCode

表示应用需要分发的国家地区码,具体值以ISO-3166-1标准为准。支持多个国家和地区枚举定义。

对象数组

该标签可缺省,缺省值为空。

表10 apiVersion标签说明

属性名称

含义

数据类型

是否可缺省

policy

标识该子属性取值规则。配置为“exclude”或“include”。

- exclude:表示需要排除的value属性。

- include:表示需要包含的value属性。

字符串

该标签不可缺省。

value

支持的取值为API Version存在的整数值,例如4、5、6。场景示例:某应用,针对相同设备型号,同时在网的为使用API 5和API 6开发的两个软件版本,则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。

数组

该标签不可缺省。

表11 screenShape对象的内部结构

属性名称

含义

数据类型

是否可缺省

policy

标识该子属性取值规则。配置为“exclude”或“include”。

- exclude:表示需要排除的value属性。

- include:表示需要包含的value属性。

字符串

该标签不可缺省。

value

支持的取值为circle(圆形)、rect(矩形)。场景示例:针对智能穿戴设备,可为圆形表盘和矩形表盘分别提供不同的HAP。

字符串数组

该标签不可缺省。

表12 screenWindow对象的内部结构说明

属性名称

含义

数据类型

是否可缺省

policy

标识该子属性取值规则。配置为“exclude”或“include”。

- exclude:表示该字段取值不包含value枚举值匹配规则的匹配该属性。

- include:表示该字段取值满足value枚举值匹配规则的匹配该属性。

字符串

该标签不可缺省。

value

单个字符串的取值格式为“宽 * 高”,取值为整数像素值,例如“454 * 454”。

字符串数组

该标签不可缺省。

表13 screenDensity对象的内部结构说明

属性名称

含义

数据类型

是否可缺省

policy

标识该子属性取值规则。配置为“exclude”或“include”。

- exclude:表示需要排除的value属性。

- include:表示需要包含的value属性。

字符串

该标签不可缺省。

value

该标签标识屏幕的像素密度(dpi :Dot Per Inch)。

字符串数组

该标签不可缺省。

表14 countryCode对象的内部结构说明

属性名称

含义

数据类型

是否可缺省

policy

标识该子属性取值规则。配置为“exclude”或“include”。

- exclude:表示需要排除的value属性。

- include:表示需要包含的value属性。

字符串

该标签不可缺省。

value

标识应用需要分发的国家地区码。

字符串数组

该标签不可缺省。

在开发视图的resources/base/profile下面定义配置文件distro_filter_config.json,文件名可以自定义。

{
  "distroFilter": {
    "apiVersion": {
      "policy": "include",
      "value": [
        3,
        4
      ]
    },
    "screenShape": {
      "policy": "include",
      "value": [
        "circle",
        "rect"
      ]
    },
    "screenWindow": {
      "policy": "include",
      "value": [
        "454*454",
        "466*466"
      ]
    },
    "screenDensity": {
      "policy": "exclude",
      "value": [
        "ldpi",
        "xldpi"
      ]
    },
    "countryCode": { // 支持中国和香港地区分发
      "policy": "include",
      "value": [
        "CN",
        "HK"
      ]
    }
  }
}

在module.json5配置文件的module标签中定义metadata信息。

{
  "module": {
    // ...
    "metadata": [
      {
        "name": "ohos.module.distro",
        "resource": "$profile:distro_filter_config",
      }
    ]
  }
}

testRunner标签

此标签用于支持对测试框架的配置。

表15 testRunner标签说明

属性名称

含义

数据类型

是否可缺省

name

标识测试框架对象名称。该标签最大字节长度为255个字节。

字符串

不可缺省。

srcPath

标识测试框架代码路径。该标签最大字节长度为255个字节。

字符串

不可缺省。

testRunner标签示例:

{
  "module": {
    // ...
    "testRunner": {
      "name": "myTestRunnerName",
      "srcPath": "etc/test/TestRunner.ts"
    }
  }
}



文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/application-configuration-file-overview-stage-0000001428061460-V3?catalogVersion=V3​

标签
收藏
回复
举报
回复
    相关推荐