HarmonyOS4.0系统性深入开发10卡片事件能力说明

卡片事件能力说明

ArkTS卡片中提供了postCardAction()接口用于卡片内部和提供方应用间的交互,当前支持router、message和call三种类型的事件,仅在卡片中可以调用。

HarmonyOS4.0系统性深入开发10卡片事件能力说明_第1张图片

接口定义:postCardAction(component: Object, action: Object): void

接口参数说明:

参数名 参数类型 必填 参数描述
component Object 当前自定义组件的实例,通常传入this。
action Object action的具体描述,详情见下表。

action参数说明:

Key Value 样例描述
“action” string action的类型,支持三种预定义的类型:“router”:跳转到提供方应用的指定UIAbility。“message”:自定义消息。触发后会调用提供方FormExtensionAbility的onFormEvent()生命周期回调。“call”:后台启动提供方应用。触发后会拉起提供方应用的指定UIAbility(仅支持launchType为singleton的UIAbility,即启动模式为单实例的UIAbility),但不会调度到前台。提供方应用需要具备后台运行权限(ohos.permission.KEEP_BACKGROUND_RUNNING)。
“bundleName” string “router” / “call” 类型时跳转的包名,可选。
“moduleName” string “router” / “call” 类型时跳转的模块名,可选。
“abilityName” string “router” / “call” 类型时跳转的UIAbility名,必填。
“params” Object 当前action携带的额外参数,内容使用JSON格式的键值对形式。"call"类型时需填入参数’method’,且类型需要为string类型,用于触发UIAbility中对应的方法,必填。

postCardAction()接口示例代码:

Button('跳转')
  .width('40%')
  .height('20%')
  .onClick(() => {
    postCardAction(this, {
      'action': 'router',
      'bundleName': 'com.example.myapplication',
      'abilityName': 'EntryAbility',
      'params': {
        'message': 'testForRouter' // 自定义要发送的message
      }
    });
  })
Button('拉至后台')
  .width('40%')
  .height('20%')
  .onClick(() => {
    postCardAction(this, {
      'action': 'call',
      'bundleName': 'com.example.myapplication',
      'abilityName': 'EntryAbility',
      'params': {
        'method': 'fun', // 自定义调用的方法名,必填
        'message': 'testForCall' // 自定义要发送的message
      }
    });
  })

使用router事件跳转到指定UIAbility

在卡片中使用postCardAction接口的router能力,能够快速拉起卡片提供方应用的指定UIAbility,因此UIAbility较多的应用往往会通过卡片提供不同的跳转按钮,实现一键直达的效果。例如相机卡片,卡片上提供拍照、录像等按钮,点击不同按钮将拉起相机应用的不同UIAbility,从而提升用户的体验。

HarmonyOS4.0系统性深入开发10卡片事件能力说明_第2张图片

通常使用按钮控件来实现页面拉起,示例代码如下:

  • 在卡片页面中布局两个按钮,点击其中一个按钮时调用postCardAction向指定UIAbility发送router事件,并在事件内定义需要传递的内容。

    @Entry
    @Component
    struct WidgetCard {
      build() {
        Column() {
          Button('功能A')
            .margin('20%')
            .onClick(() => {
              console.info('Jump to EntryAbility funA');
              postCardAction(this, {
                'action': 'router',
                'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility
                'params': {
                  'targetPage': 'funA' // 在EntryAbility中处理这个信息
                }
              });
            })
    
          Button('功能B')
            .margin('20%')
            .onClick(() => {
              console.info('Jump to EntryAbility funB');
              postCardAction(this, {
                'action': 'router',
                'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility
                'params': {
                  'targetPage': 'funB' // 在EntryAbility中处理这个信息
                }
              });
            })
        }
        .width('100%')
        .height('100%')
      }
    }
    
  • 在UIAbility中接收router事件并获取参数,根据传递的params不同,选择拉起不同的页面。

    import UIAbility from '@ohos.app.ability.UIAbility';
    import window from '@ohos.window';
    
    let selectPage = "";
    let currentWindowStage = null;
    
    export default class CameraAbility extends UIAbility {
      // 如果UIAbility第一次启动,在收到Router事件后会触发onCreate生命周期回调
      onCreate(want, launchParam) {
        // 获取router事件中传递的targetPage参数
        console.info("onCreate want:" + JSON.stringify(want));
        if (want.parameters.params !== undefined) {
          let params = JSON.parse(want.parameters.params);
          console.info("onCreate router targetPage:" + params.targetPage);
          selectPage = params.targetPage;
        }
      }
      // 如果UIAbility已在后台运行,在收到Router事件后会触发onNewWant生命周期回调
      onNewWant(want, launchParam) {
        console.info("onNewWant want:" + JSON.stringify(want));
        if (want.parameters.params !== undefined) {
          let params = JSON.parse(want.parameters.params);
          console.info("onNewWant router targetPage:" + params.targetPage);
          selectPage = params.targetPage;
        }
        if (currentWindowStage != null) {
          this.onWindowStageCreate(currentWindowStage);
        }
      }
    
      onWindowStageCreate(windowStage: window.WindowStage) {
        let targetPage;
        // 根据传递的targetPage不同,选择拉起不同的页面
        switch (selectPage) {
          case 'funA':
            targetPage = 'pages/FunA';
            break;
          case 'funB':
            targetPage = 'pages/FunB';
            break;
          default:
            targetPage = 'pages/Index';
        }
        if (currentWindowStage === null) {
          currentWindowStage = windowStage;
        }
        windowStage.loadContent(targetPage, (err, data) => {
          if (err && err.code) {
            console.info('Failed to load the content. Cause: %{public}s', JSON.stringify(err));
            return;
          }
        });
      }
    };
    

使用call事件拉起指定UIAbility到后台

许多应用希望借助卡片的能力,实现和应用在前台时相同的功能。例如音乐卡片,卡片上提供播放、暂停等按钮,点击不同按钮将触发音乐应用的不同功能,进而提高用户的体验。在卡片中使用postCardAction接口的call能力,能够将卡片提供方应用的指定UIAbility拉到后台。同时,call能力提供了调用应用指定方法、传递数据的功能,使应用在后台运行时可以通过卡片上的按钮执行不同的功能。

通常使用按钮控件来触发call事件,示例代码如下:

  • 在卡片页面中布局两个按钮,点击其中一个按钮时调用postCardAction向指定UIAbility发送call事件,并在事件内定义需要调用的方法和传递的数据。需要注意的是,method参数为必选参数,且类型需要为string类型,用于触发UIAbility中对应的方法。

    @Entry
    @Component
    struct WidgetCard {
      build() {
        Column() {
          Button('功能A')
            .margin('20%')
            .onClick(() => {
              console.info('call EntryAbility funA');
              postCardAction(this, {
                'action': 'call',
                'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility
                'params': {
                  'method': 'funA' // 在EntryAbility中调用的方法名
                }
              });
            })
           Button('功能B')
            .margin('20%')
            .onClick(() => {
              console.info('call EntryAbility funB');
              postCardAction(this, {
                'action': 'call',
                'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility
                'params': {
                  'method': 'funB', // 在EntryAbility中调用的方法名
                  'num': 1 // 需要传递的其他参数
                }
              });
            })
        }
        .width('100%')
        .height('100%')
      }
    }
    
  • 在UIAbility中接收call事件并获取参数,根据传递的method不同,执行不同的方法。其余数据可以通过readString的方式获取。需要注意的是,UIAbility需要onCreate生命周期中监听所需的方法。

    import UIAbility from '@ohos.app.ability.UIAbility';
     
    function FunACall(data) {
      // 获取call事件中传递的所有参数
      console.log('FunACall param:' + JSON.stringify(data.readString()));
      return null;
    }
     function FunBCall(data) {
      console.log('FunACall param:' + JSON.stringify(data.readString()));
      return null;
    }
     
    export default class CameraAbility extends UIAbility {
      // 如果UIAbility第一次启动,在收到call事件后会触发onCreate生命周期回调
      onCreate(want, launchParam) {
          try {
              // 监听call事件所需的方法
              this.callee.on('funA', FunACall);
              this.callee.on('funB', FunBCall);
          } catch (error) {
              console.log('register failed with error. Cause: ' + JSON.stringify(error));
          }
      }
       
      // 进程退出时,解除监听
      onDestroy() {
          try {
              this.callee.off('funA');
              this.callee.off('funB');
          } catch (error) {
              console.log('register failed with error. Cause: ' + JSON.stringify(error));
          }
      }
    };
    

你可能感兴趣的:(鸿蒙系统,microsoft,windows,harmonyos,intellij,idea)