HarmonyOS之IntentAgent启动Ability和发布公共事件

一、简介

• IntentAgent 封装了一个指定行为的 Intent，可以通过 triggerIntentAgent 接口主动触发，也可以与通知绑定被动触发。
• 具体的行为包括：启动 Ability 和发布公共事件。例如：收到通知后，在点击通知后跳转到一个新的 Ability，不点击则不会触发。

二、API 说明

• IntentAgent 相关基础类包括 IntentAgentHelper、IntentAgentInfo、IntentAgentConstant 和 TriggerInfo，基础类之间的关系如下图所示：

• IntentAgentHelper 封装了获取、激发、取消 IntentAgent 等静态方法，主要接口如下：

接口名
描述
getIntentAgent(Context context, IntentAgentInfo paramsInfo)
获取一个IntentAgent实例。
triggerIntentAgent(Context context, IntentAgent agent, IntentAgent.Oncompleted onCompleted, EventHandler handler, TriggerInfo paramsInfo)
主动激发一个IntentAgent实例。
cancel(IntentAgent agent)
取消一个IntentAgent实例。
judgeEquality(IntentAgent agent, IntentAgent otherAgent)
判断两个IntentAgent实例是否相等。
getHashCode(IntentAgent agent)
获取一个IntentAgent实例的哈希码。
getBundleName(IntentAgent agent)
获取一个IntentAgent实例的包名。
getUid(IntentAgent agent)
获取一个IntentAgent实例的用户ID

• IntentAgentInfo 类封装了获取一个 IntentAgent 实例所需的数据。使用构造函数 IntentAgentInfo(int requestCode, OperationType operationType, List flags, List intents, IntentParams extraInfo) 获取 IntentAgentInfo 对象。
• • requestCode：使用者定义的一个私有值；
• • operationType：为 IntentAgentConstant.OperationType 枚举中的值；
• • flags：为 IntentAgentConstant.Flags 枚举中的值；
• • intents：将被执行的意图列表。operationType 的值为 START_ABILITY，START_SERVICE 和 SEND_COMMON_EVENT 时，intents 列表只允许包含一个 Intent；operationType 的值为 START_ABILITIES 时，intents 列表允许包含多个 Intent；
• • extraInfo：表明如何启动一个有页面的 ability，可以为 null，只在 operationType 的值为 START_ABILITY 和 START_ABILITIES 时有意义。
• IntentAgentConstant 类中包含 OperationType 和 Flags 两个枚举类：

类名	枚举值
IntentAgentConstant.OperationType	UNKNOWN_TYPE：不识别的类型。 START_ABILITY：开启一个有页面的Ability。 START_ABILITIES：开启多个有页面的Ability。 START_SERVICE：开启一个无页面的ability。 SEND_COMMON_EVENT：发送一个公共事件。
IntentAgentConstant.Flags	ONE_TIME_FLAG：IntentAgent仅能使用一次。只在operationType的值为START_ABILITY，START_SERVICE和SEND_COMMON_EVENT时有意义。 NO_BUILD_FLAG：如果描述IntentAgent对象不存在，则不创建它，直接返回null。只在operationType的值为START_ABILITY，START_SERVICE和SEND_COMMON_EVENT时有意义。 CANCEL_PRESENT_FLAG：在生成一个新的IntentAgent对象前取消已存在的一个IntentAgent对象。只在operationType的值为START_ABILITY，START_SERVICE和SEND_COMMON_EVENT时有意义。 UPDATE_PRESENT_FLAG：使用新的IntentAgent的额外数据替换已存在的IntentAgent中的额外数据。只在operationType的值为START_ABILITY，START_SERVICE和SEND_COMMON_EVENT时有意义。 CONSTANT_FLAG：IntentAgent是不可变的。 REPLACE_ELEMENT：当前Intent中的element属性可被IntentAgentHelper.triggerIntentAgent()中Intent的element属性取代。 REPLACE_ACTION: 当前Intent中的action属性可被IntentAgentHelper.triggerIntentAgent()中Intent的action属性取代。 REPLACE_URI：当前Intent中的uri属性可被IntentAgentHelper.triggerIntentAgent()中Intent的uri属性取代。 REPLACE_ENTITIES：当前Intent中的entities属性可被IntentAgentHelper.triggerIntentAgent()中Intent的entities属性取代。 REPLACE_BUNDLE：当前Intent中的bundleName属性可被IntentAgentHelper.triggerIntentAgent()中Intent的bundleName属性取代

• TriggerInfo 类封装了主动激发一个 IntentAgent 实例所需的数据，使用构造函数 TriggerInfo(String permission, IntentParams extraInfo, Intent intent, int code) 获取TriggerInfo 对象。
• • permission：IntentAgent 的接收者的权限名称，只在 operationType 的值为 SEND_COMMON_EVENT 时，该参数才有意义。
• • extraInfo：激发 IntentAgent 时用户自定义的额外数据。
• • intent：额外的 Intent。如果 IntentAgentInfo 成员变量 flags 包含 CONSTANT_FLAG，则忽略该参数；如果 flags 包含 REPLACE_ELEMENT，REPLACE_ACTION，REPLACE_URI，REPLACE_ENTITIES 或 REPLACE_BUNDLE，则使用额外 Intent 的element，action，uri，entities 或 bundleName 属性替换原始 Intent 中对应的属性。如果intent是空，则不替换原始Intent的属性。
• • code：提供给IntentAgent目标的结果码。

三、IntentAgent 的使用

• 获取 IntentAgent 的代码示例如下：

	// 指定要启动的Ability的BundleName和AbilityName字段
	// 将Operation对象设置到Intent中
	Operation operation = new Intent.OperationBuilder()
	        .withDeviceId("")
	        .withBundleName("com.testintentagent")
	        .withAbilityName("com.testintentagent.entry.IntentAgentAbility")
	        .build();
	intent.setOperation(operation);
	List<Intent> intentList = new ArrayList<>();
	intentList.add(intent);
	// 定义请求码
	int requestCode = 200;
	// 设置flags
	List<IntentAgentConstant.Flags> flags = new ArrayList<>();
	flags.add(IntentAgentConstant.Flags.UPDATE_PRESENT_FLAG);
	// 指定启动一个有页面的Ability
	IntentAgentInfo paramsInfo = new IntentAgentInfo(requestCode, IntentAgentConstant.OperationType.START_ABILITY, flags, intentList, null);
	// 获取IntentAgent实例
	IntentAgent agent = IntentAgentHelper.getIntentAgent(this, paramsInfo);

• 通知中添加 IntentAgent 的代码示例如下：

	int notificationId = 1;
	NotificationRequest request = new NotificationRequest(notificationId);
	String title = "title";
	String text = "There is a normal notification content.";
	NotificationRequest.NotificationNormalContent content = new NotificationRequest.NotificationNormalContent();
	content.setTitle(title)
	       .setText(text);
	NotificationContent notificationContent = new NotificationContent(content);
	request.setContent(notificationContent); // 设置通知的内容
	request.setIntentAgent(agent); // 设置通知的IntentAgent

• 主动激发 IntentAgent 的代码示例如下：

	int code = 100;
	IntentAgentHelper.triggerIntentAgent(this, agent, null, null, new TriggerInfo(null, null, null, code));