OpenHarmony开发者论坛

标题: OpenHarmony应用开发模型详解 [打印本页]

---

作者: Laval社区小助手    时间: 2024-3-6 14:27
标题: OpenHarmony应用开发模型详解
[md]## 开发环境

**IDE： DevEco Studio 3.0 Release（Build Version: 3.0.0.993）**

**SDK：Api Version8和9**

## Ability模型

**Ability分为FA和Stage两种模型，在API 8及其更早版本的应用程序只能使用FA模型进行开发，而从API 9开始，Ability框架引入了Stage模型作为第二种应用框架形态。FA与Stage这两种模型在工程目录结构，配置文件以及在应用上下文context能力的运用上有较大区别。**

## 工程结构

### FA模型目录结构

```
└── entry
    └── src
        └── main
            ├── ets
            |   └── MainAbility      //应用/服务的入口
            |       ├── pages        //MainAbility包含的页面
            |       |   └── index.ets     //pages列表中的第一个页面，即应用的首页入口
            |       └── app.ets       //承载Ability生命周期
            ├── resources         //用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等
            |   └── base          
            |       ├── element     //包括字符串、整型数、颜色、样式等资源的json文件，每个资源均由json格式进行定义
            |       |   └── string.json
            |       └── media      //多媒体文件，如图形、视频、音频等文件，支持的文件格式包括：.png、.gif、.mp3、.mp4等
            |           └── icon.png
            └── config.json
```

### Stage模型目录结构

```
├── AppScope
|   ├── resources
|   |   └── base
|   |       ├── element    //包括字符串、整型数、颜色、样式等资源的json文件，每个资源均由json格式进行定义
|   |       |   └── string.json  
|   |       └── media      //多媒体文件，如图形、视频、音频等文件，支持的文件格式包括：.png、.gif、.mp3、.mp4等
|   |           └── app_icon.png    
|   └── app.json5     //应用的全局配置，同一应用的不同.hap文件必须使用相同的应用配置
└── entry      //OpenHarmony工程模块，编译构建生成一个Hap包
    └── src
        └── main
            ├── ets     //用于存放ets源码
            |   ├── Application      //模块的入口
            |   |   └── AbilityStage.ts    
            |   ├── MainAbility      //模块对应ability的入口
            |   |   └── MainAbility.ts    
            |   └── pages       //模块包含的页面
            |       └── index.ets   
            ├── resources     
            |   └── base
            |       ├── element
            |       |   └── string.json
            |       ├── media
            |       |   └── icon.png
            |       └── profile
            |           └── main_pages.json   
            └── module.json5
```

## 配置文件

### FA模型(config.json)

**config.json 由 app、deviceConfig和module 三个部分组成，缺一不可。配置文件的内部结构说明如下表。**

**表配置文件的内部结构说明**

| **属性名称**     | **含义**                                                                 | **数据类型** | **是否可缺省** |
| ---------------------- | ------------------------------------------------------------------------------ | ------------------ | -------------------- |
| **app**          | **表示应用的全局配置信息。同一个应用的不同HAP包的app配置必须保持一致。** | **对象**     | **不可缺省**   |
| **deviceConfig** | **表示应用在具体设备上的配置信息。**                                     | **对象**     | **不可缺省**   |
| **module**       | **表示HAP包的配置信息。该标签下的配置只对当前HAP包生效。**               | **对象**     | **不可缺省**   |

**module对象的内部结构中abilities对象的内部结构说明**

| **属性名称**                    | **含义**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | **数据类型**   | **是否可缺省**                                               |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------ |
| **process**                     | **运行应用程序或Ability的进程名称。如果在deviceConfig标记中配置了进程，则应用程序的所有能力都在此进程中运行。您还可以为特定能力设置流程属性，以便该能力可以在此流程中运行。如果此属性设置为与其他应用程序相同的进程名称，则所有这些应用程序可以在同一进程中运行，前提是他们具有相同的联合用户ID和相同的签名。运行OHOS的设备不支持此属性。**                                                                                                                                                                                                                                                                                                                                                                                                                                                    | **字符串**     | **可缺省，缺省值为空。**                                     |
| **name**                        | **表示Ability名称。取值可采用反向域名方式表示，由包名和类名组成，如“com.example.myapplication.MainAbility”；也可采用“.”开头的类名方式表示，如“.MainAbility”。 Ability的名称，需在一个应用的范围内保证唯一。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。 说明：在使用DevEco Studio新建项目时，默认生成首个Ability的配置，即“config.json”中“MainAbility”的配置。如使用其他IDE工具，可自定义名称。该标签最大长度为127。**                                                                                                                                                                                                                                                                                                                                                     | **字符串**     | **不可缺省**                                                 |
| **description**                 | **表示对Ability的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。该标签最大长度为255。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | **字符串**     | **可缺省，缺省值为空。**                                     |
| **icon**                        | **表示Ability图标资源文件的索引。取值示例：\$media:ability\_icon。如果在该Ability的skills属性中，actions的取值包含 “action.system.home”，entities取值中包含“entity.system.home”，则该Ability的icon将同时作为应用的icon。如果存在多个符合条件的Ability，则取位置靠前的Ability的icon作为应用的icon。 说明：应用的“icon”和“label”是用户可感知配置项，需要区别于当前所有已有的应用“icon”或“label”（至少有一个不同）。**                                                                                                                                                                                                                                                                                                                                                                | **字符串**     | **可缺省，缺省值为空。**                                     |
| **label**                       | **表示Ability对用户显示的名称。取值可以是Ability名称，也可以是对该名称的资源索引，以支持多语言。如果在该Ability的skills属性中，actions的取值包含 “action.system.home”，entities取值中包含“entity.system.home”，则该Ability的label将同时作为应用的label。如果存在多个符合条件的Ability，则取位置靠前的Ability的label作为应用的label。 说明： 应用的“icon”和“label”是用户可感知配置项，需要区别于当前所有已有的应用“icon”或“label”（至少有一个不同）。该标签为资源文件中定义的字符串的引用，或以"{}"包括的字符串。该标签最大长度为255。**                                                                                                                                                                                                                                            | **字符串**     | **可缺省，缺省值为空。**                                     |
| **uri**                         | **表示Ability的统一资源标识符。该标签最大长度为255。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **字符串**     | **可缺省，对于data类型的Ability不可缺省。**                  |
| **launchType**                  | **表示Ability的启动模式，支持“standard”和“singleton”两种模式： standard：表示该Ability可以有多实例。该模式适用于大多数应用场景。 singleton：表示该Ability在所有任务栈中仅可以有一个实例。例如，具有全局唯一性的呼叫来电界面即采用“singleton”模式。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | **字符串**     | **可缺省，缺省值为“singleton”。**                          |
| **visible**                     | **表示Ability是否可以被其他应用调用。 true：可以被其他应用调用。 false：不能被其他应用调用。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | **布尔类型**   | **可缺省，缺省值为“false”。**                              |
| **permissions**                 | **表示其他应用的Ability调用此Ability时需要申请的权限集合，一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），取值为系统预定义的权限。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **字符串数组** | **可缺省，缺省值为空。**                                     |
| **skills**                      | **表示Ability能够接收的want的特征。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **对象数组**   | **可缺省，缺省值为空。**                                     |
| **deviceCapability**            | **表示Ability运行时要求设备具有的能力，采用字符串数组的格式表示。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **字符串数组** | **可缺省，缺省值为空。**                                     |
| **metaData**                    | **元数据，参考表1。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **对象**       | **可缺省，缺省值为空。**                                     |
| **type**                        | **表示Ability的类型。取值范围如下： page：表示基于Page模板开发的FA，用于提供与用户交互的能力。 service：表示基于Service模板开发的PA，用于提供后台运行任务的能力。 data：表示基于Data模板开发的PA，用于对外部提供统一的数据访问抽象。 CA：表示支持其他应用以窗口方式调起该Ability。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **字符串**     | **不可缺省**                                                 |
| **orientation**                 | **表示该Ability的显示模式。该标签仅适用于page类型的Ability。取值范围如下： unspecified：由系统自动判断显示方向。 landscape：横屏模式。 portrait：竖屏模式。 followRecent：跟随栈中最近的应用。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | **字符串**     | **可缺省，缺省值为“unspecified”。**                        |
| **backgroundModes**             | **表示后台服务的类型，可以为一个服务配置多个后台服务类型。该标签仅适用于service类型的Ability。取值范围如下： dataTransfer：通过网络/对端设备进行数据下载、备份、分享、传输等业务。 audioPlayback：音频输出业务。 audioRecording：音频输入业务。 pictureInPicture：画中画、小窗口播放视频业务。 voip：音视频电话、VOIP业务。 location：定位、导航业务。 bluetoothInteraction：蓝牙扫描、连接、传输业务。 wifiInteraction：WLAN扫描、连接、传输业务。 screenFetch：录屏、截屏业务。 multiDeviceConnection：多设备互联业务**                                                                                                                                                                                                                                                                      | **字符串数组** | **可缺省，缺省值为空。**                                     |
| **grantPermission**             | **指定是否可以向Ability内任何数据授予权限。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | **布尔值**     | **可缺省，缺省值为空。**                                     |
| **readPermission**              | **表示读取Ability的数据所需的权限。该标签仅适用于data类型的Ability。取值为长度不超过255字节的字符串。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | **字符串**     | **可缺省，缺省为空。**                                       |
| **writePermission**             | **表示向Ability写数据所需的权限。该标签仅适用于data类型的Ability。取值为长度不超过255字节的字符串。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | **字符串**     | **可缺省，缺省为空。**                                       |
| **configChanges**               | **表示Ability关注的系统配置集合。当已关注的配置发生变更后，Ability会收到onConfigurationUpdated回调。取值范围： mcc：表示IMSI移动设备国家/地区代码（MCC）发生变更。典型场景：检测到SIM并更新MCC。 mnc：IMSI移动设备网络代码（MNC）发生变更。典型场景：检测到SIM并更新MNC。 locale：表示语言区域发生变更。典型场景：用户已为设备文本的文本显示选择新的语言类型。 layout：表示屏幕布局发生变更。典型场景：当前有不同的显示形态都处于活跃状态。 fontSize：表示字号发生变更。典型场景：用户已设置新的全局字号。 orientation：表示屏幕方向发生变更。典型场景：用户旋转设备。 density：表示显示密度发生变更。典型场景：用户可能指定不同的显示比例，或当前有不同的显示形态同时处于活跃状态。 size：显示窗口大小发生变更。 smallestSize：显示窗口较短边的边长发生变更。 colorMode：颜色模式发生变更。** | **字符串数组** | **可缺省，缺省为空。**                                       |
| **mission**                     | **表示Ability指定的任务栈。该标签仅适用于page类型的Ability。默认情况下应用中所有Ability同属一个任务栈。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | **字符串**     | **可缺省，缺省为应用的包名。**                               |
| **targetAbility**               | **表示当前Ability重用的目标Ability。该标签仅适用于page类型的Ability。如果配置了targetAbility属性，则当前Ability（即别名Ability）的属性中仅name、icon、label、visible、permissions、skills生效，其它属性均沿用targetAbility中的属性值。目标Ability必须与别名Ability在同一应用中，且在配置文件中目标Ability必须在别名之前进行声明。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                      | **字符串**     | **可缺省，缺省值为空。表示当前Ability不是一个别名Ability。** |
| **multiUserShared**             | **表示Ability是否支持多用户状态进行共享，该标签仅适用于data类型的Ability。配置为“true”时，表示在多用户下只有一份存储数据。需要注意的是，该属性会使visible属性失效。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | **布尔值**     | **可缺省，缺省值为“false”。**                              |
| **supportPipMode**              | **表示Ability是否支持用户进入PIP模式（用于在页面最上层悬浮小窗口，俗称“画中画”，常见于视频播放等场景）。该标签仅适用于page类型的Ability。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **布尔值**     | **可缺省，缺省值为“false”。**                              |
| **formsEnabled**                | **表示Ability是否支持卡片（forms）功能。该标签仅适用于page类型的Ability。 true：支持卡片能力。 false：不支持卡片能力。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | **布尔值**     | **可缺省，缺省值为“false”。**                              |
| **forms**                       | **表示服务卡片的属性。该标签仅当formsEnabled为“true”时，才能生效。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **对象数组**   | **可缺省，缺省值为空。**                                     |
| **srcLanguage**                 | **Ability开发语言的类型。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | **字符串**     | **可缺省，取值为js或ets**                                    |
| **srcPath**                     | **该标签表示Ability对应的JS组件代码路径**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | **字符串**     | **可缺省，缺省值为空。**                                     |
| **uriPermission**               | **表示该Ability有权访问的应用程序数据。此属性由模式和路径子属性组成。此属性仅对类型提供者的能力有效。运行OHOS的设备不支持此属性。参考表2。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | **对象**       | **可缺省，缺省值为空。**                                     |
| **startWindowIcon**             | **表示该Ability启动页面图标资源文件的索引。该标签仅适用于page类型的ability。取值示例：\$media:icon。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **字符串**     | **可缺省，缺省值为空。**                                     |
| **startWindowBackground**       | **表示该Ability启动页面背景颜色资源文件的索引。该标签仅适用于page类型的ability。取值示例：\$color:red。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | **字符串**     | **可缺省，缺省值为空。**                                     |
| **removeMissionAfterTerminate** | **该标签标识ability销毁后是否从任务列表中移除任务。该标签仅适用于page类型的ability。true表示销毁后移除任务， false表示销毁后不移除任务。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | **布尔值**     | **可缺省，缺省值为false。**                                  |

**表1 metaData对象的内部结构说明**

| **属性名称**      | **含义**                                                                                                   | **数据类型** | **是否可缺省**           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------ |
| **parameters**    | **表示调用Ability时所有调用参数的元信息。每个调用参数的元信息由以下三个标签组成：description、name、type** | **对象数组** | **可缺省，缺省值为空**   |
| **results**       | **表示Ability返回值的元信息。每个返回值的元信息由以下三个标签组成：description、name、type**               | **对象数组** | **可缺省，缺省值为空。** |
| **customizeData** | **该标签标识父级组件的自定义元信息，Parameters和results在application不可配**                               | **对象数组** | **可缺省，缺省值为空。** |

**表2 uriPermission对象的内部结构说明**

| **属性名称** | **含义**                    | **数据类型** | **是否可缺省**                |
| ------------------ | --------------------------------- | ------------------ | ----------------------------------- |
| **path**     | **uriPermission标识的路径** | **字符串**   | **不可缺省**                  |
| **mode**     | **uriPeimission的匹配模式** | **字符串**   | **可缺省，缺省值为default。** |

**abilities示例：**

```
"abilities": [
   {
       "name": ".MainAbility",
       "description": "test main ability",
       "icon": "$media:ic_launcher",
       "label": "$media:example",
       "launchType": "standard",
       "orientation": "unspecified",
       "permissions": [],
       "visible": true,
       "skills": [
           {
               "actions": [
                   "action.system.home"
               ],
               "entities": [
                   "entity.system.home"
               ]
           }
       ],
       "configChanges": [
           "locale",
           "layout",
           "fontSize",
           "orientation"
       ],
       "type": "page",
       "startWindowIcon": "$media:icon",
       "startWindowBackground": "$color:red",
       "removeMissionAfterTerminate": true
   },
   {
       "name": ".PlayService",
       "description": "example play ability",
       "icon": "$media:ic_launcher",
       "label": "$media:example",
       "launchType": "standard",
       "orientation": "unspecified",
       "visible": false,
       "skills": [
           {
               "actions": [
                   "action.play.music",
                   "action.stop.music"
               ],
               "entities": [
                   "entity.audio"
               ]
           }
       ],
       "type": "service",
       "backgroundModes": [
           "audioPlayback"
       ]
   },
   {
       "name": ".UserADataAbility",
       "type": "data",
       "uri": "dataability://com.example.world.test.UserADataAbility",
       "visible": true
   }
]
```

### Stage模型(module.json5)

**配置文件由app和module这两个部分组成，缺一不可。配置文件的内部结构说明如下表。**

**表 配置文件的内部结构说明**

| **属性名称** | **含义**                                                               | **数据类型** | **是否可缺省** |
| ------------------ | ---------------------------------------------------------------------------- | ------------------ | -------------------- |
| **app**      | **表示应用的全局配置信息。同一个应用的不同HAP包的app配置必须保持一致** | **对象**     | **否**         |
| **module**   | **表示HAP包的配置信息。该标签下的配置只对当前HAP包生效**               | **对象**     | **否**         |

**module对象的内部结构中abilities对象的内部结构说明**

| **属性**                        | **含义**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **数据类型**   | **是否可缺省**                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------- |
| **name**                        | **该标签标识当前ability的逻辑名，该名称在整个应用要唯一，标签值采用字符串表示（最大长度127个字节）。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **字符串**     | **该标签不可缺省。**                                                            |
| **srcEntrance**                 | **该标签表示ability所对应的js代码路径，标签值为字符串（最长为127字节）。。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | **字符串**     | **该标签不可缺省。**                                                            |
| **launchType**                  | **该标签标示ability的启动模式，标签值可选“standard”、“singleton”、“specified”。该标签缺省为"singleton"。standard表示普通多实例，specified表示指定实例，运行时由ability内部业务决定是否创建多实例，singleton表示单实例。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | **字符串**     | **可缺省，该标签缺省为"singleton"**                                             |
| **description**                 | **该标签标识ability的描述，标签值是是字符串类型或对描述内容的资源索引，要求采用用资源索引方式，以支持多语言。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | **字符串**     | **该标签可缺省，缺省值为空。**                                                  |
| **icon**                        | **该标签标识ability图标，标签值为资源文件的索引。该标签可缺省，缺省值为空。 如果ability被配置为MainElement，该标签必须配置。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | **字符串**     | **该标签可缺省，缺省值为空。 如果ability被配置为MainElement，该标签必须配置。** |
| **permissions**                 | **该标签标识被其它应用的ability调用时需要申请的权限的集合，一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），取值为系统预定义的权限。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **字符串数组** | **该标签可缺省，缺省值为空。**                                                  |
| **metadata**                    | **该标签表示ability的元信息**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | **数组**       | **该标签可缺省，缺省值为空。**                                                  |
| **visible**                     | **该标签标识ability是否可以被其它应用调用，为布尔类型，true表示可以被其它应用调用， false表示不可以被其它应用调用。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **布尔值**     | **该标签可缺省，缺省值为false。**                                               |
| **continuable**                 | **该标签标识ability是否可以迁移，为布尔类型，true表示可以被迁移， false表示不可以被迁移。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | **布尔值**     | **该标签可缺省，缺省值为false。**                                               |
| **skills**                      | **该标签标识ability能够接收的意图的特征集，为数组格式。 配置规则 : entry包可以配置多个具有入口能力的skills标签（配置了action.system.home和entity.system.home）的ability，其中第一个配置了skills标签的ability中的label和icon作为OpenHarmony服务或应用的label和icon。 OpenHarmony服务的Feature包不能配置具有入口能力的skills标签。 OpenHarmony应用的Feature包可以配置具有入口能力的skills标签。**                                                                                                                                                                                                                                                                                                  | **数组**       | **该标签可缺省，缺省值为空。**                                                  |
| **backgroundModes**             | **该标签标识ability长时任务集合。指定用于满足特定类型的长时任务。 长时任务类型有如下 : dataTransfer :通过网络/对端设备进行数据下载、备份、分享、传输等业务。 audioPlayback :音频输出业务。 audioRecording :音频输入业务。 location :定位、导航业务。 bluetoothInteraction :蓝牙扫描、连接、传输业务（穿戴）。 multiDeviceConnection :多设备互联业务。 wifiInteraction :Wifi扫描、连接、传输业务（克隆 多屏）。 voip :音视频电话，VOIP业务。 taskKeeping :计算业务。**                                                                                                                                                                                                                            | **字符串**     | **可缺省，缺省为空。**                                                          |
| **startWindowIcon**             | **表示该Ability启动页面图标资源文件的索引。取值示例：\$media:icon。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **字符串**     | **不可缺省。**                                                                  |
| **startWindowBackground**       | **表示该Ability启动页面背景颜色资源文件的索引。取值示例：\$color:red。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **字符串**     | **不可缺省。**                                                                  |
| **removeMissionAfterTerminate** | **该标签标识ability销毁后是否从任务列表中移除任务。为布尔类型，true表示销毁后移除任务， false表示销毁后不移除任务。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **布尔值**     | **该标签可缺省，缺省值为false。**                                               |
| **orientation**                 | **表示该ability启动时的方向。该方向的取值范围包括： 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**           | **表示该ability所支持的窗口模式，包含： fullscreen: 全屏模式， split: 分屏模式， floating: 悬浮窗模式。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | **数组**       | **该标签可缺省，缺省值为 ["fullscreen", "split", "floating"]。**                |
| **maxWindowRatio**              | **表示该ability支持的最大的宽高比。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **数值**       | **该标签可缺省，缺省值为平台支持的最大的宽高比。**                              |
| **minWindowRatio**              | **表示该ability支持的最小的宽高比。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **数值**       | **该标签可缺省，缺省值为平台支持的最小的宽高比。**                              |
| **maxWindowWidth**              | **表示该ability支持的最大的窗口宽度，宽度单位为pixl。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **数值**       | **该标签可缺省，缺省值为平台支持的最大的窗口宽度。**                            |
| **minWindowWidth**              | **表示该ability支持的最小的窗口宽度, 宽度单位为pixl。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **数值**       | **该标签可缺省，缺省值为平台支持的最小的窗口宽度。**                            |
| **maxWindowHeight**             | **表示该ability支持的最大的窗口高度, 高度单位为pixl。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **数值**       | **该标签可缺省，缺省值为平台支持的最大的窗口高度。**                            |
| **minWindowHeight**             | **表示该ability支持的最小的窗口高度, 高度单位为pixl。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **数值**       | **该标签可缺省，缺省值为平台支持的最小的窗口高度。**                            |
| **excludeFromMissions**         | **该标签标识ability是否在最近任务列表中显示，仅支持系统应用配置。为布尔类型，true表示不在任务列表中显示，false表示在任务列表中显示。**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **布尔值**     | **该标签可缺省，缺省值为false。**                                               |

**abilities示例**

```
{
   "abilities": [{
       "name": "MainAbility",
       "srcEntrance": "./ets/login/MyLoginAbility.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
   }]
}
```

## 应用上下文

**Context是应用中对象的上下文，提供获取应用程序环境信息的能力。**

**OpenHarmony的应用框架分为FA模型和Stage两种模型。对应存在两套Context机制适配两种应用框架模型，其中application/BaseContext属于通用的Context基类，里面包含一个属性stageMode，用来区分开发模型是FA还是Stage。**

**只有app/Context中的方法属于FA模型对应的Context。该模式下，应用级别的Context和Ability级别的Context都是该类型的实例，如果在应用级别的Context里面调用了Ability级别的方法，会产生错误。所以开发者需要注意Context实例所代表的实际含义。**

**除了app/Context之外的Context都属于Stage模型，分别有application/Context、application/ApplicationContext、application/AbilityStageContext、application/ExtensionContext、application/AbilityContext、application/FormExtensionContext等Context。**

### FA模型的Context

**只有app/Context中的方法属于FA模型对应的Context，FA模型只有一个Context定义。**

**Context中所有的功能都是通过方法来提供的，它提供了一些featureAbility中不存在的方法，相当于featureAbility的一个扩展和补全。**

**使用说明**

**Context对象是在featureAbility中创建实例，并通过featureAbility的getContext()接口返回，因此在使用Context时，必须导入@ohos.ability.featureAbility库。**

**示例**

```
import featureAbility from '@ohos.ability.featureAbility'
// 获取Context并调用相关方法
let context = featureAbility.getContext();
context.getOrCreateLocalDir()
```

### Stage模型的Context

**Stage模型下，每个Ability中都包含了一个Context属性，由AbilityContext实现操作Ability的方法(如startAbility、connectAbility等)。**

**AbilityContext是Ability的上下文环境，继承自Context，Context里面提供了应用的一些基础信息：resourceManager、applicationInfo、cacheDir、area等，还有应用的一些基本方法：createBundleContext等。**

**AbilityContext模块提供允许访问特定于ability的资源的能力，包括对Ability的启动、停止的设置、获取caller通信接口、拉起弹窗请求用户授权等。**

**使用说明**

**在Ability生命周期中使用AbilityContext的功能，需要通过Ability子类实例context获取。**

**示例**

```
import Ability from '@ohos.application.Ability'
class MainAbility extends Ability {
   ... ...
   onWindowStageCreate(windowStage) {
       // 通过子类实例context(后者)，获取AbilityContext并调用相关方法
       let context = this.context;
   }
    ... ...
}
```

**在UI页面或其他自定义方法页面，可通过全局getContext函数调用AbilityContext相关功能，getContext中的this参数指向当前UI组件名或方法名，作为全局getContext函数的区分。**

> **getContext函数属于Context类型，此时的Context是一个定义上下文的模拟对象。**

**示例**

```
@Entry
@Component
export struct Index {
   private context = getContext(this)
    ...
   aboutToAppear() {
       this.context.filesDir
   }
}
```

### 常见错误使用方式

**Stage模型通过globalThis去获取Context**

**案例**

**在生命周期中使用globalThis获取Abilitycontext的能力，然后在UI页面使用globalThis去调用Abilitycontext的相关方法，如下实例：**

```
//MainAbility.ts
onWindowStageCreate(windowStage) {
   // Main window is created, set main page for this ability
   console.log("[Demo] MainAbility onWindowStageCreate")
       // 通过globalThis.context调用子类context，获取AbilityContext并调用相关方法
   globalThis.context = this.context
   windowStage.setUIContent(this.context, "pages/nav", null)
}
```

```
//index.ets
@Entry
@Component
struct Index {
    aboutToAppear() {
        globalThis.context.filesDir
    }

    build() {
        ...
    }
}
```

**原因**

**在API8的FA模型下，每个Ability实例有一个js虚拟机实例，所以可以从js引擎的global对象上，获取到一个全局的Ability实例，但是在新的模型（Stage模型）下，整个应用进程共用一个js虚拟机实例，其中可以运行多个Ability实例，这样就不存在一个全局的Ability实例。**

**如果开发者在新的模型（Stage模型）下，调用的API实现仍然走到了获取全局Ability实例的方法，就可能会发生错误或者崩溃。**

### FA模型和Stage模型中context功能差异

**FA模型AbilityContext API特有接口功能介绍**

| **接口名**                                                                                                                                                                                                                                                                                                      | **描述**                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **getOrCreateLocalDir(callback:AsyncCallback**<string>**): void;**                                                                                                                                                                                                                                        | **获取应用的本地根目录。如果是第一个呼叫，则目录将被创建**                           |
| **verifyPermission(permission: string, options?: PermissionOptions): Promise**<number>**;** **verifyPermission(permission: string, options: PermissionOptions, callback:** **verifyPermission(permission: string, callback: AsyncCallback**<number>**): void;**                         | **验证是否允许对特定功能的特定权限**                                                 |
| **requestPermissionsFromUser(permissions: Array**<string>**, requestCode: number, resultCallback: AsyncCallback**<PermissionRequestResult>**): void;** **requestPermissionsFromUser(permissions: Array**<string>**, requestCode: number): Promise**<PermissionRequestResult>**;** | **向系统请求某些权限**                                                               |
| **getApplicationInfo(callback: AsyncCallback**<ApplicationInfo>**): void** **getApplicationInfo(): Promise**<ApplicationInfo>**;**                                                                                                                                                            | **获取当前应用的信息。**                                                             |
| **getBundleName(callback: AsyncCallback**<string>**): void** **getBundleName(): Promise**<string>**;**                                                                                                                                                                                        | **获取当前能力的套餐名称**                                                           |
| **getDisplayOrientation(callback: AsyncCallback**<DisplayOrientation>**): void** **getDisplayOrientation(): Promise**<DisplayOrientation>**;**                                                                                                                                                | **获取此能力的当前显示方向**                                                         |
| **setDisplayOrientation(orientation: DisplayOrientation, callback: AsyncCallback**<void>**): void setDisplayOrientation(orientation: DisplayOrientation): Promise**<void>**;**                                                                                                                      | **设置当前能力的显示方向**                                                           |
| **setShowOnLockScreen(show: boolean, callback: AsyncCallback**<void>**): void** **setShowOnLockScreen(show: boolean): Promise**<void>**;**                                                                                                                                                    | **设置每当显示锁定屏幕时，是否在锁定屏幕顶部显示此技能，并将该技能保持在激活状态。** |
| **setWakeUpScreen(wakeUp: boolean, callback: AsyncCallback**<void>**): void** **setWakeUpScreen(wakeUp: boolean): Promise**<void>**;**                                                                                                                                                        | **设置恢复此能力时是否唤醒屏幕**                                                     |
| **getProcessInfo(callback: AsyncCallback**<ProcessInfo>**): void** **getProcessInfo(): Promise**<ProcessInfo>**;**                                                                                                                                                                            | **获取当前进程的信息，包括进程ID和进程名称**                                         |
| **getElementName(callback: AsyncCallback**<ElementName>**): void** **getElementName(): Promise**<ElementName>**;**                                                                                                                                                                            | **获取当前能力的ohos.bundle.ElementName对象。此方法仅对Page功能可用**                |
| **getProcessName(callback: AsyncCallback**<string>**): void** **getProcessName(): Promise**<string>**;**                                                                                                                                                                                      | **获取当前进程的名称**                                                               |
| **getCallingBundle(callback: AsyncCallback**<string>**): void** **getCallingBundle(): Promise**<string>**;**                                                                                                                                                                                  | **获取调用当前能力的能力的捆绑包名称**                                               |
| **getFilesDir(callback: AsyncCallback**<string>**): void;** **getFilesDir(): Promise**<string>**;**                                                                                                                                                                                           | **获取该应用程序在内部存储上的文件目录**                                             |
| **getCacheDir(callback: AsyncCallback**<string>**): void;** **getCacheDir(): Promise**<string>**;**                                                                                                                                                                                           | **取此应用程序在内部存储上的缓存目录**                                               |
| **getOrCreateDistributedDir(): Promise**<string>**;** **getOrCreateDistributedDir(callback: AsyncCallback**<string>**): void;**                                                                                                                                                               | **获取能力或应用数据文件的分布式文件路径**                                           |
| **getAppType(callback: AsyncCallback**<string>**): void** **getAppType(): Promise**<string>**;**                                                                                                                                                                                              | **获取应用类型**                                                                     |
| **getHapModuleInfo(callback: AsyncCallback**<HapModuleInfo>**): void** **getHapModuleInfo(): Promise**<HapModuleInfo>**;**                                                                                                                                                                    | **获取此应用程序的ModuleInfo对象**                                                   |
| **getAppVersionInfo(callback: AsyncCallback**<AppVersionInfo>**): void** **getAppVersionInfo(): Promise**<AppVersionInfo>**;**                                                                                                                                                                | **获取应用版本信息**                                                                 |
| **getApplicationContext(): Context;**                                                                                                                                                                                                                                                                           | **获取此应用程序的上下文**                                                           |
| **getAbilityInfo(callback: AsyncCallback**<AbilityInfo>**): void** **getAbilityInfo(): Promise**<AbilityInfo>**;**                                                                                                                                                                            | **查看此能力的详细信息**                                                             |
| **isUpdatingConfigurations(callback: AsyncCallback**<boolean>**): void;** **isUpdatingConfigurations(): Promise**<boolean>**;**                                                                                                                                                               | **检查此能力的配置是否正在更改**                                                     |
| **printDrawnCompleted(callback: AsyncCallback**<void>**): void;** **printDrawnCompleted(): Promise**<void>**;**                                                                                                                                                                               | **通知系统绘制此页面功能所需的时间**                                                 |

**StageAbilityContext API特有接口功能介绍**

| **接口名**                                                                                                                                                                                                                                                                                                                                                  | **描述**                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **startAbilityByCall(want: Want): Promise**<Caller>**;**                                                                                                                                                                                                                                                                                              | **获取启动能力的调用者对象**           |
| **startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback**<void>**): void;** **startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback**<void>**): void; startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise**<void>**;** | **启动Ability**                        |
| **void startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback)**                                                                                                                                                                                                                                                                    | **使用帐户启动新能力**                 |
| **void startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback)**                                                                                                                                                                                                                                             | **带AccountId启动Ability。**           |
| **void startAbilityForResult(want: Want, callback: AsyncCallback)**                                                                                                                                                                                                                                                                                         | **带返回结果启动Ability。**            |
| **void startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback)**                                                                                                                                                                                                                                                                  | **带返回结果启动Ability。**            |
| **void startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback)**                                                                                                                                                                                                                                                           | **带返回结果及AccountId启动Ability。** |
| **void startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback)**                                                                                                                                                                                                                                    | **带返回结果及AccountId启动Ability。** |
| **void terminateSelf(callback: AsyncCallback)**                                                                                                                                                                                                                                                                                                             | **销毁当前的Page Ability。**           |
| **void terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback)**                                                                                                                                                                                                                                                                         | **带返回结果销毁当前的Page Ability。** |

## 参考文献

**[1]OpenHarmony Ability开发. **[https://gitee.com/openharmony/do ... ication-dev/ability](https://link.csdn.net/?target=ht ... 3Flogin%3Dfrom_csdn)
[/md]

---

欢迎光临 OpenHarmony开发者论坛 (https://forums.openharmony.cn/)

Powered by Discuz! X3.5