@cordova-ohos/cordova-plugin-local-notification

v1.2.3

Published

2 months ago

Cordova Local Notification Plugin

0High
0Medium
0Low

cordova local-notification ecosystem:cordova cordova-openharmony

cordova-plugin-local-notification

一款专为Cordova/PhoneGap应用设计的本地通知插件，支持在iOS、Android和OHOS设备上创建、调度、更新和取消本地通知，无需依赖远程服务器，可实现定时提醒、任务通知等核心场景。

主要说明：在OHOS系统中，该插件包括两个主要功能，（1）即时提醒，即应用在前台，立即发出通知提醒，用户实时可见，应用退到后台，不能发送通知；（2）定时提醒，例如闹钟、倒计时等功能，此类提醒需要单独向华为申请代理提醒权限，该权限有管控限制，点击查看链接，只有符合要求的应用才可以获取该权限，该插件不采用该方案；但为实现目标，使用日历的替代方案，无需申请任何权限，即可实现倒计时提醒、闹钟提醒等功能，但是提醒是有系统日历触发，并非应用本身触发，但是设置提醒是有应用调起日历接口进行配置。

鸿蒙的内部通知封装了本地通知和日历服务通知，所有即时通知和进度通知使用本地通知，即Notification Kit服务，对于触发通知、重复提醒、闹钟提醒和倒计时提醒使用日历服务，即Calendar Kit，鉴于后台代理提醒，鸿蒙要求专有应用才能使用，因此本插件暂不支持Background Tasks Kit服务，如果您一定要使用后台代理提醒服务，请使用push插件代替。

本地通知参考文档：https://docs.openharmony.cn/pages/v5.1.0/zh-cn/application-dev/notification/notification-overview.md

[日历服务参考文档：https://https://docs.openharmony.cn/pages/v5.1.0/zh-cn/application-dev/calendarmanager/calendarmanager-overview.md](https://docs.openharmony.cn/pages/v5.1.0/zh-cn/application-dev/calendarmanager/calendarmanager-overview.md)

概述

cordova-plugin-local-notification为移动应用提供了全方位的本地通知能力，无需联网即可在设备上触发通知提醒，适用于闹钟、待办事项、日程提醒、应用内消息推送等场景。核心特性包括：

支持即时通知和定时延迟通知（精确到秒）
可自定义通知标题、内容、图标、声音、振动等样式
支持重复通知（每日、每周、每月等周期）
提供通知的创建、更新、取消、清空等完整生命周期管理
支持监听通知的点击、触发、清除等事件
支持应用在前台、后台及关闭状态下的通知触发

安装

在Cordova项目根目录下执行以下命令安装插件，支持从GitHub或本地路径安装：

# 安装hcordova
npm install -g hcordova

# 基础安装
hcordova plugin cordova-plugin-local-notification

# 指定OHOS安装
hcordova plugin cordova-plugin-local-notification --platform ohos


# 从GitHub安装（推荐，获取最新稳定版）
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-local-notification.git --platform ohos

卸载

如需移除插件，在项目根目录执行以下命令：

# 全平台卸载
hcordova plugin remove cordova-plugin-local-notification

# 指定OHOS卸载
hcordova plugin remove cordova-plugin-local-notification  --platform ohos

权限配置

在主工程module.json5中添加日历权限，如下：

{
  "name": "ohos.permission.READ_CALENDAR",
  "reason": "$string:calenderInfo",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
},
{
  "name": "ohos.permission.WRITE_CALENDAR",
  "reason": "$string:calenderInfo",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

核心API说明

插件挂载在cordova.plugins.notification.local对象上，所有API均为异步操作，支持Promise链式调用或回调函数两种方式。

1. 授权本地通知

cordova.plugins.notification.local.requestPermission(function() {
    document.getElementById("notificationPermission").innerHTML = "授权成功";
});

2. 检测是否有权限

cordova.plugins.notification.local.hasPermission(function() {
    document.getElementById("hasNotificationPermission").innerHTML = "有授权";
});

3. 创建渠道

通知渠道说明：OHOS系统支持多种通知渠道，不同通知渠道对应的通知提醒方式不同，可以根据应用的实际场景选择适合的通知渠道，并对通知渠道进行管理（支持创建、查询、删除等操作）。参考连接：https://docs.openharmony.cn/pages/v5.1.0/zh-cn/application-dev/notification/notification-slot.md

| 安卓渠道 | 鸿蒙渠道 | |----------------|--------------------| | IMPORTANCE_NONE | UNKNOWN_TYPE | | IMPORTANCE_MIN | SOCIAL_COMMUNICATION | | IMPORTANCE_LOW | SERVICE_INFORMATION | | IMPORTANCE_DEFAULT | SERVICE_INFORMATION | | IMPORTANCE_HIGH | SERVICE_INFORMATION | | IMPORTANCE_MAX | CUSTOMER_SERVICE |

//创建通知渠道
cordova.plugins.notification.local.createChannel({
    androidChannelId: "my_channel_01", // 渠道ID，自定义
    androidChannelName: "My Channel Name", // 渠道名称，自定义
    androidChannelDescription: "Description of channel", // 渠道描述，自定义
    androidChannelImportance: "IMPORTANCE_DEFAULT", // 安卓渠道，对应OHOS渠道
    androidChannelEnableLights: true, // 通知灯光，OHOS通知渠道不支持自定义，true和false不影响
    androidChannelEnableVibration: true, // 是否震动，OHOS通知渠道不支持自定义，有通知渠道决定
    sound: 'www/audio/ring.mp3', // 播放声音，OHOS通知渠道不支持自定义，有通知渠道决定
    androidChannelSoundUsage: 5 //播放声音参数， OHOS通知渠道不支持自定义，有通知渠道决定
}, function(){
    document.getElementById("channelInfo").innerHTML = "创建成功";
}, this);

4，删除通知渠道

//删除通知渠道
function deleteChannel() {
    cordova.plugins.notification.local.deleteChannel("my_channel_01", function() {
        document.getElementById("deleteInfo").innerHTML = "删除成功";
    }, this);
}

5，添加一个通知按钮

通知按钮先注册，注册成功后，后续发送通知可以引用

**title：**按钮标题
wantAgentInfo： 点击按钮打开对象，点击链接插件详细说明：https://docs.openharmony.cn/pages/v5.1.0/zh-cn/application-dev/reference/apis-ability-kit/js-apis-inner-ability-want.md

//删除通知渠道
function addActions() {
    cordova.plugins.notification.local.addActions('REPLY_NO_CATEGORY', [
        {
            title: 'Reply',
            wantAgentInfo:{
                wants: [
                    {
                        bundleName: 'com.ionicframework.chuzhitong410158',
                        abilityName: 'EntryAbility',
                    }
                ],
                actionType: 1,
                requestCode: 0,
                actionFlags:[4]
            }
        }
    ]);
}

6，立即发送通知

| 属性 | 默认值 | 说明 | |--------------|--------|--------------------------------------------------------------| | actions | [] | 通知的操作项,提前注册的按钮 | | badgeNumber | 0 | 设置应用的角标数量 | | id | 1 | 通知的ID，类型为数字，必传 | | title | "" | 通知的标题，必传 | | text | "" | 通知文本。鸿蒙特性：1. 若文本包含换行符（\n），将使用通知样式 NotificationCompat.InboxStyle；2. 若文本长度超过44个字符，将使用通知样式 NotificationCompat.BigTextStyle | | wantAgentInfo | 对象 | 点击通知后打开的页面 | | androidMessages | [] | 多行通知，多行通知也可以在text里面“\n"换行，通知最多支持3行，超过的后面不显示 |

function sendLocalNotificationAtOnce() {
    cordova.plugins.notification.local.on("add", (notification, eopts) => {
        document.getElementById("atOnceInfo").innerHTML = "发送成功";
    });

    cordova.plugins.notification.local.schedule({
        id: 6,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM\n请注意开会时间。',
        wantAgentInfo:{
            wants: [
                {
                    bundleName: 'com.ionicframework.chuzhitong410158',
                    abilityName: 'EntryAbility',
                }
            ],
            actionType: 1,
            requestCode: 0,
            actionFlags:[4]
        },
        androidMessages: [
            { person: 'Me', message: 'I miss you' },
            { person: 'Irish', message: 'I miss you more!' },
            { person: 'Me', message: 'I always miss you more by 10%' }
        ],
        actions: 'REPLY_NO_CATEGORY'
    },function(notification){
        console.log(notification);
        document.getElementById("atOnceInfo").innerHTML = "发送成功";
    });
}

7，发送进度条通知

进度条通知用于下载文件等场景，但是程序只能在前台，不可转入后台

function sendLocalNotificationProgress() {
    cordova.plugins.notification.local.on("add", (notification, eopts) => {
        document.getElementById("barInfo").innerHTML = "发送成功";
    });
    cordova.plugins.notification.local.schedule({
        id: 6,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM',
        androidProgressBar: {
            name:"下载标题",
            data:{
                title:"下载中",
                fileName:"文件名",
                progressValue:45
            }
        }
    },function(notification){
        console.log(notification);
        document.getElementById("barInfo").innerHTML = "发送成功";
    });
}

8，更新进度条通知

进度条到100%自动消失


function sendLocalNotificationUpdateProgress() {
    cordova.plugins.notification.local.on("update", (notification, eopts) => {
        document.getElementById("barUpdateInfo").innerHTML = "更新成功";
    });
    cordova.plugins.notification.local.update({
        id: 6,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM',
        autoDeletedTime: new Date().getTime()+2000,
        androidProgressBar: {
            name:"下载标题",
            data:{
                title:"下载中",
                fileName:"文件名",
                progressValue:100
            }
        }
    },function(notification){
        console.log(notification);
        document.getElementById("barUpdateInfo").innerHTML = "更新成功";
    });
}

9，删除通知

根据通知的ID删除通知

function deleteLocalNotification() {
    //根据ID，批量删除通知
    cordova.plugins.notification.local.cancel([6]
        ,function(notification){
            document.getElementById("deleteSingleInfo").innerHTML = "清除成功";
        });
}

10，全部清除通知

只能清除自己应用发起的通知，不能清除其他应用的通知，另外也不能清除日历通知

function deleteAllLocalNotification() {
    cordova.plugins.notification.local.cancelAll(function(notification){
        document.getElementById("deleteAllInfo").innerHTML = "清除成功";
    });
}

11，查询通知类型

通知类型：

trigger：实时通知

scheduled：倒计时安排通知，只通知一次

every：定期通知

function getNotificationType() {
    cordova.plugins.notification.local.getType(6
    ,function(info){
        document.getElementById("typeInfo").innerHTML = info;
    });
}

12，查询所有通知

cordova.plugins.notification.local.getIds(function(ids){
    //返回数组
    document.getElementById("idsInfo").innerHTML = ids;
});

13，获取通知对象

根据通知ID数组，返回通知json对象

function getNotificationJson() {
    cordova.plugins.notification.local.get([6,7]
        ,function(info){
            document.getElementById("jsonInfo").innerHTML = JSON.stringify(info);
        });
}

14，打开通知设置窗口

打开系统通知设置窗口，设置通知

function openNotificationWindow() {
    cordova.plugins.notification.local.openNotificationSettings(function(){
        document.getElementById("windowInfo").innerHTML = "打开成功";
    });
}

15，调起日历窗口添加一个通知

trigger：定时通知，弹出日历设置窗口，也可以再自定义配置

at: 在什么时间通知
in: 在最近的时间通知 |Property |Type| value| |---------|----|----| |in |Int | | |unit |String |second, minute, hour, day, week, month, quarter, year|
every： 定期通知

function sendLocalNotificationAtAfter() {
    cordova.plugins.notification.local.schedule({
        id: 6,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM',
        trigger: { at: new Date().getTime()+100000 }
    },function(info) {
        document.getElementById("atInfo").innerHTML = info;
    });
}

16，调起日历窗口添加一个在最近的1个小时内通知

function sendLocalNotificationAfterHour() {
    cordova.plugins.notification.local.schedule({
        id: 6,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM',
        trigger: { in: 1, unit: 'hour' }
    },function(info) {
        document.getElementById("inInfo").innerHTML = info;
    });
}

17，调起日历窗口设置重复通知

每年的10月27号9点钟通知

function sendLocalNotificationRepeat() {
    cordova.plugins.notification.local.schedule({
        id: 7,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM',
        trigger: { every: { month: 10, day: 27, hour: 9, minute: 0 } }
    },function(info) {
        document.getElementById("everyInfo").innerHTML = info;
    });
}

18，调起日历窗口设置重复通知

每月的第一天通知

function sendLocalNotificationRepeatMonth() {
    cordova.plugins.notification.local.schedule({
        id: 9,
        title: 'Design team meeting',
        text: '3:00 - 4:00 PM',
        trigger: { every: 'month', count:1 }
    },function(info) {
        document.getElementById("everyMonthInfo").innerHTML = info;
    });
}

说明：对于定期通知时调用的日历通知，在调起通知时，用户可以根据需要自定义通知时间

许可证

本插件基于 Apache License 开源，详见 LICENSE 文件。

联系方式

OHOS Cordova https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-local-notification

Android/iOS：https://npmjs.com/cordova-plugin-local-notification/issues