@ohos.app.ability.Want (Want)

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

说明：

本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import Want from '@ohos.app.ability.Want';

属性

系统能力：以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase

示例：

• 基础用法：在UIAbility对象中调用，示例中的context的获取方式请参见获取UIAbility的上下文信息。

  import common from '@ohos.app.ability.common';
  let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
  let want = {
    'deviceId': '', // deviceId为空表示本设备
    'bundleName': 'com.example.myapplication',
    'abilityName': 'FuncAbility',
    'moduleName': 'entry' // moduleName非必选
  };
  
  context.startAbility(want, (err) => {
    // 显式拉起Ability，通过bundleName、abilityName和moduleName可以唯一确定一个Ability
    console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
  });
  

• 目前支持的数据类型有：字符串、数字、布尔、对象、数组和文件描述符等。

  • 字符串（String）

    import common from '@ohos.app.ability.common';
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForString: 'str',
      },
    };
    
    context.startAbility(want, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • 数字（Number）

    import common from '@ohos.app.ability.common';
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForInt: 100,
        keyForDouble: 99.99,
      },
    };
    
    context.startAbility(want, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • 布尔（Boolean）

    import common from '@ohos.app.ability.common';
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForBool: true,
      },
    };
    
    context.startAbility(want, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • 对象（Object）

    import common from '@ohos.app.ability.common';
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForObject: {
          keyForObjectString: 'str',
          keyForObjectInt: -200,
          keyForObjectDouble: 35.5,
          keyForObjectBool: false,
        },
      },
    };
    
    context.startAbility(want, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • 数组（Array）

    import common from '@ohos.app.ability.common';
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    let want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'FuncAbility',
      parameters: {
        keyForArrayString: ['str1', 'str2', 'str3'],
        keyForArrayInt: [100, 200, 300, 400],
        keyForArrayDouble: [0.1, 0.2],
        keyForArrayObject: [{ obj1: 'aaa' }, { obj2: 100 }],
      },
    };
    
    context.startAbility(want, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • 文件描述符（FD）

    import fs from '@ohos.file.fs';
    
    import common from '@ohos.app.ability.common';
    let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
    
    let fd;
    try {
      fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd;
    } catch(err) {
      console.error(`Failed to openSync. Code: ${err.code}, message: ${err.message}`);
    }
    let want = {
      'deviceId': '', // deviceId为空表示本设备
      'bundleName': 'com.example.myapplication',
      'abilityName': 'FuncAbility',
      'moduleName': 'entry', // moduleName非必选
      'parameters': {
        'keyFd': { 'type': 'FD', 'value': fd } // {'type':'FD', 'value':fd}是固定用法，用于表示该数据是FD
      }
    };
    
    context.startAbility(want, (err) => {
      console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
    });
    

  • parameter参数用法：以ability.params.backToOtherMissionStack为例，ServiceExtension在拉起UIAbility的时候，可以支持跨任务链返回。

      // (1) UIAbility1启动一个ServiceExtension
      let context = getContext(this) as common.UIAbilityContext; // UIAbilityContext
      let want = {
        bundleName: 'com.example.myapplication1',
        abilityName: 'ServiceExtensionAbility',
      };
  
      context.startAbility(want, (err) => {
        console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
      });
  
      // (2) 该ServiceExtension去启动另一个UIAbility2，并在启动的时候携带参数ability.params.backToOtherMissionStack为true
      let context = ...; // ServiceExtensionContext
      let want = {
        bundleName: 'com.example.myapplication2',
        abilityName: 'MainAbility',
        parameters: {
          "ability.params.backToOtherMissionStack": true,
        },
      };
  
      context.startAbility(want, (err) => {
        console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
      });
  

  说明：上例中，如果ServiceExtension启动UIAbility2时不携带ability.params.backToOtherMissionStack参数，或者携带的ability.params.backToOtherMissionStack参数为false，则UIAbility1和UIAbility2不在同一个任务栈里面，在UIAbility2的界面点back键，不会回到UIAbility1的界面。如果携带的ability.params.backToOtherMissionStack参数为true，则表示支持跨任务链返回，此时在UIAbility2的界面点back键，会回到UIAbility1的界面。