负一屏提供日常功能的快捷入口,为高频应用提供统一平台能力,展示用户最关心的信息,丰富HarmonyOS应用的使用场景。当应用进入后台,并处于运行中状态时,开发者可以在负一屏创建Ongoing卡片,用于查看应用运行时的状态。
场景介绍
Ongoing卡片展示后台正在运行的业务,应用以通知的方式向负一屏发送通知消息,在负一屏展示卡片信息。任务结束后,应用需要确保通知到负一屏移除之前的卡片。
卡片主要组成部分:图标、内容。应用可以通过ComponentProvider自定义一个卡片布局,以通知的方式发送到负一屏,负一屏将解析后的ComponentProvider页面展示到负一屏。还可以将图标及内容同样以通知的方式发送给负一屏,通过负一屏提供的通用布局展示出来。
Ongoing卡片以图标加实时刷新的文字内容展示后台执行中的应用信息。左侧图标体现应用身份,右侧为文本信息,效果如图所示,具体UX布局要求请参考智能穿戴设计指南。
具体效果如图所示。
开发指导
Ongoing卡片的实现使用了消息通知的接口NotificationHelper,如果负一屏提供的通用布局无法满足您的需求,应用可通过ComponentProvider实现自定义卡片,将通知消息发送到负一屏进行展示。如果可以满足要求,我们更推荐通过负一屏提供的通用布局来展示应用的信息。
创建负一屏卡片通知通道
NotificationSlot slot = new NotificationSlot(ONGOING_CARD_SLOT_ID, ONGOING_CARD_NAME, NotificationSlot.LEVEL_MIN);
slot.setDescription(ONGOING_CARD_SLOT_DESCRIPTION);
try {
NotificationHelper.addNotificationSlot(slot);
} catch (RemoteException ex) {
LogUtil.error(TAG, “Add ongoing card slot exception.”);
}
在发送端,如果一个应用中已经创建了消息通道,可以复用;但是为了区别负一屏卡片通道和消息通知通道,建议单独创建一个通知通道。
创建卡片通知消息
创建通知请求
NotificationRequest request = new NotificationRequest(context, notificationId);
request.setSlotId(slot.getId());
负一屏卡片通知发送后,虽然不会在设备的通知栏中显示通知,但仍需设置通知内容:
String title = “title”;
String text = “There is an ongoing notification content.”;
NotificationRequest.NotificationNormalContent content = new NotificationRequest.NotificationNormalContent();
content.setTitle(title).setText(text);
NotificationRequest.NotificationContent notificationContent = new NotificationRequest.NotificationContent(content);
request.setContent(notificationContent);
添加布局
如果开发者需要自定义一个卡片布局,可以构建一个ComponentProvider,再通过通知的方式发送给负一屏。
ComponentProvider componentProvider = new ComponentProvider(ResourceTable.Layout_ongoing_card_componentProvider, context); // 创建ComponentProvider对象
componentProvider.setString(ResourceTable.Id_ongoing_card_text, “setText”, “TextContent”); // 设置布局中的文本内容
notificationRequest.setCustomView(componentProvider);
如果要在自定义布局中添加跳转事件,可以通过IntentAgent实现。
Intent intent = new Intent();
Operation operation = new Intent.OperationBuilder()
.withDeviceId(“”)
.withBundleName(bundleName)
.withAbilityName(abilityName)
.build();
intent.setOperation(operation); // 创建跳转的目的ability
List<Intent> intentList = new ArrayList<>();
intentList.add(intent);
IntentAgentInfo paramsInfo = new IntentAgentInfo(INTENT_AGENT_REQUEST,
IntentAgentConstant.OperationType.START_ABILITY, IntentAgentConstant.Flags.UPDATE_PRESENT_FLAG, intentList, null);
IntentAgent intentAgent = IntentAgentHelper.getIntentAgent(context, paramsInfo);
componentProvider.setIntentAgent(ResourceTable.ResourceTable.Id_ongoing_card_notification, intentAgent); // 设置跳转事件信息
创建ComponentProvider对象
ResourceTable.Layout_ongoing_card_componentProvider:卡片布局资源xml文件所对应的资源ID。
context:使用的是ability级别的,不能是Application级别的context。
设置布局中的文本内容
创建跳转的目的ability
abilityName:目的Ability的Ability名。
设置跳转事件信息
ResourceTable.Id_ongoing_card_notification:能够点击跳转的热区布局资源ID。
intentAgent:创建好的跳转事件信息。
NotificationRequest request = new NotificationRequest(context, notificationId);
request.setLittleIcon(PixelMap) // 设置卡片图标
String text = “There is an ongoing notification content.”;
NotificationNormalContent content = new NotificationNormalContent();
content.setText(text); // 设置卡片内容
String additionalText = “This is additional content”;
content.setAdditionalText(additionalText); // (可选)设置卡片额外内容,设置后将会展示在卡片内容下方
NotificationContent notificationContent = new NotificationContent(content);
request.setContent(notificationContent);
request.setIntentAgent(intentAgent); // 设置通知可以触发的事件
设置卡片图标
NotificationRequest.setLittleIcon设置卡片图标
设置卡片内容
NotificationNormalContent.setText设置卡片内容
注:Ongoing概述卡片的标签需要设置为“Ongoing_Overview”。
发送和移除通知
发送通知
当卡片内容构造完成后,应用可视自己业务情况在合适的时机将卡片信息发送给负一屏,例如:锻炼开始的时候、音乐开始播放的时候、计时器开始计时的时候。由于负一屏在接收端复用消息通知通道,这样需要将负一屏的通知消息和通知栏消息区分开,在发送通知的时候需要添加ongoing标签。
// 方法一:直接在发送的方法中设置标签
try {
NotificationHelper.publishNotification(ONGOING_TAG, notificationRequest); // 设置ongoing标签
} catch (RemoteException exception) {
LogUtil.error(TAG, “A remote exception occurred when publish ongoing card notification.”);
}
// 方法二:在构造的notificationRequest中设置标签
IntentParams params = new IntentParams();
params.setParams(“MinusOneExtraTag”,ONGOING_TAG); // MinusOneExtraTag必须准确无误
notificationRequest.setAdditionalData(params);
try {
NotificationHelper.publishNotification(notificationRequest); // 无需再次设置标签
} catch (RemoteException exception) {
LogUtil.error(TAG, “A remote exception occurred when publish ongoing card notification.”);
}
// 或者将相应服务保留在后台并发送通知
keepBackgroundRunning(notificationId, notificationRequest);
设置ongoing标签
ONGOING_TAG这里设置为Ongoing_Overview。
移除通知
当任务完成后,请确保通知负一屏移除之前的卡片,这个需要根据业务的实际情况来决定。例如通话应用会在来电时向负一屏发送卡片信息,挂断后通知负一屏移除;计时器会在计时开始时向负一屏发送卡片信息,计时结束时通知负一屏移除;锻炼应用在每次锻炼开始时向负一屏发送卡片信息,锻炼结束后通知负一屏移除掉卡片。
// 使用带标签的publishNotification()方法发送通知的移除
try {
NotificationHelper.cancelNotification(ONGOING_TAG, notificationId);
} catch (RemoteException exception) {
LogUtil.error(TAG, “A remote exception occurred when cancel ongoing card notification.”);
}
// 未使用带标签的publishNotification()方法发送通知的移除
try {
NotificationHelper.cancelNotification(notificationId);
} catch (RemoteException exception) {
LogUtil.error(TAG, “A remote exception occurred when cancel ongoing card notification.”);
}