【鸿蒙开发】第二十七章 应用程序包结构目录

已于 2025-02-11 11:15:09 修改
阅读量742 收藏 15
点赞数 26
分类专栏： 鸿蒙理论知识学习 文章标签： harmonyos
于 2025-02-11 11:03:29 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/wsy18201533604/article/details/145553348
版权

目录

1 应用的多Module设计机制

2 Module类型

3 Stage模型应用程序包结构

3.1 开发态包结构

3.2 编译态包结构

3.3 发布态包结构

3.4 选择合适的包类型

 4 应用程序包

4.1 HAP

4.1.1 使用场景

4.1.2 约束限制

4.1.3 创建

4.1.4 开发

4.1.5 调试

4.2 HAR

4.2.1 使用场景

4.2.2 约束限制

4.2.3 创建

4.2.4 开发

4.2.4.1 导出ArkUI组件

4.2.4.2 导出ts类和方法

4.2.4.3 导出native方法

4.2.4.4 导出资源

4.2.5 使用

4.2.5.1 引用HAR的ArkUI组件

4.2.5.2 引用HAR的ts类和方法

4.2.5.3 引用HAR的native方法

4.2.5.4 引用HAR的资源

4.2.6 编译

4.2.6.1 编译生成TS文件

4.3 HSP

4.3.1 使用场景

4.3.2 约束限制

4.3.3 创建

4.3.3.1 开发

4.3.3.2 导出ArkUI组件

4.3.3.3 导出ts类和方法

4.3.3.4 导出native方法

4.3.3.5 通过$r访问HSP中的资源

4.3.3.6 导出HSP中的资源

4.3.4 使用

4.3.4.1 引用HSP中的接口

4.3.4.2 页面路由跳转

4.3.4.3 页面路由返回

5 应用配置文件概述（Stage模型）

5.1 app.json5配置文件

5.1.1 配置文件示例

5.1.2 配置文件标签

5.1.2.1 icon标签

5.1.2.2 appEnvironments标签

5.1.2.3 multiAppMode标签

5.1.2.4  configuration标签

5.2 module.json5配置文件

5.2.1  配置文件示例

5.2.2 配置文件标签

5.2.2.1 deviceTypes标签

5.2.2.2 pages标签

5.2.2.3 metadata标签

5.2.2.4 abilities标签

5.2.2.5 skills标签

5.2.2.6 extensionAbilities标签

5.2.2.7 shortcuts标签

5.2.2.8 wants标签

5.2.2.9 distributionFilter标签

5.2.2.10 screenShape标签

5.2.2.11 screenWindow标签

5.2.2.12 screenDensity标签

5.2.2.13 countryCode标签

5.2.2.14 testRunner标签

5.2.2.15 atomicService标签

5.2.2.16 dependencies标签

5.2.2.17 proxyData标签

5.2.2.18 routerMap标签

5.2.2.19 data标签

5.2.2.20 customData标签

5.2.2.21 appEnvironments标签

5.2.2.22 definePermissions标签

5.2.2.23 hnpPackages标签

5.2.2.24 fileContextMenu标签

5.2.2.25 响应行为

1 应用的多Module设计机制

  • 支持模块化开发： 一个应用通常会包含多种功能，将不同的功能特性按模块来划分和管理是一种良好的设计方式。在开发过程中，我们可以将每个功能模块作为一个独立的Module进行开发，Module中可以包含源代码、资源文件、第三方库、配置文件等，每一个Module可以独立编译，实现特定的功能。这种模块化、松耦合的应用管理方式有助于应用的开发、维护与扩展。

  • 支持多设备适配： 一个应用往往需要适配多种设备类型，在采用多Module设计的应用中，每个Module都会标注所支持的设备类型。有些Module支持全部类型的设备，有些Module只支持某一种或几种类型的设备（比如平板），那么在应用市场分发应用包时，也能够根据设备类型做精准的筛选和匹配，从而将不同的包合理的组合和部署到对应的设备上。

2 Module类型

Module按照使用场景可以分为两种类型：

  • Ability类型的Module： 用于实现应用的功能和特性。每一个Ability类型的Module编译后，会生成一个以.hap为后缀的文件，我们称其为HAP（Harmony Ability Package）包。HAP包可以独立安装和运行，是应用安装的基本单位，一个应用中可以包含一个或多个HAP包，具体包含如下两种类型。

    • entry类型的Module：应用的主模块，包含应用的入口界面、入口图标和主功能特性，编译后生成entry类型的HAP。每一个应用分发到同一类型的设备上的应用程序包，只能包含唯一一个entry类型的HAP，也可以不包含。
    • feature类型的Module：应用的动态特性模块，编译后生成feature类型的HAP。一个应用中可以包含一个或多个feature类型的HAP，也可以不包含。

  • Library类型的Module： 用于实现代码和资源的共享。同一个Library类型的Module可以被其他的Module多次引用，合理地使用该类型的Module，能够降低开发和维护成本。Library类型的Module分为Static和Shared两种类型，编译后会生成共享包。

    • Static Library：静态共享库。编译后会生成一个以.har为后缀的文件，即静态共享包HAR（Harmony Archive）。
    • Shared Library：动态共享库。编译后会生成一个以.hsp为后缀的文件，即动态共享包HSP（Harmony Shared Package）。

    说明

    实际上，Shared Library编译后除了会生成一个.hsp文件，还会生成一个.har文件。这个.har文件中包含了HSP对外导出的接口，应用中的其他模块需要通过.har文件来引用HSP的功能。为了表述方便，我们通常认为Shared Library编译后生成HSP。

    HAR与HSP两种共享包的主要区别体现在：

    共享包类型编译和运行方式发布和引用方式
    HAR

    HAR中的代码和资源跟随使用方编译，如果有多个使用方，它们的编译产物中会存在多份相同拷贝。

    注意：编译HAR时，建议开启混淆能力，保护代码资产。

    		HAR除了支持应用内引用，还可以独立打包发布，供其他应用引用。
    HSPHSP中的代码和资源可以独立编译，运行时在一个进程中代码也只会存在一份。HSP一般随应用进行打包，当前支持应用内和集成态HSP。应用内HSP只支持应用内引用，集成态HSP支持发布到ohpm私仓和跨应用引用。

    图1 HAR和HSP在APP包中的形态示意图

3 Stage模型应用程序包结构

3.1 开发态包结构

在DevEco Studio上创建一个项目工程，并尝试创建多个不同类型的Module。根据实际工程中的目录对照本章节进行学习，可以有助于理解开发态的应用程序结构。

图1 项目工程结构示意图（以实际为准）

工程结构主要包含的文件类型及用途如下：

说明

  • AppScope目录由DevEco Studio自动生成，不可更改。
  • Module目录名称可以由DevEco Studio自动生成（比如entry、library等），也可以自定义。为了便于说明，下表中统一采用Module_name表示。
文件类型说明
配置文件

包括应用级配置信息、以及Module级配置信息：

- AppScope > app.json5：app.json5配置文件，用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等。

- Module_name > src > main > module.json5：module.json5配置文件，用于声明Module基本信息、支持的设备类型、所含的组件信息、运行所需申请的权限等。

ArkTS源码文件Module_name > src > main > ets：用于存放Module的ArkTS源码文件（.ets文件）。
资源文件

包括应用级资源文件、以及Module级资源文件，支持图形、多媒体、字符串、布局文件等，详见资源分类与访问。

- AppScope > resources ：用于存放应用需要用到的资源文件。

- Module_name > src > main > resources ：用于存放该Module需要用到的资源文件。

其他配置文件

用于编译构建，包括构建配置文件、编译构建任务脚本、混淆规则文件、依赖的共享包信息等。

- build-profile.json5：工程级或Module级的构建配置文件，包括应用签名、产品配置等。

- hvigorfile.ts：应用级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。

- obfuscation-rules.txt：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。

- oh-package.json5：用于存放依赖库的信息，包括所依赖的三方库和共享包。

3.2 编译态包结构

不同类型的Module编译后会生成对应的HAP、HAR、HSP等文件，开发态视图与编译态视图的对照关系如下：

图2 开发态与编译态的工程结构视图

从开发态到编译态，Module中的文件会发生如下变更：

  • ets目录：ArkTS源码编译生成.abc文件。
  • resources目录：AppScope目录下的资源文件会合入到Module下面资源目录中，如果两个目录下存在重名文件，编译打包后只会保留AppScope目录下的资源文件。
  • module配置文件：AppScope目录下的app.json5文件字段会合入到Module下面的module.json5文件之中，编译后生成HAP或HSP最终的module.json文件。

说明

在编译HAP和HSP时，会把他们所依赖的HAR直接编译到HAP和HSP中。

3.3 发布态包结构

每个应用中至少包含一个.hap文件，可能包含若干个.hsp文件、也可能不含，一个应用中的所有.hap与.hsp文件合在一起称为Bundle，其对应的bundleName是应用的唯一标识（详见app.json5配置文件中的bundleName标签）。

当应用发布上架到应用市场时，需要将Bundle打包为一个.app后缀的文件用于上架，这个.app文件称为App Pack（Application Package），与此同时，DevEco Studio工具自动会生成一个pack.info文件。pack.info文件描述了App Pack中每个HAP和HSP的属性，包含APP中的bundleName和versionCode信息、以及Module中的name、type和abilities等信息。

说明

  • App Pack是发布上架到应用市场的基本单元，但是不能在设备上直接安装和运行。
  • 在应用签名、云端分发、端侧安装时，都是以HAP/HSP为单位进行签名、分发和安装的。

图3 编译发布与上架部署流程图

3.4 选择合适的包类型

HAP、HAR、HSP三者的功能和使用场景总结对比如下：

Module类型包类型说明
AbilityHAP应用的功能模块，可以独立安装和运行，必须包含一个entry类型的HAP，可选包含一个或多个feature类型的HAP。
Static LibraryHAR

静态共享包，编译态复用。

- 支持应用内共享，也可以发布后供其他应用使用。

- 作为二方库，发布到OHPM私仓，供公司内部其他应用使用。

- 作为三方库，发布到OHPM中心仓，供其他应用使用。

- 多包（HAP/HSP）引用相同的HAR时，会造成多包间代码和资源的重复拷贝，从而导致应用包膨大。

- 注意：编译HAR时，建议开启混淆能力，保护代码资产。

Shared LibraryHSP

动态共享包，运行时复用。

- 当多包（HAP/HSP）同时引用同一个共享包时，采用HSP替代HAR，可以避免HAR造成的多包间代码和资源的重复拷贝，从而减小应用包大小。

HAP、HSP、HAR支持的规格对比如下，其中“√”表示是，“×”表示否。

开发者可以根据实际场景所需的能力，选择相应类型的包进行开发。在后续的章节中还会针对如何使用HAP、HAR、HSP分别展开详细介绍。

规格HAPHARHSP
支持在配置文件中声明UIAbility组件与ExtensionAbility组件√××
支持在配置文件中声明pages页面√×√
支持包含资源文件与.so文件√√√
支持依赖其他HAR文件√√√
支持依赖其他HSP文件√√√
支持在设备上独立安装运行√××

说明

  • HAR虽然不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过命名路由的方式进行跳转。
  • 由于HSP仅支持应用内共享，如果HAR依赖了HSP，则该HAR文件仅支持应用内共享，不支持发布到二方仓或三方仓供其他应用使用，否则会导致编译失败。
  • HAR和HSP均不支持循环依赖，也不支持依赖传递。

 4 应用程序包

4.1 HAP

HAP（Harmony Ability Package）是应用安装和运行的基本单元。HAP包是由代码、资源、第三方库、配置文件等打包生成的模块包，其主要分为两种类型：entry和feature。

  • entry：应用的主模块，作为应用的入口，提供了应用的基础功能。
  • feature：应用的动态特性模块，作为应用能力的扩展，可以根据用户的需求和设备类型进行选择性安装。

应用程序包可以只包含一个基础的entry包，也可以包含一个基础的entry包和多个功能性的feature包。

4.1.1 使用场景

  • 单HAP场景：如果只包含UIAbility组件，无需使用ExtensionAbility组件，优先采用单HAP（即一个entry包）来实现应用开发。虽然一个HAP中可以包含一个或多个UIAbility组件，为了避免不必要的资源加载，推荐采用“一个UIAbility+多个页面”的方式。

  • 多HAP场景：如果应用的功能比较复杂，需要使用ExtensionAbility组件，可以采用多HAP（即一个entry包+多个feature包）来实现应用开发，每个HAP中包含一个UIAbility组件或者一个ExtensionAbility组件。在这种场景下，可能会存在多个HAP引用相同的库文件，导致重复打包的问题。

4.1.2 约束限制

  • 不支持导出接口和ArkUI组件，给其他模块使用。

  • 多HAP场景下，App Pack包中同一设备类型的所有HAP中必须有且只有一个Entry类型的HAP，Feature类型的HAP可以有一个或者多个，也可以没有。

  • 多HAP场景下，同一应用中的所有HAP的配置文件中的bundleName、versionCode、versionName、minCompatibleVersionCode、debug、minAPIVersion、targetAPIVersion、apiReleaseType相同，同一设备类型的所有HAP对应的moduleName标签必须唯一。HAP打包生成App Pack包时，会对上述参数配置进行校验。

  • 多HAP场景下，同一应用的所有HAP、HSP的签名证书要保持一致。上架应用市场是以App Pack形式上架，应用市场分发时会将所有HAP从App Pack中拆分出来，同时对其中的所有HAP进行重签名，这样保证了所有HAP签名证书的一致性。在调试阶段，开发者通过命令行或DevEco Studio将HAP安装到设备上时，要保证所有HAP签名证书一致，否则会出现安装失败的问题。

4.1.3 创建

下面简要介绍如何通过DevEco Studio新建一个HAP模块。

  1. 创建工程，构建第一个ArkTS应用。

  2. 在工程目录上单击右键，选择New > Module。

  3. 在弹出的对话框中选择Empty Ability模板，单击Next。

  4. 在Module配置界面，配置Module name，选择Module Type和Device Type，然后单击Next。

  5. 在Ability配置界面，配置Ability name，然后单击Finish完成创建。

4.1.4 开发

4.1.5 调试

通过DevEco Studio编译打包，生成单个或者多个HAP，即可基于HAP进行调试。如需根据不同的部署环境、目标人群、运行环境等，将同一个HAP定制编译为不同版本，请参见定制编译指导。

开发者可以采用DevEco Studio或者hdc工具进行调试：

  • 方法一： 使用DevEco Studio进行调试，详见应用程序包调试方法。

  • 方法二： 使用hdc工具(可通过HarmonyOS SDK获取，在SDK的toolchains目录下)进行调试。

    在调试前，需要先安装或更新HAP，此处有两种方式：

    • 直接使用hdc安装、更新HAP。

      HAP的路径为开发平台上的文件路径，以Windows开发平台为例，命令参考如下：

// 安装、更新，多HAP可以指定多个文件路径
hdc install entry.hap feature.hap
// 执行结果
install bundle successfully.
// 卸载
hdc uninstall com.example.myapplication
// 执行结果
uninstall bundle successfully.
  •         先执行hdc shell，再使用bm工具安装、更新HAP。

        HAP的文件路径为真机上的文件路径，命令参考如下：

// 先执行hdc shell才能使用bm工具
hdc shell
// 安装、更新，多HAP可以指定多个文件路径
bm install -p /data/app/entry.hap /data/app/feature.hap
// 执行结果
install bundle successfully.
// 卸载
bm uninstall -n com.example.myapplication
// 执行结果
uninstall bundle successfully.

4.2 HAR

HAR（Harmony Archive）是静态共享包，可以包含代码、C++库、资源和配置文件。通过HAR可以实现多个模块或多个工程共享ArkUI组件、资源等相关代码。

4.2.1 使用场景

  • 支持应用内共享，也可以发布后供其他应用使用。
  • 作为二方库，发布到OHPM私仓，供公司内部其他应用使用。
  • 作为三方库，发布到OHPM中心仓，供其他应用使用。
  • 多包（HAP/HSP）引用相同的HAR时，会造成多包间代码和资源的重复拷贝，从而导致应用包膨大。

4.2.2 约束限制

  • HAR不支持在设备上单独安装/运行，只能作为应用模块的依赖项被引用。
  • HAR不支持在配置文件中声明UIAbility组件与ExtensionAbility组件。
  • HAR不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过命名路由的方式进行跳转。
  • HAR不支持引用AppScope目录中的资源。在编译构建时，AppScope中的内容不会打包到HAR中，因此会导致HAR资源引用失败。
  • HAR可以依赖其他HAR，但不支持循环依赖，也不支持依赖传递。

4.2.3 创建

通过DevEco Studio创建一个HAR模块，详见创建库模块。

4.2.4 开发

介绍如何导出HAR的ArkUI组件、接口、资源，供其他应用或当前应用的其他模块引用。

Index.ets文件是HAR导出声明文件的入口，HAR需要导出的接口，统一在Index.ets文件中导出。Index.ets文件是DevEco Studio默认自动生成的，用户也可以自定义，在模块的oh-package.json5文件中的main字段配置入口声明文件，配置如下所示：

{
  "main": "Index.ets"
}
4.2.4.1 导出ArkUI组件

ArkUI组件的导出方式与ts的导出方式一致，通过export导出ArkUI组件，示例如下：

// library/src/main/ets/components/mainpage/MainPage.ets
@Component
export struct MainPage {
  @State message: string = 'HAR MainPage';

  build() {
    Column() {
      Row() {
        Text(this.message)
          .fontSize(32)
          .fontWeight(FontWeight.Bold)
      }
      .margin({ top: '32px' })
      .height(56)
      .width('624px')

      Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center, alignContent: FlexAlign.Center }) {
        Column() {
          Image($r('app.media.pic_empty')).width('33%')
          Text($r('app.string.empty'))
            .fontSize(14)
            .fontColor($r('app.color.text_color'))
        }
      }.width('100%')
      .height('90%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor($r('app.color.page_background'))
  }
}

 HAR对外暴露的接口，在Index.ets导出文件中声明如下所示：

// library/Index.ets
export { MainPage } from './src/main/ets/components/mainpage/MainPage';
4.2.4.2 导出ts类和方法

通过export导出ts类和方法，支持导出多个ts类和方法，示例如下所示：

// library/src/main/ts/test.ets
export class Log {
    static info(msg: string) {
        console.info(msg);
    }
}

export function func() {
  return 'har func';
}

export function func2() {
  return 'har func2';
}

 HAR对外暴露的接口，在Index.ets导出文件中声明如下所示：

// library/Index.ets
export { Log } from './src/main/ts/test';
export { func } from './src/main/ts/test';
export { func2 } from './src/main/ts/test';
4.2.4.3 导出native方法

在HAR中也可以包含C++编写的so。对于so中的native方法，HAR通过以下方式导出，以导出liblibrary.so的加法接口add为例：

// library/src/main/ets/utils/nativeTest.ets
import native from 'liblibrary.so';

export function nativeAdd(a: number, b: number): number {
  let result: number = native.add(a, b);
  return result;
}

 HAR对外暴露的接口，在Index.ets导出文件中声明如下所示：

// library/Index.ets
export { nativeAdd } from './src/main/ets/utils/nativeTest';
4.2.4.4 导出资源

在编译构建HAP时，DevEco Studio会从HAP模块及依赖的模块中收集资源文件，如果不同模块下的资源文件出现重名冲突时，DevEco Studio会按照以下优先级进行覆盖（优先级由高到低）：

  • AppScope（仅Stage模型支持）。
  • HAP包自身模块。
  • 依赖的HAR模块，如果依赖的多个HAR之间有资源冲突，会按照工程oh-package.json5中dependencies下的依赖顺序进行覆盖，依赖顺序在前的优先级较高。例如下方示例中dayjs和lottie中包含同名文件时，会优先使用dayjs中的资源。

说明

如果在AppScope/HAP模块/HAR模块的国际化目录中配置了资源，在相同的国际化限定词下，合并的优先级也遵循上述规则。同时，国际化限定词中配置的优先级高于在base中的配置。如：在AppScope的base中配置了资源字段，在HAR模块的en_US中配置了同样的资源字段，则在en_US的使用场景中，会更优先使用HAR模块中配置的资源字段。

// oh-package.json5
{
  "dependencies": {
    "dayjs": "^1.10.4",
    "lottie": "^2.0.0"
  }
}

4.2.5 使用

介绍如何配置HAR依赖，并引用HAR的ArkUI组件、接口、资源。

引用HAR前，需要先配置对HAR的依赖，详见引用HAR文件和资源。

4.2.5.1 引用HAR的ArkUI组件

HAR的依赖配置成功后，可以引用HAR的ArkUI组件。ArkUI组件的导入方式与ts的导入方式一致，通过import引入HAR导出的ArkUI组件，示例如下所示：

// entry/src/main/ets/pages/IndexSec.ets
import { MainPage } from 'library';

@Entry
@Component
struct IndexSec {
  build() {
    Row() {
      // 引用HAR的ArkUI组件
      MainPage()
    }
    .height('100%')
  }
}
4.2.5.2 引用HAR的ts类和方法

通过import引用HAR导出的ts类和方法，示例如下所示：

// entry/src/main/ets/pages/Index.ets
import { Log } from 'library';
import { func } from 'library';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Column() {
      Text(this.message)
        .fontFamily('HarmonyHeiTi')
        .fontWeight(FontWeight.Bold)
        .fontSize(32)
        .fontWeight(700)
        .fontColor($r('app.color.text_color'))
        .textAlign(TextAlign.Start)
        .margin({ top: '32px' })
        .width('624px')

      //引用HAR的ts类和方法
      Button($r('app.string.button'))
        .id('button')
        .height(48)
        .width('624px')
        .margin({ top: '4%' })
        .type(ButtonType.Capsule)
        .fontFamily('HarmonyHeiTi')
        .borderRadius($r('sys.float.ohos_id_corner_radius_button'))
        .backgroundColor($r('app.color.button_background'))
        .fontColor($r('sys.color.ohos_id_color_foreground_contrary'))
        .fontSize($r('sys.float.ohos_id_text_size_button1'))
        .onClick(() => {
          // 引用HAR的类和方法
          Log.info('har msg');
          this.message = 'func return: ' + func();
        })
    }
    .width('100%')
    .backgroundColor($r('app.color.page_background'))
    .height('100%')
  }
}
4.2.5.3 引用HAR的native方法

通过import引用HAR导出的native方法，示例如下所示：

// entry/src/main/ets/pages/Index.ets
import { nativeAdd } from 'library';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Column() {
      Text(this.message)
        .fontFamily('HarmonyHeiTi')
        .fontWeight(FontWeight.Bold)
        .fontSize(32)
        .fontWeight(700)
        .fontColor($r('app.color.text_color'))
        .textAlign(TextAlign.Start)
        .margin({ top: '32px' })
        .width('624px')

      //引用HAR的native方法
      Button($r('app.string.native_add'))
        .id('nativeAdd')
        .height(48)
        .width('624px')
        .margin({ top: '4%', bottom: '6%' })
        .type(ButtonType.Capsule)
        .fontFamily('HarmonyHeiTi')
        .borderRadius($r('sys.float.ohos_id_corner_radius_button'))
        .backgroundColor($r('app.color.button_background'))
        .fontColor($r('sys.color.ohos_id_color_foreground_contrary'))
        .fontSize($r('sys.float.ohos_id_text_size_button1'))
        .onClick(() => {
          this.message = 'result: ' + nativeAdd(1, 2);
        })
    }
    .width('100%')
    .backgroundColor($r('app.color.page_background'))
    .height('100%')
  }
}
4.2.5.4 引用HAR的资源

通过$r引用HAR中的资源，例如在HAR模块的src/main/resources里添加字符串资源（在string.json中定义，name：hello_har）和图片资源（icon_har.png），然后在Entry模块中引用该字符串和图片资源的示例如下所示：

// entry/src/main/ets/pages/Index.ets
@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Column() {
      // 引用HAR的字符串资源
      Text($r('app.string.hello_har'))
        .id('stringHar')
        .fontFamily('HarmonyHeiTi')
        .fontColor($r('app.color.text_color'))
        .fontSize(24)
        .fontWeight(500)
        .margin({ top: '40%' })

      List() {
        ListItem() {
          // 引用HAR的图片资源
          Image($r('app.media.icon_har'))
            .id('iconHar')
            .borderRadius('48px')
        }
        .margin({ top: '5%' })
        .width('312px')
      }
      .alignListItem(ListItemAlign.Center)
    }
    .width('100%')
    .backgroundColor($r('app.color.page_background'))
    .height('100%')
  }
}

4.2.6 编译

HAR可以作为二方库和三方库提供给其他应用使用，如果需要对代码资产进行保护时，建议开启混淆能力。

混淆能力开启后，DevEco Studio在构建HAR时，会对代码进行编译、混淆及压缩处理，保护代码资产。

HAR模块原先默认开启混淆能力，会对API 10及以上的HAR模块，且编译模块为release时，自动进行简单的代码混淆；从DevEco Studio 5.0.3.600开始，新建工程默认关闭代码混淆功能，可以在HAR模块的build-profile.json5文件中的ruleOptions字段下的enable进行开启混淆，详情请见代码混淆，配置如下所示：

{
  "apiType": "stageMode",
  "buildOption": {
  },
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": {
            "enable": true,
            "files": [
              "./obfuscation-rules.txt"
            ]
          },
          "consumerFiles": [
            "./consumer-rules.txt"
          ]
        }
      }
    },
  ],
  "targets": [
    {
      "name": "default"
    }
  ]
}
4.2.6.1 编译生成TS文件

说明

在HAR中使用Sendable时，开启该配置。

使用限制

在依赖TS HAR时，禁止引用TS HAR中的ArkUI组件。

HAR模块中arkts文件编译后，默认产物为js文件，想要将产物修改为ts文件，可以在HAR模块下的module.json5文件中将"metadata"字段下的"name"设置为“UseTsHar”，配置如下所示：

{
  "module": {
    "name": "TsClosedHar",
    "type": "har",
    "deviceTypes": [
      "default",
      "tablet",
      "2in1"
    ],
    "metadata": [
      {
        "name": "UseTsHar",
        "value": "true"
      }
    ]
  }
}

4.3 HSP

HSP（Harmony Shared Package）是动态共享包，可以包含代码、C++库、资源和配置文件，通过HSP可以实现代码和资源的共享。HSP不支持独立发布，而是跟随其宿主应用的APP包一起发布，与宿主应用同进程，具有相同的包名和生命周期。

说明

应用内HSP：在编译过程中与应用包名（bundleName）强耦合，只能给某个特定的应用使用。

集成态HSP：构建、发布过程中，不与特定的应用包名耦合；使用时，工具链支持自动将集成态HSP的包名替换成宿主应用包名。

4.3.1 使用场景

  • 多个HAP/HSP共用的代码和资源放在同一个HSP中，可以提高代码、资源的可重用性和可维护性，同时编译打包时也只保留一份HSP代码和资源，能够有效控制应用包大小。

  • HSP在运行时按需加载，有助于提升应用性能。

  • 同一个组织内部的多个应用之间，可以使用集成态HSP实现代码和资源的共享。

4.3.2 约束限制

  • HSP不支持在设备上单独安装/运行，需要与依赖该HSP的HAP一起安装/运行。HSP的版本号必须与HAP版本号一致。
  • HSP不支持在配置文件中声明ExtensionAbility组件，但支持UIAbility（除入口ability外）组件。
  • HSP可以依赖其他HAR或HSP，但不支持循环依赖，也不支持依赖传递。

4.3.3 创建

通过DevEco Studio创建一个HSP模块，详见创建HSP模块，我们以创建一个名为library的HSP模块为例。基本的工程目录结构如下：

MyApplication
├── library
│   ├── src
│   │   └── main
│   │       ├── ets
│   │       │   └── pages
│   │       │       └── index.ets
│   │       ├── resources
│   │       └── module.json5
│   ├── oh-package.json5
│   ├── index.ets
│   └── build-profile.json5 //模块级
└── build-profile.json5     //工程级
4.3.3.1 开发

介绍如何导出HSP的ArkUI组件、接口、资源，供应用内的其他HAP/HSP引用。

4.3.3.2 导出ArkUI组件

ArkUI组件可以通过export导出，例如：

// library/src/main/ets/components/MyTitleBar.ets
@Component
export struct MyTitleBar {
  build() {
    Row() {
      Text($r('app.string.library_title'))
        .id('library')
        .fontFamily('HarmonyHeiTi')
        .fontWeight(FontWeight.Bold)
        .fontSize(32)
        .fontColor($r('app.color.text_color'))
    }
    .width('100%')
  }
}

对外暴露的接口，需要在入口文件index.ets中声明：

// library/index.ets
export { MyTitleBar } from './src/main/ets/components/MyTitleBar';
4.3.3.3 导出ts类和方法

通过export导出ts类和方法，例如：

// library/src/main/ets/utils/test.ets
export class Log {
  static info(msg: string): void {
    console.info(msg);
  }
}

export function add(a: number, b: number): number {
  return a + b;
}

export function minus(a: number, b: number): number {
  return a - b;
}

对外暴露的接口，需要在入口文件index.ets中声明：

// library/index.ets
export { Log, add, minus } from './src/main/ets/utils/test';
4.3.3.4 导出native方法

在HSP中也可以包含C++编写的so。对于so中的native方法，HSP通过间接的方式导出，以导出liblibrary.so的乘法接口multi为例：

// library/src/main/ets/utils/nativeTest.ets
import native from 'liblibrary.so';

export function nativeMulti(a: number, b: number): number {
  let result: number = native.multi(a, b);
  return result;
}

对外暴露的接口，需要在入口文件index.ets中声明：

// library/index.ets
export { nativeMulti } from './src/main/ets/utils/nativeTest';
4.3.3.5 通过$r访问HSP中的资源

在组件中，经常需要使用字符串、图片等资源。HSP中的组件需要使用资源时，一般将其所用资源放在HSP包内，而非放在HSP的使用方处，以符合高内聚低耦合的原则。

在工程中，常通过$r/$rawfile的形式引用应用资源。可以用$r/$rawfile访问本模块resources目录下的资源，如访问resources目录下定义的图片src/main/resources/base/media/example.png时，可以用$r("app.media.example")。有关$r/$rawfile的详细使用方式，请参阅文档资源分类与访问中“资源访问-应用资源”小节。

不推荐使用相对路径的方式，容易引用错误路径。例如：

当要引用上述同一图片资源时，在HSP模块中使用Image("../../resources/base/media/example.png")，实际上该Image组件访问的是HSP调用方（如entry）下的资源entry/src/main/resources/base/media/example.png。

// library/src/main/ets/pages/Index.ets
// 正确用例
Image($r('app.media.example'))
  .id('example')
  .borderRadius('48px')
// 错误用例
Image("../../resources/base/media/example.png")
  .id('example')
  .borderRadius('48px')
4.3.3.6 导出HSP中的资源

跨包访问HSP内资源时，推荐实现一个资源管理类，以封装对外导出的资源。采用这种方式，具有如下优点：

  • HSP开发者可以控制自己需要导出的资源，不需要对外暴露的资源可以不用导出。
  • 使用方无须感知HSP内部的资源名称。当HSP内部的资源名称发生变化时，也不需要使用方跟着修改。

其具体实现如下：

将需要对外提供的资源封装为一个资源管理类：

// library/src/main/ets/ResManager.ets
export class ResManager{
  static getPic(): Resource{
    return $r('app.media.pic');
  }
  static getDesc(): Resource{
    return $r('app.string.shared_desc');
  }
}

对外暴露的接口，需要在入口文件index.ets中声明：

// library/index.ets
export { ResManager } from './src/main/ets/ResManager';

4.3.4 使用

介绍如何引用HSP中的接口，以及如何通过页面路由实现HSP的pages页面跳转与返回。

4.3.4.1 引用HSP中的接口

要使用HSP中的接口，首先需要在使用方的oh-package.json5中配置对它的依赖，详见引用动态共享包。

依赖配置成功后，就可以像使用HAR一样调用HSP的对外接口了。例如，上面的library已经导出了下面这些接口：

// library/index.ets
export { Log, add, minus } from './src/main/ets/utils/test';
export { MyTitleBar } from './src/main/ets/components/MyTitleBar';
export { ResManager } from './src/main/ets/ResManager';
export { nativeMulti } from './src/main/ets/utils/nativeTest';

在使用方的代码中，可以这样使用：

// entry/src/main/ets/pages/index.ets
import { Log, add, MyTitleBar, ResManager, nativeMulti } from 'library';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';

const TAG = 'Index';

@Entry
@Component
struct Index {
  @State message: string = '';

  build() {
    Column() {
      List() {
        ListItem() {
          MyTitleBar()
        }
        .margin({ left: '35px', top: '32px' })

        ListItem() {
          Text(this.message)
            .fontFamily('HarmonyHeiTi')
            .fontSize(18)
            .textAlign(TextAlign.Start)
            .width('100%')
            .fontWeight(FontWeight.Bold)
        }
        .width('685px')
        .margin({ top: 30, bottom: 10 })

        ListItem() {
          // ResManager返回的Resource对象，可以传给组件直接使用，也可以从中取出资源来使用
          Image(ResManager.getPic())
            .id('image')
            .borderRadius('48px')
        }
        .width('685px')
        .margin({ top: 10, bottom: 10 })
        .padding({ left: 12, right: 12, top: 4, bottom: 4 })

        ListItem() {
          Text($r('app.string.add'))
            .fontSize(18)
            .textAlign(TextAlign.Start)
            .width('100%')
            .fontWeight(500)
            .height('100%')
        }
        .id('add')
        .borderRadius(24)
        .width('685px')
        .height('84px')
        .backgroundColor($r('sys.color.ohos_id_color_foreground_contrary'))
        .margin({ top: 10, bottom: 10 })
        .padding({ left: 12, right: 12, top: 4, bottom: 4 })
        .onClick(() => {
          Log.info('add button click!');
          this.message = 'result: ' + add(1, 2);
        })

        ListItem() {
          Text($r('app.string.get_string_value'))
            .fontSize(18)
            .textAlign(TextAlign.Start)
            .width('100%')
            .fontWeight(500)
            .height('100%')
        }
        .id('getStringValue')
        .borderRadius(24)
        .width('685px')
        .height('84px')
        .backgroundColor($r('sys.color.ohos_id_color_foreground_contrary'))
        .margin({ top: 10, bottom: 10 })
        .padding({ left: 12, right: 12, top: 4, bottom: 4 })
        .onClick(() => {
          // 先通过当前上下文获取hsp模块的上下文，再获取hsp模块的resourceManager，然后再调用resourceManager的接口获取资源
          getContext()
            .createModuleContext('library')
            .resourceManager
            .getStringValue(ResManager.getDesc())
            .then(value => {
              console.log('getStringValue is ' + value);
              this.message = 'getStringValue is ' + value;
            })
            .catch((err: BusinessError) => {
              console.error('getStringValue promise error is ' + err);
            });
        })

        ListItem() {
          Text($r('app.string.native_multi'))
            .fontSize(18)
            .textAlign(TextAlign.Start)
            .width('100%')
            .fontWeight(500)
            .height('100%')
        }
        .id('nativeMulti')
        .borderRadius(24)
        .width('685px')
        .height('84px')
        .backgroundColor($r('sys.color.ohos_id_color_foreground_contrary'))
        .margin({ top: 10, bottom: 10 })
        .padding({ left: 12, right: 12, top: 4, bottom: 4 })
        .onClick(() => {
          Log.info('nativeMulti button click!');
          this.message = 'result: ' + nativeMulti(3, 4);
        })
      }
      .alignListItem(ListItemAlign.Center)
    }
    .width('100%')
    .backgroundColor($r('app.color.page_background'))
    .height('100%')
  }
}
4.3.4.2 页面路由跳转

若开发者想在entry模块中，添加一个按钮跳转至library模块中的menu页面（路径为：library/src/main/ets/pages/menu.ets），那么可以在使用方的代码（entry模块下的Index.ets，路径为：entry/src/main/ets/pages/Index.ets）里这样使用：

import { Log, add, MyTitleBar, ResManager, nativeMulti } from 'library';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';

const TAG = 'Index';

@Entry
@Component
struct Index {
  @State message: string = '';

  build() {
    Column() {
      List() {
        ListItem() {
          Text($r('app.string.click_to_menu'))
            .fontSize(18)
            .textAlign(TextAlign.Start)
            .width('100%')
            .fontWeight(500)
            .height('100%')
        }
        .id('clickToMenu')
        .borderRadius(24)
        .width('685px')
        .height('84px')
        .backgroundColor($r('sys.color.ohos_id_color_foreground_contrary'))
        .margin({ top: 10, bottom: 10 })
        .padding({ left: 12, right: 12, top: 4, bottom: 4 })
        .onClick(() => {
          router.pushUrl({
            url: '@bundle:com.samples.hspsample/library/ets/pages/Menu'
          }).then(() => {
            console.log('push page success');
          }).catch((err: BusinessError) => {
            console.error('pushUrl failed, code is' + err.code + ', message is' + err.message);
          })
        })
      }
      .alignListItem(ListItemAlign.Center)
    }
    .width('100%')
    .backgroundColor($r('app.color.page_background'))
    .height('100%')
  }
}

其中router.pushUrl方法的入参中url的内容为：

'@bundle:com.samples.hspsample/library/ets/pages/Menu'

url内容的模板为：

'@bundle:包名（bundleName）/模块名（moduleName）/路径/页面所在的文件名(不加.ets后缀)'
4.3.4.3 页面路由返回

如果当前处于HSP中的页面，需要返回之前的页面时，可以使用router.back方法，但是返回的页面必须是当前页面跳转路径上的页面。

import router from '@ohos.router';

@Entry
@Component
struct Index3 { // 路径为：`library/src/main/ets/pages/Back.ets
  @State message: string = 'HSP back page';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontFamily('HarmonyHeiTi')
          .fontWeight(FontWeight.Bold)
          .fontSize(32)
          .fontColor($r('app.color.text_color'))
          .margin({ top: '32px' })
          .width('624px')

        Button($r('app.string.back_to_HAP'))
          .id('backToHAP')
          .fontFamily('HarmonyHeiTi')
          .height(48)
          .width('624px')
          .margin({ top: 550 })
          .type(ButtonType.Capsule)
          .borderRadius($r('sys.float.ohos_id_corner_radius_button'))
          .backgroundColor($r('app.color.button_background'))
          .fontColor($r('sys.color.ohos_id_color_foreground_contrary'))
          .fontSize($r('sys.float.ohos_id_text_size_button1'))
            // 绑定点击事件
          .onClick(() => {
            router.back({ //  返回HAP的页面
              url: 'pages/Index' // 路径为：`entry/src/main/ets/pages/Index.ets`
            })
          })

        Button($r('app.string.back_to_HSP'))
          .id('backToHSP')
          .fontFamily('HarmonyHeiTi')
          .height(48)
          .width('624px')
          .margin({ top: '4%' , bottom: '6%' })
          .type(ButtonType.Capsule)
          .borderRadius($r('sys.float.ohos_id_corner_radius_button'))
          .backgroundColor($r('app.color.button_background'))
          .fontColor($r('sys.color.ohos_id_color_foreground_contrary'))
          .fontSize($r('sys.float.ohos_id_text_size_button1'))
            // 绑定点击事件
          .onClick(() => {
            router.back({ //  返回HSP的页面
              url: '@bundle:com.samples.hspsample/library/ets/pages/Menu' //路径为：`library/src/main/ets/pages/Menu.ets
            })
          })
      }
      .width('100%')
    }
    .backgroundColor($r('app.color.page_background'))
    .height('100%')
  }
}

页面返回router.back方法的入参中url说明：

  • 如果从HSP页面返回HAP页面，url的内容为

'pages/Index'
  • 如果从HSP1的页面跳到HSP2的页面后，需要返回到HSP1的页面，url的内容为：
'@bundle:com.samples.hspsample/library/ets/pages/Menu'

5 应用配置文件概述（Stage模型）

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

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

app.json5配置文件主要包含以下内容：

  • 应用的全局配置信息，包含应用的Bundle名称、开发厂商、版本号等基本信息。

  • 特定设备类型的配置信息。

module.json5配置文件主要包含以下内容：

  • Module的基本配置信息，包含Module名称、类型、描述、支持的设备类型等基本信息。

  • 应用组件信息，包含UIAbility组件和ExtensionAbility组件的描述信息。

  • 应用运行过程中所需的权限信息。

5.1 app.json5配置文件

5.1.1 配置文件示例

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

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:layered-image",
    "label": "$string:app_name",
    "description": "$string:description_application",
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "car": {
      "minAPIVersion": 8
    },
    "targetBundleName": "com.application.test",
    "targetPriority": 50,
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ],
    "maxChildProcess": 5,
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 5
    },
    "cloudFileSyncEnabled": false,
    "configuration": "$profile:configuration"
  },
}

5.1.2 配置文件标签

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

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

属性名称含义数据类型是否可缺省
bundleName

标识应用的Bundle名称，用于标识应用的唯一性。命名规则如下 ：

- 由字母、数字、下划线和符号“.”组成，且必须以字母开头。

- 字符串最小长度为7字节，最大长度128字节。

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

对于随系统源码编译的应用，建议命名为“com.ohos.demo”形式，其中的ohos标识系统应用。

字符串该标签不可缺省。
bundleType

标识应用的Bundle类型，用于区分应用或者元服务。支持的取值如下：

- app：当前Bundle为应用。

- atomicService：当前Bundle为元服务。

- shared：当前Bundle为共享库应用，预留字段。

- appService：当前Bundle为系统级共享库应用，仅供系统应用使用。

字符串该标签可缺省，缺省值为app。
debug

标识应用是否可调试。

- true：可调试，一般用于开发阶段。

- false：不可调试，一般用于发布阶段。

布尔值由DevEco Studio编译构建时生成。该标签可缺省，缺省值为false。
icon标识应用的图标，取值为图标资源文件的索引。字符串该标签不可缺省。
label标识应用的名称，取值为字符串资源的索引，字符串长度不超过63字节。字符串该标签不可缺省。
description标识应用的描述信息，取值为长度不超过255字节的字符串，内容为描述信息的字符串资源索引。该字段可用于应用信息展示，如在应用的关于页面，取该字段展示应用描述信息。字符串该标签可缺省，缺省值为空。
vendor标识对应用开发厂商的描述，取值为长度不超过255字节的字符串。该字段可用于展示开发厂商信息，如在应用的关于页面，取该字段展示开发厂商信息。字符串该标签可缺省，缺省值为空。
versionCode

标识应用的版本号，取值为小于2^31次方的正整数。此数字仅用于确定某个版本是否比另一个版本更新，数值越大表示版本越高。

开发者可以将该值设置为任何正整数，但是必须确保应用的新版本都使用比旧版本更大的值。

数值该标签不可缺省。
versionName

标识向用户展示的应用版本号。

取值为长度不超过127字节的字符串，仅由数字和点构成，推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。

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

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

第三段：特性版本号/Feature，范围0~99，标识规划的新版本特性。

第四段：修订版本号/Patch，范围0~999，表示维护版本，如修复bug。

字符串该标签不可缺省。
minCompatibleVersionCode标识应用能够兼容的最低历史版本号，用于应用多设备之间协同、数据迁移、跨设备兼容性判断，该字段为预留字段，暂未使用。取值范围为0~2147483647。数值该标签可缺省，缺省值等于versionCode标签值。
minAPIVersion标识应用运行需要的SDK的API最小版本。取值范围为0~2147483647。数值应用编译构建时由build-profile.json5中的compatibleSdkVersion自动生成。
targetAPIVersion标识应用运行需要的API目标版本。取值范围为0~2147483647。数值应用编译构建时由build-profile.json5中的compileSdkVersion自动生成。
apiReleaseType

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

- Canary：受限发布的版本。

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

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

字符串应用编译构建时根据当前使用的SDK的Stage自动生成。即便手动配置了取值，编译构建时也会被覆盖。
accessible标识应用是否能访问应用的安装目录，仅针对Stage模型的系统应用和预置应用生效。布尔值该标签可缺省，缺省值为false。
multiProjects

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

- true：当前工程支持多个工程的联合开发。多工程开发可参考多工程构建。

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

布尔值该标签可缺省，缺省值为false。
asanEnabled

标识应用程序是否开启asan检测，用于辅助定位buffer越界造成的crash问题。

- true：当前工程开启asan检测。

- false：当前工程不开启asan检测。

布尔值该标签可缺省，缺省值为false。
tablet

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

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

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

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

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

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

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

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

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

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

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

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

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

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

对象该标签可缺省，缺省时default设备使用app.json5公共区域配置的属性值。
targetBundleName标识当前包所指定的目标应用, 标签值的取值规则和范围与bundleName标签一致。配置该字段的应用为具有overlay特征的应用。字符串该标签可缺省，缺省值为空。
targetPriority标识当前应用的优先级，取值范围为1~100。配置targetBundleName字段之后，才支持配置该字段。数值该标签可缺省, 缺省值为1。
generateBuildHash

标识当前应用的所有HAP和HSP是否由打包工具生成哈希值。

该字段配置为true时，该应用下的所有HAP和HSP都会由打包工具生成对应的哈希值。系统OTA升级时，若应用的versionCode保持不变，可根据哈希值判断应用是否需要升级。

说明：

该字段仅对预置应用生效。

布尔值该标签可缺省, 缺省值为false。
GWPAsanEnabled

标识应用程序是否开启GWP-asan堆内存检测工具，用于对内存越界、内存释放后使用等内存破坏问题进行分析。

- true：当前工程开启GWP-asan检测。

- false：当前工程不开启GWP-asan检测。

布尔值该标签可缺省, 缺省值为false。
appEnvironments标识当前模块配置的应用环境变量。对象数组该标签可缺省，缺省值为空。
maxChildProcess标识当前应用自身可创建的子进程的最大个数，取值范围为0到512，0表示不限制，当应用有多个模块时，以entry模块的配置为准。数值该标签可缺省，缺省时使用系统配置的默认值。
multiAppMode标识当前应用配置的多开模式。仅bundleType为app的应用的entry或feature模块配置有效，存在多个模块时，以entry模块的配置为准。对象该标签可缺省，缺省值为空。
cloudFileSyncEnabled

标识当前应用是否启用端云文件同步能力。

- true：当前应用启用端云文件同步能力。

- false：当前应用不启用端云文件同步能力。

布尔值该标签可缺省，缺省值为false。
configuration

标识当前应用字体大小跟随系统配置的能力。

该标签是一个profile文件资源，用于指定描述应用字体大小跟随系统变更的配置文件。

字符串该标签可缺省，缺省时configuration使用不跟随系统默认设定。
5.1.2.1 icon标签

此标签标识应用的图标和对分层图标配置文件的索引。

支持分层图标的配置，具体方式如下：

  1. 将图标的前景资源和背景资源放在AppScope/resources/base/media目录下。

  2. 在上述media目录下创建一个json文件（例如：layered-image.json），在文件中引用前景资源和背景资源，详见图标资源规范。

分层图标资源文件示例：

{
  "layered-image"：
    {
      "background":"$media:background", //背景资源
      "foreground":"$media:foreground" //前景资源 
    }    
}

 icon标签示例：

{
  "app":{
    "icon":"$media:layered-image"
  }
}
5.1.2.2 appEnvironments标签

此标签标识应用配置的环境变量。应用运行时有时会依赖一些三方库，这些三方库会使用到一些自定义的环境变量，为了不修改三方库的实现逻辑，可以在工程的配置文件中设置自定义的环境变量，以供运行时期使用。

表2 appEnvironments标签说明

属性名称含义数据类型是否可缺省
name标识环境变量的变量名称。取值为长度不超过4096字节的字符串。字符串该标签可缺省，缺省值为空。
value标识环境变量的值。取值为长度不超过4096字节的字符串。字符串该标签可缺省，缺省值为空。

appEnvironments标签示例：

{
  "app": {
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ]
  }
}

5.1.2.3 multiAppMode标签

应用多开模式。

表3 multiAppMode标签说明

属性名称含义数据类型是否可缺省
multiAppModeType

标识应用多开模式类型，支持的取值如下：

- multiInstance：多实例模式。该字段仅支持2in1设备。

- appClone：应用分身模式。

字符串该标签不可缺省。
maxCount

标识最大允许的应用多开个数，支持的取值如下：

- multiInstance模式：取值范围1~10。

- appClone模式：取值范围1~5。

数值该标签不可缺省。

multiAppMode标签示例：

{
  "app": {
    "multiAppMode": {
      "multiAppModeType": "appClone",
      "maxCount": 5
    }
  }
}
5.1.2.4  configuration标签

该标签是一个profile文件资源，用于指定描述应用字体大小跟随系统变更的配置文件。

configuration标签示例：

{
  "app": {
    "configuration": "$profile:configuration"  
  }
}

在开发视图的AppScope/resources/base/profile下面定义配置文件configuration.json，其中文件名"configuration"可自定义，需要和configuration标签指定的信息对应。配置文件中列举了当前应用字体大小跟随系统变化的属性。

表4 configuration标签说明

属性名称含义数据类型是否可缺省
fontSizeScale

应用字体大小是否跟随系统，支持的取值如下：

- followSystem：跟随系统。

- nonFollowSystem：不跟随系统。

字符串该标签可缺省，缺省值为nonFollowSystem。
fontSizeMaxScale

应用字体大小选择跟随系统后，配置的最大比例，支持的取值：1、1.15、1.3、1.45、1.75、2、3.2。

fontSizeScale为nonFollowSystem时，该项不生效。

字符串该标签可缺省，缺省值为3.2。

configuration标签示例：

{
  "configuration": {
    "fontSizeScale": "followSystem",
    "fontSizeMaxScale": "3.2"
  }
}

5.2 module.json5配置文件

5.2.1  配置文件示例

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

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "tv",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "virtualMachine": "ark",
    "metadata": [
      {
        "name": "string",
        "value": "string",
        "resource": "$profile:distributionFilter_config"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  },
  "targetModuleName": "feature",
  "targetPriority": 50,
  "isolationMode": "nonisolationFirst"
}

5.2.2 配置文件标签

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

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

属性名称含义数据类型是否可缺省
name

标识当前Module的名称，确保该名称在整个应用中唯一。命名规则如下 ：

- 由字母、数字和下划线组成，且必须以字母开头。

- 最大长度31字节。

应用升级时允许修改该名称，但需要应用适配Module相关数据目录的迁移，详见文件管理接口。

字符串该标签不可缺省。
type

标识当前Module的类型。支持的取值如下：

- entry：应用的主模块。

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

- har：静态共享包模块。

- shared：动态共享包模块。

字符串该标签不可缺省。
srcEntry标识当前Module所对应的代码路径，取值为长度不超过127字节的字符串。字符串该标签可缺省，缺省值为空。
description标识当前Module的描述信息，取值为长度不超过255字节的字符串，可以采用字符串资源索引格式。字符串该标签可缺省，缺省值为空。
mainElement标识当前Module的入口UIAbility名称或者ExtensionAbility名称，取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
deviceTypes

标识当前Module可以运行在哪类设备上。

说明：

当存在多个模块时，各模块中的配置可以不一致，但必须包含所需的设备类型以确保正常运行。

字符串数组该标签不可缺省。
deliveryWithInstall

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

- true：主动安装时安装。

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

布尔值该标签不可缺省。
installationFree

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

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

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

说明：

当bundleType为元服务时，该字段需要配置为true。反之，该字段需要配置为false。

布尔值该标签不可缺省。
virtualMachine标识当前Module运行的目标虚拟机类型，供云端分发使用，如应用市场和分发中心。如果目标虚拟机类型为ArkTS引擎，则其值为“ark+版本号”。字符串该标签由IDE构建HAP的时候自动插入。
pages标识当前Module的profile资源，用于列举每个页面信息，取值为长度不超过255字节的字符串。字符串在有UIAbility的场景下，该标签不可缺省。
metadata标识当前Module的自定义元信息，可通过资源引用的方式配置distributionFilter、shortcuts等信息。只对当前Module、UIAbility、ExtensionAbility生效。对象数组该标签可缺省，缺省值为空。
abilities标识当前Module中UIAbility的配置信息，只对当前UIAbility生效。对象数组该标签可缺省，缺省值为空。
extensionAbilities标识当前Module中ExtensionAbility的配置信息，只对当前ExtensionAbility生效。对象数组该标签可缺省，缺省值为空。
definePermissions标识系统资源hap定义的权限，不支持应用自定义权限。对象数组该标签可缺省，缺省值为空。
requestPermissions标识当前应用运行时需向系统申请的权限集合。对象数组该标签可缺省，缺省值为空。
testRunner标识用于测试当前Module的测试框架的配置。对象该标签可缺省，缺省值为空。
atomicService标识当前应用是元服务时，有关元服务的相关配置。对象该标签可缺省，缺省值为空。
dependencies标识当前模块运行时依赖的共享库列表。对象数组该标签可缺省，缺省值为空。
targetModuleName标识当前包所指定的目标module，确保该名称在整个应用中唯一。取值为长度不超过31字节的字符串，不支持中文。配置该字段的Module具有overlay特性。仅在动态共享包（HSP）中适用。字符串该标签可缺省，缺省值为空。
targetPriority标识当前Module的优先级，取值范围为1~100。配置targetModuleName字段之后，才需要配置该字段。仅在动态共享包（HSP）中适用。整型数值该标签可缺省，缺省值为1。
proxyData标识当前Module提供的数据代理列表。对象数组该标签可缺省，缺省值为空。
isolationMode

标识当前Module的多进程配置项。支持的取值如下：

- nonisolationFirst：优先在非独立进程中运行。

- isolationFirst：优先在独立进程中运行。

- isolationOnly：只在独立进程中运行。

- nonisolationOnly：只在非独立进程中运行。

字符串该标签可缺省，缺省值为nonisolationFirst。
generateBuildHash

标识当前HAP/HSP是否由打包工具生成哈希值。当配置为true时，如果系统OTA升级时应用versionCode保持不变，可根据哈希值判断应用是否需要升级。

该字段仅在app.json5文件中的generateBuildHash字段为false时使能。

说明：

该字段仅对预置应用生效。

布尔值该标签可缺省，缺省值为false。
compressNativeLibs

标识libs库是否以压缩存储的方式打包到HAP。

- true：libs库以压缩方式存储。

- false：libs库以不压缩方式存储。

布尔值该标签可缺省，缺省值为false。
libIsolation

用于区分同应用不同HAP下的.so文件，以防止.so冲突。

- true：当前HAP的.so文件会储存在libs目录中以Module名命名的路径下。

- false：当前HAP的.so文件会直接储存在libs目录中。

布尔值该标签可缺省，缺省值为false。
fileContextMenu标识当前HAP的右键菜单配置项。取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
querySchemes标识允许当前应用进行跳转查询的URL schemes，只允许entry类型模块配置，最多50个，每个字符串取值不超过128字节。字符串数组该标签可缺省，缺省值为空。
routerMap标识当前模块配置的路由表路径。取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
appEnvironments标识当前模块配置的应用环境变量，只允许entry和feature模块配置。对象数组该标签可缺省，缺省值为空。
appStartup标识当前Module启动框架配置路径，仅在Entry中生效。字符串该标签可缺省，缺省值为空。
hnpPackages标识当前应用包含的Native软件包信息。只允许entry类型模块配置。对象数组该标签可缺省，缺省值为空。
5.2.2.1 deviceTypes标签

表2 deviceTypes标签说明

设备类型枚举值说明
手机phone-
平板tablet-
2in1设备2in1融合了屏幕触控和键鼠操作的二合一设备。
智慧屏tv-
智能手表wearable系统能力较丰富的手表，具备电话功能。
车机car-

deviceTypes示例：

{
  "module": {
    "name": "myHapName",
    "type": "feature",
    "deviceTypes" : [
       "tablet"
    ]
  }
}
5.2.2.2 pages标签

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

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

在开发视图的resources/base/profile下面定义配置文件main_pages.json，其中文件名"main_pages"可自定义，需要和pages标签指定的信息对应。配置文件中列举了当前应用组件中的页面信息，包含页面的路由信息和显示窗口相关的配置。

表3 pages标签说明

属性名称含义数据类型是否可缺省
src标识当前Module中所有页面的路由信息，包括页面路径和页面名称。其中，页面路径是以当前Module的src/main/ets为基准。该标签取值为一个字符串数组，其中每个元素表示一个页面。字符串数组该标签不可缺省。
window标识用于定义与显示窗口相关的配置。对象该标签可缺省，缺省值为空。

表4 window标签说明

属性名称含义数据类型是否可缺省
designWidth标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小。数值可缺省，缺省值为720px。
autoDesignWidth标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。
{
  "src": [
    "pages/index/mainPage",
    "pages/second/payment",
    "pages/third/shopping_cart",
    "pages/four/owner"
  ],
  "window": {
    "designWidth": 720,
    "autoDesignWidth": false
  }
}

5.2.2.3 metadata标签

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

表5 metadata标签说明

属性名称含义数据类型是否可缺省
name标识数据项的名称，取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
value标识数据项的值，取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
resource标识定义用户自定义数据格式，取值为长度不超过255字节的字符串，内容为标识该数据的资源索引。字符串该标签可缺省，缺省值为空。

resource属性值使用“$profile:文件名”的方式指定文件所在位置，$profile表示资源的路径为工程中的/resources/base/profile目录下。例如$profile:shortcuts_config指定了/resources/base/profile/shortcuts_config.json文件。

{
  "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"
      }],
    }]
  }
}
5.2.2.4 abilities标签

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

表6 abilities标签说明

属性名称含义数据类型是否可缺省
name标识当前UIAbility组件的名称，确保该名称在整个应用中唯一。取值为长度不超过127字节的字符串，不支持中文。字符串该标签不可缺省。
srcEntry标识入口UIAbility的代码路径，取值为长度不超过127字节的字符串。字符串该标签不可缺省。
launchType

标识当前UIAbility组件的启动模式，支持的取值如下：

- multiton：多实例模式，每次启动创建一个新实例。

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

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

- standard：multiton的曾用名，效果与多实例模式一致。

字符串该标签可缺省，该标签缺省为“singleton”。
description标识当前UIAbility组件的描述信息，取值为长度不超过255字节的字符串。要求采用描述信息的资源索引，以支持多语言。字符串该标签可缺省，缺省值为空。
icon标识当前UIAbility组件的图标，取值为图标资源文件的索引。字符串该标签可缺省，缺省值为空。
label标识当前UIAbility组件对用户显示的名称，要求采用该名称的资源索引，以支持多语言。取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
permissions

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

一个数组元素为一个权限名称。通常采用反向域名格式（不超过255字节），取值为系统预定义的权限。

字符串数组该标签可缺省，缺省值为空。
metadata标识当前UIAbility组件的元信息。对象数组该标签可缺省，缺省值为空。
exported

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

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

- false：表示不可以被其他应用调用，包括无法被aa工具命令拉起应用。

布尔值该标签可缺省，缺省值为false。
continuable

标识当前UIAbility组件是否支持跨端迁移。

- true：表示支持迁移。

- false：表示不支持迁移。

布尔值该标签可缺省，缺省值为false。
skills

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

配置规则：

- 对于Entry类型的HAP，应用可以配置多个具有入口能力的skills标签（即配置了ohos.want.action.home和entity.system.home）。

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

对象数组该标签可缺省，缺省值为空。
backgroundModes

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

长时任务类型有如下：

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

- audioPlayback：音频播放。

- audioRecording：录音。

- location：定位、导航。

- bluetoothInteraction：蓝牙扫描、连接、传输（穿戴）。

- multiDeviceConnection：多设备互联。

- taskKeeping：计算。

字符串数组该标签可缺省，缺省值为空。
startWindowIcon标识当前UIAbility组件启动页面图标资源文件的索引，取值为长度不超过255字节的字符串。字符串该标签不可缺省。
startWindowBackground

标识当前UIAbility组件启动页面背景颜色资源文件的索引，取值为长度不超过255字节的字符串。

取值示例：$color:red。

字符串该标签不可缺省。
removeMissionAfterTerminate

标识当前UIAbility组件销毁后，是否从任务列表中移除任务。

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

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

布尔值该标签可缺省，缺省值为false。
orientation

标识当前UIAbility组件启动时的方向。支持的取值如下：

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

- landscape：横屏。

- portrait：竖屏。

- follow_recent：跟随背景窗口的旋转模式。

- landscape_inverted：反向横屏。

- portrait_inverted：反向竖屏。

- auto_rotation：随传感器旋转。

- auto_rotation_landscape：传感器横屏旋转，包括横屏和反向横屏。

- auto_rotation_portrait：传感器竖屏旋转，包括竖屏和反向竖屏。

- auto_rotation_restricted：传感器开关打开，方向可随传感器旋转。

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

- auto_rotation_portrait_restricted：传感器开关打开，方向随可传感器旋转为竖屏， 包括竖屏和反向竖屏。

- locked：传感器开关关闭，方向锁定。

- auto_rotation_unspecified：受开关控制和由系统判定的自动旋转模式。

- follow_desktop：跟随桌面的旋转模式。

字符串该标签可缺省，缺省值为unspecified。
supportWindowMode

标识当前UIAbility组件所支持的窗口模式。支持的取值如下：

- fullscreen：全屏模式。

- split：分屏模式。

- floating：悬浮窗模式。

字符串数组

该标签可缺省，缺省值为

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

maxWindowRatio标识当前UIAbility组件支持的最大的宽高比。该标签最小取值为0。数值该标签可缺省，缺省值为平台支持的最大的宽高比。
minWindowRatio标识当前UIAbility组件支持的最小的宽高比。该标签最小取值为0。数值该标签可缺省，缺省值为平台支持的最小的宽高比。
maxWindowWidth

标识当前UIAbility组件支持的最大的窗口宽度，宽度单位为vp。

最小取值为minWindowWidth，最大取值为平台支持的最大窗口宽度。窗口尺寸可以参考窗口大小限制。

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

标识当前UIAbility组件支持的最小的窗口宽度， 宽度单位为vp。

最小取值为平台支持的最小窗口宽度，最大取值为maxWindowWidth。窗口尺寸可以参考窗口大小限制。

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

标识当前UIAbility组件支持的最大的窗口高度， 高度单位为vp。

最小取值为minWindowHeight，最大取值为平台支持的最大窗口高度。 窗口尺寸可以参考窗口大小限制。

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

标识当前UIAbility组件支持的最小的窗口高度， 高度单位为vp。

最小取值为平台支持的最小窗口高度，最大取值为maxWindowHeight。窗口尺寸可以参考窗口大小限制。

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

标识当前UIAbility组件是否支持在检测到应用故障后，恢复到应用原界面。

- true：支持检测到出现故障后，恢复到原界面。

- false：不支持检测到出现故障后，恢复到原界面。

布尔值该标签可缺省，缺省值为false。
isolationProcess

标识组件能否运行在独立的进程中。

- true：表示能运行在独立的进程中。

- false：表示不能运行在独立的进程中。

布尔值该标签可缺省，缺省值为false。
excludeFromDock

标识当前UIAbility组件是否支持从dock区域隐藏图标。

- true：表示在dock区域隐藏。

- false：表示不能在dock区域隐藏。

布尔值该标签可缺省，缺省值为false。
preferMultiWindowOrientation

标识当前UIAbility组件多窗布局方向：

- default：缺省值，参数不配置默认值，建议其他应用类配置。

- portrait：多窗布局方向为竖向，建议竖向游戏类应用配置。

- landscape：多窗布局方向为横向，配置后支持横屏悬浮窗和上下分屏，建议横向游戏类应用配置。

- landscape_auto：多窗布局动态可变为横向，需要配合API enableLandScapeMultiWindow/disableLandScapeMultiWindow使用，建议视频类应用配置。

字符串该标签可缺省，缺省值为default。
continueType标识当前UIAbility组件的跨端迁移类型。字符串数组该标签可缺省，缺省值为当前组件的名称。

abilities示例：

{
  "abilities": [{
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "launchType":"singleton",
    "description": "$string:description_main_ability",
    "icon": "$media:layered_image",
    "label": "Login",
    "permissions": [],
    "metadata": [],
    "exported": true,
    "continuable": true,
    "skills": [{
      "actions": ["ohos.want.action.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": "$string:orientation",
    "supportWindowMode": ["fullscreen", "split", "floating"],
    "maxWindowRatio": 3.5,
    "minWindowRatio": 0.5,
    "maxWindowWidth": 2560,
    "minWindowWidth": 1400,
    "maxWindowHeight": 300,
    "minWindowHeight": 200,
    "excludeFromDock": false,
    "preferMultiWindowOrientation": "default",
    "isolationProcess": false,
    "continueType": [
      "continueType1",
      "continueType2"
    ],
    "continueBundleName": [
      "com.example.myapplication1",
      "com.example.myapplication2"
    ],
    "process": ":processTag"
  }]
}
5.2.2.5 skills标签

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

表7 skills标签说明

属性名称含义数据类型是否可缺省
actions

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

一个skill中不建议配置多个action，否则可能导致无法匹配预期场景。

字符串数组该标签可缺省，缺省值为空。
entities

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

一个skill中不建议配置多个entity，否则可能导致无法匹配预期场景。

字符串数组该标签可缺省，缺省值为空。
uris标识与Want中URI（Uniform Resource Identifier）相匹配的集合。数组允许的最大数量为512。对象数组该标签可缺省，缺省值为空。
permissions

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

一个数组元素为一个权限名称。通常采用反向域名格式（不超过255字节），取值为系统预定义的权限。

字符串数组该标签可缺省，缺省值为空。
domainVerify标识是否开启域名校验。布尔值该标签可缺省，缺省值为false。

表8 uris标签说明

属性名称含义数据类型是否可缺省
scheme标识URI的协议名部分，常见的有http、https、file、ftp等。字符串uris中仅配置type时可以缺省，缺省值为空，否则不可缺省。
host

标识URI的主机地址部分，该字段在scheme存在时才有意义。常见的方式：

- 域名方式，如example.com。

- IP地址方式，如10.10.10.1。

字符串该标签可缺省，缺省值为空。
port标识URI的端口部分。如http默认端口为80，https默认端口是443，ftp默认端口是21。该字段在scheme和host都存在时才有意义。字符串该标签可缺省，缺省值为空。
path | pathStartWith | pathRegex标识URI的路径部分，path、pathStartWith和pathRegex配置时三选一。path标识URI与want中的路径部分全匹配，pathStartWith标识URI与want中的路径部分允许前缀匹配，pathRegex标识URI与want中的路径部分允许正则匹配。该字段在scheme和host都存在时才有意义。字符串该标签可缺省，缺省值为空。
type标识与Want相匹配的数据类型，使用MIME（Multipurpose Internet Mail Extensions）类型规范和UniformDataType类型规范。可与scheme同时配置，也可以单独配置。字符串该标签可缺省，缺省值为空。
utd标识与Want相匹配的标准化数据类型，适用于分享等场景。字符串该标签可缺省，缺省值为空。
maxFileSupported对于指定类型的文件，标识一次能接收或打开的最大数量，适用于分享等场景，需要与utd配合使用。整数该标签可缺省，缺省值为0。
linkFeature标识URI提供的功能类型（如文件打开、分享、导航等），用于实现应用间跳转。取值为长度不超过127字节的字符串，不支持中文。详情见linkFeature标签说明。字符串该标签可缺省，缺省值为空。

skills示例：

{
  "abilities": [
    {
      "skills": [
        {
          "actions": [
            "ohos.want.action.home"
          ],
          "entities": [
            "entity.system.home"
          ],
          "uris": [
            {
              "scheme":"http",
              "host":"example.com",
              "port":"80",
              "path":"path",
              "type": "text/*",
              "linkFeature": "Login"
            }
          ],
          "permissions": [],
          "domainVerify": false
        }
      ]
    }
  ]
}
5.2.2.6 extensionAbilities标签

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

表9 extensionAbilities标签说明

属性名称含义数据类型是否可缺省
name标识当前ExtensionAbility组件的名称，确保该名称在整个应用中唯一，取值为长度不超过127字节的字符串。字符串该标签不可缺省。
srcEntry标识当前ExtensionAbility组件所对应的代码路径，取值为长度不超过127字节的字符串。字符串该标签不可缺省。
description标识当前ExtensionAbility组件的描述，取值为长度不超过255字节的字符串，可以是对描述内容的资源索引，用于支持多语言。字符串该标签可缺省，缺省值为空。
icon标识当前ExtensionAbility组件的图标，取值为资源文件的索引。如果ExtensionAbility组件被配置为MainElement，该标签必须配置。字符串该标签可缺省，缺省值为空。
label标识当前ExtensionAbility组件对用户显示的名称，取值为该名称的资源索引，以支持多语言，字符串长度不超过255字节。如果ExtensionAbility被配置当前Module的mainElement时，该标签必须配置，且要确保应用内唯一。字符串该标签可缺省，缺省值为空。
type

标识当前ExtensionAbility组件的类型，支持的取值如下：

- form：卡片的ExtensionAbility。

- workScheduler：延时任务的ExtensionAbility。

- inputMethod：输入法的ExtensionAbility。

- accessibility：辅助能力的ExtensionAbility。

- staticSubscriber：静态广播的ExtensionAbility。

- wallpaper：壁纸的ExtensionAbility。

- backup：数据备份的ExtensionAbility。

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

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

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

- print：打印框架的ExtensionAbility。

- push：推送的ExtensionAbility。

- driver：驱动框架的ExtensionAbility。

- remoteNotification：远程通知的ExtensionAbility。

- remoteLocation：远程定位的ExtensionAbility。

- voip：网络音视频通话的ExtensionAbility。

- action：自定义操作业务模板的ExtensionAbility，为开发者提供基于UIExtension的自定义操作业务模板。

- embeddedUI：嵌入式UI扩展能力，提供跨进程界面嵌入的能力。

- insightIntentUI：为开发者提供能被小艺意图调用，以窗口形态呈现内容的扩展能力。

- ads：广告业务的ExtensionAbility，与AdComponent控件组合使用，将广告页面展示到其他应用中。仅支持设备厂商使用。

- photoEditor：图片编辑业务的ExtensionAbility，为开发者提供基于UIExtension的图片编辑业务模版。

- appAccountAuthorization：应用账号授权扩展能力的ExtensionAbility，用于处理账号授权请求，比如账号登录授权。

- autoFill/password：用于账号和密码自动填充业务的ExtensionAbility，支持数据的保存、填充能力。

- hms/account：应用账号管理能力的ExtensionAbility。

- autoFill/smart：用于情景化场景自动填充业务的ExtensionAbility，支持数据的保存、填充能力。

- uiService：弹窗服务组件，在启动过程中会创建window，并支持双向通信。

- recentPhoto：最近照片推荐的ExtensionAbility。

字符串该标签不可缺省。
permissions

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

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

字符串数组该标签可缺省，缺省值为空。
readPermission标识读取当前ExtensionAbility组件数据所需的权限，取值为长度不超过255字节的字符串。仅当ExtensionAbility组件的type为dataShare时支持配置该标签。字符串该标签可缺省，缺省值为空。
writePermission标识向当前ExtensionAbility组件写数据所需的权限，取值为长度不超过255字节的字符串。仅当ExtensionAbility组件的type为dataShare时支持配置该标签。字符串该标签可缺省，缺省值为空。
uri

标识当前ExtensionAbility组件提供的数据URI，取值为长度不超过255字节的字符数组，用反向域名的格式表示。

说明：

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

字符串该标签可缺省，缺省值为空。
skills

标识当前ExtensionAbility组件能够接收的Want的特征集。

配置规则：entry包可以配置多个具有入口能力的skills标签（配置了ohos.want.action.home和entity.system.home）的ExtensionAbility，其中第一个配置了skills标签的ExtensionAbility中的label和icon作为服务或应用的label和icon。

说明：

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

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

数组该标签可缺省，缺省值为空。
metadata

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

说明：

该标签在type为form时，不可缺省，且必须存在一个name为ohos.extension.form的对象值，其对应的resource值不能缺省，为卡片的二级资源引用。

对象数组该标签可缺省，缺省值为空。
exported

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

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

- false：表示不可以被其他应用调用，包括无法被aa工具命令拉起应用。

布尔值该标签可缺省，缺省值为false。
extensionProcessMode

标识当前ExtensionAbility组件的多进程实例模型,当前只对UIExtensionAbility以及从UIExtensionAbility扩展的ExtensionAbility生效。

- instance：表示该ExtensionAbility每个实例一个进程。

- type：表示该ExtensionAbility实例都运行在同一个进程里，与其他ExtensionAbility分离进程。

- bundle：表示该ExtensionAbility实例都运行在应用统一进程里，与其他配置了bundle模型的ExtensionAbility共进程。

字符串该标签可缺省，缺省值为空。
dataGroupIds标识当前ExtensionAbility组件的dataGroupId集合。如果当前ExtensionAbility组件所在的应用在应用市场申请的证书里groupIds也申请了某个dataGroupId，那么当前ExtensionAbility组件可以和应用共享这一个dataGroupId生成的目录，所以ExtensionAbility组件的dataGroupId需要是应用的证书中groupIds字段里配置的才能生效。 且该字段仅在当前ExtensionAbility组件存在独立的沙箱目录时生效。详见dataGroupId申请流程。字符串数组该标签可缺省，缺省值为空。

extensionAbilities示例：

{
  "extensionAbilities": [
    {
      "name": "FormName",
      "srcEntry": "./form/MyForm.ts",
      "icon": "$media:icon",
      "label" : "$string:extension_name",
      "description": "$string:form_description",
      "type": "form",
      "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
      "readPermission": "",
      "writePermission": "",
      "exported": true,
      "uri":"scheme://authority/path/query",
      "skills": [{
        "actions": [],
        "entities": [],
        "uris": [],
        "permissions": []
      }],
      "metadata": [
        {
          "name": "ohos.extension.form",
          "resource": "$profile:form_config",
        }
      ],
      "extensionProcessMode": "instance",
      "dataGroupIds": [
        "testGroupId1"
      ]
    }
  ]
}
5.2.2.7 shortcuts标签

shortcuts标识应用的快捷方式信息。标签值为数组，包含四个子标签shortcutId、label、icon、wants。

metadata中指定shortcut信息，其中：

  • name：指定shortcuts的名称，使用ohos.ability.shortcuts作为shortcuts信息的标识。

  • resource：指定shortcuts信息的资源位置。

表11 shortcuts标签说明

属性名称含义类型是否可缺省
shortcutId标识快捷方式的ID，取值为长度不超过63字节的字符串。不推荐通过资源索引的方式（$string）配置该字段字符串该标签不可缺省。
label标识快捷方式的标签信息，即快捷方式对外显示的文字描述信息。取值为长度不超过255字节的字符串，可以是描述性内容，也可以是标识label的资源索引。字符串该标签可缺省，缺省值为空。
icon标识快捷方式的图标，取值为资源文件的索引。字符串该标签可缺省，缺省值为空。
wants标识快捷方式内定义的目标wants信息集合，在调用launcherBundleManager的startShortcut接口时，会拉起wants标签里的第一个目标组件，推荐只配置一个wants元素。对象该标签可缺省，缺省为空。

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

{
  "shortcuts": [
    {
      "shortcutId": "id_test1",
      "label": "$string:shortcut",
      "icon": "$media:aa_icon",
      "wants": [
        {
          "bundleName": "com.ohos.hello",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": {
            "testKey": "testValue"
          }
        }
      ]
    }
  ]
}

2. 在module.json5配置文件的abilities标签中，针对需要添加快捷方式的UIAbility进行配置metadata标签，使shortcut配置文件对该UIAbility生效。

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        // ...
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ],
        "metadata": [
          {
            "name": "ohos.ability.shortcuts",
            "resource": "$profile:shortcuts_config"
          }
        ]
      }
    ]
  }
}
5.2.2.8 wants标签

此标签用于标识快捷方式内定义的目标wants信息集合。

表11-1 wants标签说明

属性名称含义类型是否可缺省
bundleName表示快捷方式的目标包名。字符串该标签不可缺省。
moduleName表示快捷方式的目标模块名。字符串该标签可缺省。
abilityName表示快捷方式的目标组件名。字符串该标签不可缺省。
parameters表示拉起快捷方式时的自定义数据，仅支持配置字符串类型的数据。其中键值均最大支持1024长度的字符串。对象该标签可缺省。

data标签示例：

{
  "wants": [
    {
      "bundleName": "com.ohos.hello",
      "moduleName": "entry",
      "abilityName": "EntryAbility",
      "parameters": {
        "testKey": "testValue"
      }
    }
  ]
}
5.2.2.9 distributionFilter标签

该标签用于定义HAP对应的细分设备规格的分发策略，以便在应用市场进行云端分发应用包时做精准匹配。

说明

该标签从API10及以后版本开始生效，API9及以前版本使用distroFilter标签。

  • 适用场景： 当一个工程中存在多个Entry，且多个Entry配置的deviceTypes存在交集时，则需要通过该标签进行区分。比如下面的两个Entry都支持tablet类型，就需要通过该标签进行区分。

// entry1支持的设备类型
{
  "module": {
    "name": "entry1",
    "type": "entry",
    "deviceTypes" : [
      "tv",
      "tablet"
    ]
  }
}
// entry2支持的设备类型
{
  "module": {
    "name": "entry2",
    "type": "entry",
    "deviceTypes" : [
      "car",
      "tablet"
    ]
  }
}

在分发应用包时，通过deviceTypes与这四个属性的匹配关系，唯一确定一个用于分发到设备的HAP。

  • 如果需要配置该标签，则至少包含一个属性。
  • 如果一个Entry中配置了任意一个或多个属性，则其他Entry也必须包含相同的属性。
  • screenShape和screenWindow属性仅用于轻量级智能穿戴设备。

  • 配置方式： 该标签需要配置在/resources/base/profile资源目录下，并在metadata的resource字段中引用。

表12 distributionFilter标签配置说明

属性名称含义数据类型是否可缺省
screenShape标识屏幕形状的支持策略。对象数组该标签可缺省，缺省值为空。
screenWindow标识应用运行时的窗口分辨率的支持策略。对象数组该标签可缺省，缺省值为空。
screenDensity标识屏幕的像素密度（dpi：Dot Per Inch）的支持策略。对象数组该标签可缺省，缺省值为空。
countryCode标识国家与地区的支持策略，取值参考ISO-3166-1标准。支持多个国家和地区枚举定义。对象数组该标签可缺省，缺省值为空。
5.2.2.10 screenShape标签

表13 screenShape标签说明

属性名称含义数据类型是否可缺省
policy

标识条件属性的过滤规则。

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

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

字符串该标签不可缺省。
value支持的取值为circle（圆形）、rect（矩形）。例如，针对智能穿戴设备，可为圆形表盘和矩形表盘分别提供不同的HAP。字符串数组该标签不可缺省。
5.2.2.11 screenWindow标签

表14 screenWindow标签说明

属性名称含义数据类型是否可缺省
policy

标识条件属性的过滤规则。当前取值仅支持“include”。

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

字符串该标签不可缺省。
value单个字符串的取值格式为“宽 * 高”，取值为整数像素值，例如“454 * 454”。字符串数组该标签不可缺省。
5.2.2.12 screenDensity标签

表15 screenDensity标签说明

属性名称含义数据类型是否可缺省
policy

标识条件属性的过滤规则。

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

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

字符串该标签不可缺省。
value

标识屏幕的像素密度（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]的设备。

字符串数组该标签不可缺省。
5.2.2.13 countryCode标签

表16 countryCode标签说明

属性名称含义数据类型是否可缺省
policy

标识条件属性的过滤规则。

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

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

字符串该标签不可缺省。
value标识应用需要分发的国家地区码。字符串数组该标签不可缺省。

示例如下：

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

{
  "distributionFilter": {
    "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"
      ]
    }
  }
}

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

{
  "module": {
    // ...
    "metadata": [
      {
        "name": "ohos.module.distribution",
        "resource": "$profile:distributionFilter_config",
      }
    ]
  }
}
5.2.2.14 testRunner标签

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

表17 testRunner标签说明

属性名称含义数据类型是否可缺省
name标识测试框架对象名称，取值为长度不超过255字节的字符串。字符串不可缺省。
srcPath标识测试框架代码路径，取值为长度不超过255字节的字符串。字符串不可缺省。

testRunner标签示例：

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

此标签用于支持对元服务的配置。此标签仅在app.json中bundleType指定为atomicService时使能。

表18 atomicService标签说明

属性名称含义数据类型是否可缺省
preloads标识元服务中预加载列表。对象数组该标签可缺省，缺省值为空。

表19 preloads标签说明

属性名称含义数据类型是否可缺省
moduleName标识元服务中当前模块被加载时，需预加载的模块名。不能配置自身modulename，且必须有对应的模块，取值为长度不超过31字节的字符串。字符串该标签不可缺省。

atomicService标签示例：

{
  "module": {
    "atomicService": {
      "preloads":[
        {
          "moduleName":"feature"
        }
      ]
    }
  }
}

5.2.2.16 dependencies标签

此标签标识模块运行时依赖的共享库列表。

表20 dependencies标签说明

属性名称含义数据类型是否可缺省
bundleName标识当前模块依赖的共享包包名。取值为长度7~128字节的字符串。字符串该标签可缺省，缺省值为空。
moduleName标识当前模块依赖的共享包模块名。取值为长度不超过31字节的字符串。字符串该标签不可缺省。
versionCode标识当前共享包的版本号。取值范围为0~2147483647。数值该标签可缺省，缺省值为空。

dependencies标签示例：

{
  "module": {
    "dependencies": [
      {
        "bundleName":"com.share.library",
        "moduleName": "library",
        "versionCode": 10001
      }
    ]
  }
}
5.2.2.17 proxyData标签

此标签标识模块提供的数据代理列表，仅限entry和feature配置。

表21 proxyData标签说明

属性名称含义数据类型是否可缺省
uri标识用于访问该数据代理的URI，不同的数据代理配置的URI不可重复，且需要满足datashareproxy://当前应用包名/xxx的格式。取值为长度不超过255字节的字符串。字符串该标签不可缺省。
requiredReadPermission标识从该数据代理中读取数据所需要的权限，若不配置，则其他应用无法使用该代理。非系统应用配置的权限的等级需为system_basic或system_core，系统应用配置的权限的等级没有限制。权限等级可以参考权限列表。取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
requiredWritePermission标识向该数据代理中写入数据所需要的权限，若不配置，则其他应用无法使用该代理。非系统应用配置的权限的等级需为system_basic或system_core，系统应用配置的权限的等级没有限制。权限等级可以参考权限列表。取值为长度不超过255字节的字符串。字符串该标签可缺省，缺省值为空。
metadata标识该数据代理的元信息，只支持配置name和resource字段。对象该标签可缺省，缺省值为空。

proxyData标签示例：

{
  "module": {
    "proxyData": [
      {
        "uri":"datashareproxy://com.ohos.datashare/event/Meeting",
        "requiredReadPermission": "ohos.permission.GET_BUNDLE_INFO",
        "requiredWritePermission": "ohos.permission.GET_BUNDLE_INFO",
        "metadata": {
          "name": "datashare_metadata",
          "resource": "$profile:datashare"
        }
      }
    ]
  }
}
5.2.2.18 routerMap标签

此标签标识模块配置的路由表的路径。

routerMap配置文件描述模块的路由表信息，routerMap标签值为数组类型。

表22 routerMap标签说明

属性名称含义数据类型是否可缺省
name标识跳转页面的名称。取值为长度不超过1023字节的字符串。字符串该标签不可缺省。
pageSourceFile标识页面在模块内的路径。取值为长度不超过255字节的字符串。字符串该标签不可缺省。
buildFunction标识被@Builder修饰的函数，该函数描述页面的UI。取值为长度不超过1023字节的字符串。字符串该标签不可缺省。
data标识字符串类型的自定义数据。 每个自定义数据字符串取值不超过128字节。对象该标签可缺省，缺省值为空。
customData标识任意类型的自定义数据，总长度不超过4096字节。对象该标签可缺省，缺省值为空。

示例如下：

1. 在开发视图的resources/base/profile下面定义配置文件，文件名可以自定义，例如：router_map.json。

{
  "routerMap": [
    {
      "name": "DynamicPage1",
      "pageSourceFile": "src/main/ets/pages/pageOne.ets",
      "buildFunction": "myFunction",
      "customData": {
        "stringKey": "data1",
        "numberKey": 123,
        "booleanKey": true,
        "objectKey": {
          "name": "test"
        },
        "arrayKey": [
          {
            "id": 123
          }
        ]
      }
    },
    {
      "name": "DynamicPage2",
      "pageSourceFile": "src/main/ets/pages/pageTwo.ets",
      "buildFunction": "myBuilder",
      "data": {
        "key1": "data1",
        "key2": "data2"
      }
    }
  ]
}

2.  在module.json5配置文件的module标签中定义routerMap字段，指向定义的路由表配置文件，例如："routerMap": "$profile:router_map"。

5.2.2.19 data标签

此标签用于支持在路由表中配置自定义的字符串数据。

data标签示例：

{
  "routerMap": [
    {
      "name": "DynamicPage",
      "pageSourceFile": "src/main/ets/pages/pageOne.ets",
      "buildFunction": "myBuilder",
      "data": {
        "key1": "data1",
        "key2": "data2"
      }
    }
  ]
}
5.2.2.20 customData标签

此标签用于支持在路由表中配置自定义数据。

customData对象内部，可以填入任意类型的自定义数据。

customData标签示例：

{
  "routerMap": [
    {
      "name": "DynamicPage",
      "pageSourceFile": "src/main/ets/pages/pageOne.ets",
      "buildFunction": "myBuilder",
      "customData": {
        "stringKey": "data1",
        "numberKey": 123,
        "booleanKey": true,
        "objectKey": {
          "name": "test"
        },
        "arrayKey": [
          {
            "id": 123
          }
        ]
      }
    }
  ]
}
5.2.2.21 appEnvironments标签

此标签标识模块配置的应用环境变量。

表23 appEnvironments标签说明

属性名称含义数据类型是否可缺省
name标识环境变量的变量名称。取值为长度不超过4096字节的字符串。字符串该标签可缺省，缺省值为空。
value标识环境变量的值。取值为长度不超过4096字节的字符串。字符串该标签可缺省，缺省值为空。

appEnvironments标签示例：

{
  "module": {
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ]
  }
}
5.2.2.22 definePermissions标签

该标签仅支持系统资源hap定义权限，不支持应用自定义权限。权限定义方式参见系统资源权限定义。

表24 definePermissions标签说明

属性名称含义数据类型是否可缺省
name标识权限的名称，该标签最大长度为255字节。字符串不可缺省。
grantMode

标识权限的授予方式，支持如下两种授予模式如下：

- system_grant：安装后系统自动授予该权限。

- user_grant：使用时动态申请，用户授权后才可使用。

字符串可缺省，缺省值为system_grant。
availableLevel

标识权限限制类别，可选值如下：

- system_core：系统核心权限。

- system_basic：系统基础权限。

- normal：普通权限。所有应用允许申请的权限。

字符串可缺省，缺省值为normal。
provisionEnable标识权限是否支持证书方式申请权限，包括高级别的权限。配置为true标识开发者可以通过provision方式申请权限。布尔值可缺省，缺省值为true。
distributedSceneEnabled标识权限是否支持分布式场景下使用该权限。布尔值可缺省，缺省值为false。
label标识权限的简短描述，配置为对描述内容的资源索引。字符串可缺省，缺省值为空。
description标识权限的详细描述，可以是字符串，或者是对描述内容的资源索引。字符串可缺省，缺省值为空。

definePermissions标签示例：

{
  "module" : {
    "definePermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "grantMode": "system_grant",
        "availableLevel": "system_core",
        "provisionEnable": true,
        "distributedSceneEnable": false,
        "label": "$string:EntryAbility_label"
      }
    ]
  }
}
5.2.2.23 hnpPackages标签

该标签标识应用包含的Native软件包信息。

表25 hnpPackages标签说明

属性名称含义数据类型是否可缺省
package标识Native软件包名称。字符串该标签不可缺省。
type

标识Native软件包类型。支持的取值如下：

- public：公有类型。

- private：私有类型。

字符串该标签不可缺省。

hnpPackages示例：

{
  "module" : {
    "hnpPackages": [
      {
        "package": "hnpsample.hnp",
        "type": "public"
      }
    ]
  }
}
5.2.2.24 fileContextMenu标签

该标签用来标识当前HAP的右键菜单配置项，是一个profile文件资源，用于指定描述应用注册右键菜单配置文件。

fileContextMenu标签示例

{
  "module": {
    // ...
    "fileContextMenu": "$profile:menu" // 通过profile下的资源文件配置
  }
}

在开发视图的resources/base/profile下面定义配置文件menu.json，其中文件名“menu.json”可自定义，需要和fileContextMenu标签指定的信息对应。配置文件中描述了当前应用注册的右键菜单的项目和响应行为。

配置文件根节点名称为fileContextMenu，为对象数组，标识当前module注册右键菜单的数量。（单模块和单应用注册数量不能超过5个，配置超过数量当前只解析随机5个）

表26 fileContextMenu标签配置说明

属性名称含义数据类型是否可缺省
abilityName表示当前右键菜单对应的需要拉起的ability名称。字符串不可缺省
menuItem右键菜单显示的信息。资源id不可缺省
menuHandler一个ability可以创建多个右键菜单， 用该字段来区分用户拉起的不同右键菜单项。该字段在用户点击右键菜单执行时，会作为参数传递给右键菜单应用。字符串不可缺省
menuContext定义展示该菜单项需要的上下文，可以支持多种情况，类型为数组。对象数组不可缺省

表27 menuContext标签配置说明

属性名称含义数据类型是否可缺省
menuKind

表示单击如下类型时会触发右键菜单。取值范围如下：

- 0：空白处

- 1：文件

- 2：文件夹

- 3：文件和文件夹

数值不可缺省
menuRule

表示采用什么方式选择文件或文件夹时，会触发右键菜单。取值范围如下：

- single：单选

- multi：多选

- both：单选或多选

字符串仅当menuKind为1或2时，才会读取该字段，此时不可缺省。
fileSupportType

表示当选中的文件列表里包含指定的文件类型时，显示右键菜单。

当该字段取值为["*"]时，将会读取fileNotSupportType字段。

当该字段取值为[]时，将不做任何处理。

字符串数组仅当menuKind为1时，才会读取该字段，此时不可缺省。
fileNotSupportType

表示当选中的文件列表里包含这些文件类型时，不显示该右键菜单。

仅当menuKind为1、且fileSupportType为["*"]时，才会读取该字段。

字符串数组可缺省，缺省值为空。

resources/base/profile路径下的menu.json资源文件示例如下：

{
  "fileContextMenu": [
    {
      "abilityName": "EntryAbility",
      "menuItem": "$string:module_desc",
      "menuHandler": "openCompress",
      "menuContext": [
        {
          "menuKind": 0
        },
        {
          "menuKind": 1,
          "menuRule": "both",
          "fileSupportType": [
            ".rar",
            ".zip"
          ],
          "fileNotSupportType": [
            ""
          ]
        },
        {
          "menuKind": 2,
          "menuRule": "single"
        },
        {
          "menuKind": 3
        }
      ]
    }
  ]
}
5.2.2.25 响应行为

应用进行右键扩展菜单注册后，在文件管理器通过右键操作拉起菜单，该菜单中会有“更多”选项。点击“更多”选项后，会出现注册后的menuItem列表，点击任意一个选项后，文件管理器默认通过startAbility的方式拉起三方应用，除了指定三方应用的包名和ability名之外，want中的parameter中，也会传入如下字段：

表28 want中parameter字段说明

参数名值类型
menuHandler对应注册配置文件中menuHandler的值。字符串
uriList用户在具体文件上触发右键的uri值，如果空白处响应，此值为空，单个文件响应，数组长度1，多个文件响应则传入对应所有文件的uri值。字符串数组
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值