常见action与entities

action：表示调用方要执行的通用操作（如查看、分享、应用详情）。在隐式Want中，您可定义该字段，配合uri或parameters来表示对数据要执行的操作。如打开，查看该uri数据。例如，当uri为一段网址，action为ohos.want.action.viewData则表示匹配可查看该网址的Ability。在Want内声明action字段表示希望被调用方应用支持声明的操作。在被调用方应用配置文件skills字段内声明actions表示该应用支持声明操作。

常见action

• ACTION_HOME：启动应用入口组件的动作，需要和ENTITY_HOME配合使用；系统桌面应用图标就是显式的入口组件，点击也是启动入口组件；入口组件可以配置多个。
• ACTION_CHOOSE：选择本地资源数据，例如联系人、相册等；系统一般对不同类型的数据有对应的Picker应用，例如联系人和图库。
• ACTION_VIEW_DATA：查看数据，当使用网址uri时，则表示显示该网址对应的内容。
• ACTION_VIEW_MULTIPLE_DATA：发送多个数据记录的操作。

entities：表示目标Ability的类别信息（如浏览器、视频播放器），在隐式Want中是对action的补充。在隐式Want中，开发者可定义该字段，来过滤匹配应用的类别，例如必须是浏览器。在Want内声明entities字段表示希望被调用方应用属于声明的类别。在被调用方应用配置文件skills字段内声明entites表示该应用支持的类别。

常用entities

• ENTITY_DEFAULT：默认类别无实际意义。
• ENTITY_HOME：主屏幕有图标点击入口类别。
• ENTITY_BROWSABLE：指示浏览器类别。

Want的定义与用途

Want是对象间信息传递的载体，可以用于应用组件间的信息传递。其使用场景之一是作为startAbility()的参数，包含了指定的启动目标以及启动时需携带的相关数据，如bundleName和abilityName字段分别指明目标Ability所在应用的包名以及对应包内的Ability名称。当UIAbilityA启动UIAbilityB并需要传入一些数据给UIAbilityB时，Want可以作为一个载体将数据传给UIAbilityB。

图1 Want用法示意

Want的类型

• 显式Want：在启动Ability时指定了abilityName和bundleName的Want称为显式Want。当有明确处理请求的对象时，通过提供目标Ability所在应用的包名信息（bundleName），并在Want内指定abilityName便可启动目标Ability。显式Want通常用于在当前应用开发中启动某个已知的Ability。参数说明参见Want参数说明。
  1. let wantInfo = {
  2. deviceId: ”, // deviceId为空表示本设备
  3. bundleName: ‘com.example.myapplication’,
  4. abilityName: ‘FuncAbility’,
  5. }
• 隐式Want：在启动UIAbility时未指定abilityName的Want称为隐式Want。当请求处理的对象不明确时，希望在当前应用中使用其他应用提供的某个能力（通过skills标签定义），而不关心提供该能力的具体应用，可以使用隐式Want。例如使用隐式Want描述需要打开一个链接的请求，而不关心通过具体哪个应用打开，系统将匹配声明支持该请求的所有应用。
  1. let wantInfo = {
  2. // uncomment line below if wish to implicitly query only in the specific bundle.
  3. // bundleName: ‘com.example.myapplication’,
  4. action: ‘ohos.want.action.search’,
  5. // entities can be omitted
  6. entities: [ ‘entity.system.browsable’ ],
  7. uri: ‘https://www.test.com:8080/query/student’,
  8. type: ‘text/plain’,
  9. };
  说明
  • 根据系统中待匹配Ability的匹配情况不同，使用隐式Want启动Ability时会出现以下三种情况。
    • 未匹配到满足条件的Ability：启动失败。
    • 匹配到一个满足条件的Ability：直接启动该Ability。
    • 匹配到多个满足条件的Ability（UIAbility）：弹出选择框让用户选择。
  • 调用方传入的want参数中不带有abilityName和bundleName，则不允许通过隐式Want启动所有应用的ServiceExtensionAbility。
  • 调用方传入的want参数中带有bundleName，则允许使用startServiceExtensionAbility()方法隐式Want启动ServiceExtensionAbility，默认返回优先级最高的ServiceExtensionAbility，如果优先级相同，返回第一个。

Want参数说明

UIAbility组件的基本用法包括：指定UIAbility的启动页面以及获取UIAbility的上下文UIAbilityContext。

指定UIAbility的启动页面

应用中的UIAbility在启动过程中，需要指定启动页面，否则应用启动后会因为没有默认加载页面而导致白屏。可以在UIAbility的onWindowStageCreate()生命周期回调中，通过WindowStage对象的loadContent()方法设置启动页面。

import UIAbility from '@ohos.app.ability.UIAbility';import Window from '@ohos.window';
export default class EntryAbility extends UIAbility {    onWindowStageCreate(windowStage: Window.WindowStage) {        // Main window is created, set main page for this ability        windowStage.loadContent('pages/Index', (err, data) => {            // ...        });    }
    // ...}

说明

在DevEco Studio中创建的UIAbility中，该UIAbility实例默认会加载Index页面，根据需要将Index页面路径替换为需要的页面路径即可。

获取UIAbility的上下文信息

UIAbility类拥有自身的上下文信息，该信息为UIAbilityContext类的实例，UIAbilityContext类拥有abilityInfo、currentHapModuleInfo等属性。通过UIAbilityContext可以获取UIAbility的相关配置信息，如包代码路径、Bundle名称、Ability名称和应用程序需要的环境状态等属性信息，以及可以获取操作UIAbility实例的方法（如startAbility()、connectServiceExtensionAbility()、terminateSelf()等）。

• 在UIAbility中可以通过this.context获取UIAbility实例的上下文信息。
  1. import UIAbility from ‘@ohos.app.ability.UIAbility’;
  2. export default class EntryAbility extends UIAbility {
  3. onCreate(want, launchParam) {
  4. // 获取UIAbility实例的上下文
  5. let context = this.context;
  6. // …
  7. }
  8. }
• 在页面中获取UIAbility实例的上下文信息，包括导入依赖资源context模块和在组件中定义一个context变量两个部分。
  1. import common from ‘@ohos.app.ability.common’;
  2. @Entry
  3. @Component
  4. struct Index {
  5. private context = getContext(this) as common.UIAbilityContext;
  6. startAbilityTest() {
  7. let want = {
  8. // Want参数信息
  9. };
  10. this.context.startAbility(want);
  11. }
  12. // 页面展示
  13. build() {
  14. // …
  15. }
  16. }
  也可以在导入依赖资源context模块后，在具体使用UIAbilityContext前进行变量定义。
  1. import common from ‘@ohos.app.ability.common’;
  2. @Entry
  3. @Component
  4. struct Index {
  5. startAbilityTest() {
  6. let context = getContext(this) as common.UIAbilityContext;
  7. let want = {
  8. // Want参数信息
  9. };
  10. context.startAbility(want);
  11. }
  12. // 页面展示
  13. build() {
  14. // …
  15. }
  16. }

概述

UIAbility组件是一种包含UI界面的应用组件，主要用于和用户交互。

UIAbility组件是系统调度的基本单元，为应用提供绘制界面的窗口；一个UIAbility组件中可以通过多个页面来实现一个功能模块。每一个UIAbility组件实例，都对应于一个最近任务列表中的任务。

声明配置

为使应用能够正常使用UIAbility，需要在module.json5配置文件的abilities标签中声明UIAbility的名称、入口、标签等相关信息。

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility", // UIAbility组件的名称
        "srcEntrance": "./ets/entryability/EntryAbility.ts", // UIAbility组件的代码路径
        "description": "$string:EntryAbility_desc", // UIAbility组件的描述信息
        "icon": "$media:icon", // UIAbility组件的图标
        "label": "$string:EntryAbility_label", // UIAbility组件的标签
        "startWindowIcon": "$media:icon", // UIAbility组件启动页面图标资源文件的索引
        "startWindowBackground": "$color:start_window_background", // UIAbility组件启动页面背景颜色资源文件的索引
        // ...
      }
    ]
  }
}