用戶在使用應用時，經常想要了解應用程序在執行的操作，如下載完成、新郵件到達、發布即時的客服支付通知等，這些通知除了攜帶基本的文本圖片信息外，最好還可以支持文件上傳下載進度場景下的進度條通知，以及點擊通知欄可以拉起目標應用的意圖類型通知。開發者只有滿足用戶多種場景本地通知的需求，才能帶來更好的用戶體驗。
HarmonyOS SDK用戶通知服務（Notification Kit）為開發者提供本地通知發布通道，開發者可借助Notification Kit將應用產生的通知直接在客戶端本地推送給用戶，本地通知根據通知類型、用戶設置及發布場景會產生對應的鈴聲、震動、橫幅、鎖屏、息屏、通知欄提醒和顯示。
能力范圍
Notification Kit支持的能力主要包括：
? 發布文本、進度條等類型通知。
? 攜帶或更新應用通知數字角標。
? 取消曾經發布的某條或全部通知。
? 查詢已發布的通知列表。
? 查詢應用自身通知開關狀態。
? 應用通知用戶的能力默認關閉，開發者可拉起授權框，請求用戶授權發布通知。
業務流程
使用Notification Kit的主要業務流程如下：
1.請求用戶通知授權。
2.應用發布通知到通知服務。
3.用戶通過授權后，將通知展示到通知中心。
通知樣式
Notification Kit中常用的通知樣式如下：
開發步驟
請求通知授權
- 導入NotificationManager模塊。
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { common } from '@kit.AbilityKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 請求通知授權。
可通過requestEnableNotification的錯誤碼判斷用戶是否授權。若返回的錯誤碼為1600004，即為拒絕授權。
let context = getContext(this) as common.UIAbilityContext;
notificationManager.isNotificationEnabled().then((data: boolean) => {hilog.info(DOMAIN_NUMBER, TAG, "isNotificationEnabled success, data: " + JSON.stringify(data));if(!data){notificationManager.requestEnableNotification(context).then(() => {hilog.info(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification success`);}).catch((err : BusinessError) => {if(1600004 == err.code){hilog.error(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification refused, code is ${err.code}, message is ${err.message}`);} else {hilog.error(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);}});}
}).catch((err : BusinessError) => {hilog.error(DOMAIN_NUMBER, TAG, `isNotificationEnabled fail, code is ${err.code}, message is ${err.message}`);
});
管理通知角標
- 導入NotificationManager模塊。
import { notificationManager } from '@kit.NotificationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 增加角標個數。
發布通知在NotificationRequest的badgeNumber字段里攜帶，可參考通知發布章節。
示例為調用setBadgeNumber接口增加角標，在發布完新的通知后，調用該接口。
let setBadgeNumberCallback = (err: BusinessError): void => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to set badge number. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in setting badge number.`);
}let badgeNumber = 9;
notificationManager.setBadgeNumber(badgeNumber, setBadgeNumberCallback);
- 減少角標個數。
一條通知被查看后，應用需要調用接口設置剩下未讀通知個數，桌面刷新角標。
let setBadgeNumberCallback = (err: BusinessError): void => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to set badge number. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in setting badge number.`);
}let badgeNumber = 8;
notificationManager.setBadgeNumber(badgeNumber, setBadgeNumberCallback);
管理通知渠道
- 導入notificationManager模塊。
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 創建指定類型的通知渠道。
// addslot回調
let addSlotCallBack = (err: BusinessError): void => {if (err) {hilog.info(DOMAIN_NUMBER, TAG, `addSlot failed, code is ${err.code}, message is ${err.message}`);} else {hilog.info(DOMAIN_NUMBER, TAG, `addSlot success`);}
}
notificationManager.addSlot(notificationManager.SlotType.SOCIAL_COMMUNICATION, addSlotCallBack);
- 查詢指定類型的通知渠道。
獲取對應渠道是否創建以及該渠道支持的通知提醒方式，比如是否有聲音提示，是否有震動，鎖屏是否可見等。
// getSlot回調
let getSlotCallback = (err: BusinessError, data: notificationManager.NotificationSlot): void => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `getSlot failed, code is ${JSON.stringify(err.code)}, message is ${JSON.stringify(err.message)}`);} else {hilog.info(DOMAIN_NUMBER, TAG, `getSlot success. `);if (data != null) {hilog.info(DOMAIN_NUMBER, TAG, `slot enable status is ${JSON.stringify(data.enabled)}`);hilog.info(DOMAIN_NUMBER, TAG, `slot level is ${JSON.stringify(data.level)}`);hilog.info(DOMAIN_NUMBER, TAG, `vibrationEnabled status is ${JSON.stringify(data.vibrationEnabled)}`);hilog.info(DOMAIN_NUMBER, TAG, `lightEnabled status is ${JSON.stringify(data.lightEnabled)}`);}}
}
let slotType: notificationManager.SlotType = notificationManager.SlotType.SOCIAL_COMMUNICATION;
notificationManager.getSlot(slotType, getSlotCallback);
- 刪除指定類型的通知渠道。
// removeSlot回調
let removeSlotCallback = (err: BusinessError): void => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `removeSlot failed, code is ${JSON.stringify(err.code)}, message is ${JSON.stringify(err.message)}`);} else {hilog.info(DOMAIN_NUMBER, TAG, "removeSlot success");}
}
let slotType: notificationManager.SlotType = notificationManager.SlotType.SOCIAL_COMMUNICATION;
notificationManager.removeSlot(slotType, removeSlotCallback);
發布通知
發布文本類型通知
- 導入模塊。
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 構造NotificationRequest對象，并發布通知。
普通文本類型通知由標題、文本內容和附加信息三個字段組成，其中標題和文本內容是必填字段，大小均需要小于200字節，超出部分會被截斷。
let notificationRequest: notificationManager.NotificationRequest = {id: 1,content: {notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, // 普通文本類型通知normal: {title: 'test_title',text: 'test_text',additionalText: 'test_additionalText',}}
};
notificationManager.publish(notificationRequest, (err: BusinessError) => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');
});
多行文本類型通知繼承了普通文本類型的字段，同時新增了多行文本內容、內容概要和通知展開時的標題，其字段均小于200字節，超出部分會被截斷。通知默認顯示與普通文本相同，展開后，標題顯示為展開后標題內容，多行文本內容多行顯示。
let notificationRequest: notificationManager.NotificationRequest = {id: 3,content: {notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_MULTILINE, // 多行文本類型通知multiLine: {title: 'test_title',text: 'test_text',briefText: 'test_briefText',longTitle: 'test_longTitle',lines: ['line_01', 'line_02', 'line_03', 'line_04'],}}
};
// 發布通知
notificationManager.publish(notificationRequest, (err: BusinessError) => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');
});
發布進度條類型通知
- 導入模塊。
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 查詢系統是否支持進度條模板，查詢結果為支持downloadTemplate模板類通知。
notificationManager.isSupportTemplate('downloadTemplate').then((data:boolean) => {hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in supporting download template notification.');let isSupportTpl: boolean = data; // isSupportTpl的值為true表示支持downloadTemplate模板類通知，false表示不支持
}).catch((err: BusinessError) => {hilog.error(DOMAIN_NUMBER, TAG, `Failed to support download template notification. Code is ${err.code}, message is ${err.message}`);
});
- 構造進度條模板對象，并發布通知。
let notificationRequest: notificationManager.NotificationRequest = {id: 5,content: {notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal: {title: 'test_title',text: 'test_text',additionalText: 'test_additionalText'}},// 構造進度條模板，name字段當前需要固定配置為downloadTemplatetemplate: {name: 'downloadTemplate',data: { title: 'File Title', fileName: 'music.mp4', progressValue: 45 }}
}// 發布通知
notificationManager.publish(notificationRequest, (err: BusinessError) => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');
});
為通知添加行為意圖
- 導入模塊。
import { notificationManager } from '@kit.NotificationKit';
import { wantAgent, WantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 創建WantAgentInfo信息。
場景一：創建拉起UIAbility的WantAgent的WantAgentInfo信息。
let wantAgentObj:WantAgent; // 用于保存創建成功的wantAgent對象，后續使用其完成觸發的動作。
// 通過WantAgentInfo的operationType設置動作類型
let wantAgentInfo:wantAgent.WantAgentInfo = {wants: [{deviceId: '',bundleName: 'com.samples.notification',abilityName: 'SecondAbility',action: '',entities: [],uri: '',parameters: {}}],actionType: wantAgent.OperationType.START_ABILITY,requestCode: 0,wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
};
場景二：創建發布公共事件的WantAgent的WantAgentInfo信息。
let wantAgentObj:WantAgent; // 用于保存創建成功的WantAgent對象，后續使用其完成觸發的動作。
// 通過WantAgentInfo的operationType設置動作類型
let wantAgentInfo:wantAgent.WantAgentInfo = {wants: [{action: 'event_name', // 設置事件名parameters: {},}],actionType: wantAgent.OperationType.SEND_COMMON_EVENT,requestCode: 0,wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG],
};
- 調用getWantAgent()方法進行創建WantAgent。
// 創建WantAgent
wantAgent.getWantAgent(wantAgentInfo, (err: BusinessError, data:WantAgent) => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to get want agent. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in getting want agent.');wantAgentObj = data;
});
- 構造NotificationRequest對象，并發布WantAgent通知。
// 構造NotificationRequest對象
let notificationRequest: notificationManager.NotificationRequest = {content: {notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal: {title: 'Test_Title',text: 'Test_Text',additionalText: 'Test_AdditionalText',},},id: 6,label: 'TEST',// wantAgentObj使用前需要保證已被賦值（即步驟3執行完成）wantAgent: wantAgentObj,
}notificationManager.publish(notificationRequest, (err: BusinessError) => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');
});
- 用戶通過點擊通知欄上的通知，系統會自動觸發WantAgent的動作。
了解更多詳情>>
獲取用戶通知服務開發指導文檔
)
)
