@capacitor/push-notifications

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/push-notifications 是 capacitor 生态系统中的核心插件，用于处理应用的推送通知功能，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境，本文档主要说明在 OpenHarmony 系统中的使用。

该插件支持注册推送通知、获取推送令牌、监听注册事件等功能，帮助开发者快速集成推送通知能力到跨平台应用中。

前置条件

1. 访问华为开发者联盟网站
2. 创建新应用或选择现有应用
3. 启用 Push Kit（推送服务）
4. 根据文档配置开通相关平台推送服务

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/push-notifications

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/push-notifications

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
   "pkg": "@capacitor/push-notifications",
   "classpath": "PushNotifications"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(PushNotifications)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  PushNotifications
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中 src/main/cpp/PushNotifications 目录下 PushNotifications.h、PushNotifications.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/PushNotifications 目录下。

将源码中 src/main/ets/components/PushNotifications 目录下 PushNotifications.ets 文件引入到 capacitor 模块中 src/main/ets/components/PushNotifications 目录下。

4. 添加 ArkTS 配置

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

// ...
"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/PushNotifications/PushNotifications.ets"
        // ...
      ]
    }
  }
}
// ...

卸载

# 卸载 push-notifications 插件
hionic plugin remove @capacitor/push-notifications

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

使用示例

基础示例：权限校验、授权、注册、监听注册、注销

import { PushNotifications } from '@capacitor/push-notifications';

// 添加推送事件监听器
const addListeners = async () => {
  await PushNotifications.addListener('registration', token => {
    console.info('Registration token: ', token.value);
  });

  await PushNotifications.addListener('registrationError', err => {
    console.error('Registration error: ', err.error);
  });
}

// 注册推送通知
const registerNotifications = async () => {
  let permStatus = await PushNotifications.checkPermissions();

  if (permStatus.receive === 'denied') {
    permStatus = await PushNotifications.requestPermissions();
  }

  if (permStatus.receive !== 'granted') {
    throw new Error('User denied permissions!');
  }

  await PushNotifications.register();
}

// 注销推送通知
await PushNotifications.unregister();

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ---- | ---- | ---- | | register() | Promise<void> | 注册应用以接收推送通知，会触发 registration 或 registrationError 事件 | | unregister() | Promise<void> | 取消注册应用的推送通知 | | getDeliveredNotifications() | Promise<DeliveredNotifications> | 获取通知屏幕上可见的通知列表，暂不支持 | | removeDeliveredNotifications(delivered: DeliveredNotifications) | Promise<void> | 从通知屏幕上移除指定的通知，暂不支持 | | removeAllDeliveredNotifications() | Promise<void> | 从通知屏幕上移除所有通知，暂不支持 | | createChannel(channel: Channel) | Promise<void> | 创建通知渠道，暂不支持 | | deleteChannel(args: { id: string }) | Promise<void> | 删除通知渠道，暂不支持 | | listChannels() | Promise<ListChannelsResult> | 列出可用的通知渠道，暂不支持 | | checkPermissions() | Promise<PermissionStatus> | 检查接收推送通知的权限状态 | | requestPermissions() | Promise<PermissionStatus> | 请求接收推送通知的权限 | | addListener('registration', listenerFunc) | Promise<PluginListenerHandle> | 监听推送通知注册成功事件，获取推送令牌 | | addListener('registrationError', listenerFunc) | Promise<PluginListenerHandle> | 监听推送通知注册失败事件，获取错误信息 | | addListener('pushNotificationReceived', listenerFunc) | Promise<PluginListenerHandle> | 监听设备接收到推送通知的事件，暂不支持 | | addListener('pushNotificationActionPerformed', listenerFunc) | Promise<PluginListenerHandle> | 监听用户对推送通知执行操作的事件，暂不支持 | | removeAllListeners() | Promise<void> | 移除该插件的所有原生监听器 |

数据结构

PermissionStatus

| 属性 | 类型 | 描述 | | --- | --- | --- | | receive | PermissionState | 接收通知的权限状态 |

Token

| 属性 | 类型 | 描述 | | --- | --- | --- | | value | string | 在 OpenHarmony 系统上 Push Token 令牌 |

RegistrationError

| 属性 | 类型 | 描述 | | --- | --- | --- | | error | string | 描述注册失败的错误信息 |

DeliveredNotifications

| 属性 | 类型 | 描述 | | --- | --- | --- | | notifications | PushNotificationSchema[] | 通知屏幕上可见的通知列表 |

Channel

| 属性 | 类型 | 描述 | | --- | --- | --- | | id | string | 渠道标识符 | | name | string | 渠道的人类友好名称 | | description | string | 渠道的描述 | | sound | string | 为发布到此渠道的通知播放的声音 | | importance | Importance | 发布到此渠道的通知的中断级别 | | visibility | Visibility | 发布到此渠道的通知的可见性 | | lights | boolean | 发布到此渠道的通知是否应显示通知灯 | | lightColor | string | 发布到此渠道的通知的灯光颜色 | | vibration | boolean | 发布到此渠道的通知是否应振动 |

ListChannelsResult

| 属性 | 类型 | 描述 | | --- | --- | --- | | channels | Channel[] | 应用创建的所有渠道的列表 |

PushNotificationSchema

| 属性 | 类型 | 描述 | | --- | --- | --- | | title | string | 通知标题 | | subtitle | string | 通知副标题 | | body | string | 通知的主要文本负载 | | id | string | 通知标识符 | | tag | string | 通知标签 | | badge | number | 应用图标徽章显示的数字 | | data | string | 包含在推送通知负载中的数据 | | click_action | string | 用户打开通知时要执行的操作 | | link | string | 通知中的深层链接 | | group | string | 用于通知分组的组标识符 | | groupSummary | boolean | 指定此通知作为关联 group 的摘要 |

ActionPerformed

| 属性 | 类型 | 描述 | | --- | --- | --- | | actionId | string | 对通知执行的操作 | | inputValue | string | 在通知操作上输入的文本 | | notification | PushNotificationSchema | 执行操作的通知 |

Importance

| 值 | 描述 | | --- | --- | | 1 | 最低 - 无声音，无弹出 | | 2 | 低 - 无声音，无弹出 | | 3 | 默认 - 有声音，无弹出 | | 4 | 高 - 有声音，有弹出 | | 5 | 最高 - 有声音，有弹出，屏幕锁定时显示 |

Visibility

| 值 | 描述 | | --- | --- | | -1 | 秘密 - 通知不会显示在锁定屏幕上 | | 0 | 私有 - 通知会显示在锁定屏幕上，但敏感内容会被隐藏 | | 1 | 公共 - 通知会完整显示在锁定屏幕上 |

遗留问题

以下功能对标源库暂未实现：

• getDeliveredNotifications - 获取已投递通知列表
• removeDeliveredNotifications - 移除指定通知
• removeAllDeliveredNotifications - 移除所有通知
• createChannel - 创建通知渠道
• deleteChannel - 删除通知渠道
• listChannels - 列出通知渠道
• pushNotificationReceived - 推送通知接收事件
• pushNotificationActionPerformed - 推送通知点击操作事件

原因：OpenHarmony 推送服务架构差异，相关功能需要平台进一步支持后方可实现。

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- PushNotifications   # 插件核心 C++ 实现
|                             |---- PushNotifications.cpp
|                             |---- PushNotifications.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- PushNotifications   # ArkTS 组件实现
|                                   |---- PushNotifications.ets
|     |---- README.md                  # 说明文档
|     |---- package.json               # npm 配置文件
|     |---- plugin.xml                 # capacitor 插件配置
|     |---- LICENSE                    # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

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