{"_id":"@cordova-ohos/cordova-plugin-badge","_rev":"5-9c30d2dac4e0d9fd75ab2db545411447","name":"@cordova-ohos/cordova-plugin-badge","dist-tags":{"latest":"0.8.10"},"versions":{"0.8.9":{"name":"@cordova-ohos/cordova-plugin-badge","version":"0.8.9","keywords":["cordova","badge","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-badge@0.8.9","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-badge/issues"},"dist":{"shasum":"3540f0d5bae55dae923856bcb4a3b6c4d1239e0e","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-badge/-/cordova-plugin-badge-0.8.9.tgz","fileCount":9,"integrity":"sha512-O85MM3IT+fhjdpU518otnEafMXjtYX7OU9pKZQWpCYVJ85nZfx8eAAgoWbhj6lKdTKPCYPCShCEeG1LiJsyjuw==","signatures":[{"sig":"MEUCIFZCutdsgWvHDpFXP+OdpIGedelFfjfOyRMwMywRGOE6AiEAgjjIaOl1WHrKv23Q7ab593bVIQuwLON2Vo3BtW0jAnU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34691},"cordova":{"id":"cordova-plugin-badge","platforms":["ohos"]},"engines":{"cordovaDependencies":{"0.8.9":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"4feff0a7038f816a35c255b7518422c2ad3bb494","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-badge","type":"git"},"_npmVersion":"10.5.1","description":"Cordova File Transfer Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-badge_0.8.9_1773927984858_0.11453758584156426","host":"s3://npm-registry-packages-npm-production"}},"0.8.10":{"name":"@cordova-ohos/cordova-plugin-badge","version":"0.8.10","description":"Cordova Badge Plugin","cordova":{"id":"cordova-plugin-badge","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-badge"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-badge/issues"},"keywords":["cordova","badge","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"0.8.10":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-badge@0.8.10","gitHead":"92674fc1b48613eb50474efe3420ffe102842d45","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-brx0S4iS+ovOo6plPoFdLyS0A+pby4gwoeLx/j2P7yZ18r4L2mZP7uJOtWvXdMUxPrgb19y26UqcTe0Pe36HnQ==","shasum":"41d2ea98cbfc825848702b0d792230ae458af938","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-badge/-/cordova-plugin-badge-0.8.10.tgz","fileCount":10,"unpackedSize":66225,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFfzOOL+VK9Qm5Bu1x40Rw7H6jsaq92H+JDtYk19vQHBAiBzOd7rDfUiq2A2ny1MWdwMZh1SSSYYRPkxMkikK5ZMqg=="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-badge_0.8.10_1785147408284_0.4389530418622303"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T13:46:24.686Z","modified":"2026-07-27T10:16:48.658Z","0.8.9":"2026-03-19T13:46:25.025Z","0.8.10":"2026-07-27T10:16:48.428Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-badge/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","badge","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-badge"},"description":"Cordova Badge Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-badge</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-badge@0.8.9](https://www.npmjs.com/package/cordova-plugin-badge/v/0.8.9) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-badge](#cordova-plugin-badge)\r\n  - [简介](#简介)\r\n  - [核心特性](#核心特性)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [1. 从 npm 安装（推荐）](#1-从-npm-安装推荐)\r\n    - [2. 从 GitCode 安装（开发版本）](#2-从-gitcode-安装开发版本)\r\n    - [3. 安装指定版本](#3-安装指定版本)\r\n    - [4. 离线安装（本地包）](#4-离线安装本地包)\r\n    - [5. 安装后验证](#5-安装后验证)\r\n    - [6. 卸载插件](#6-卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：基础使用（设置/清除角标）](#示例-1基础使用设置清除角标)\r\n    - [示例 2：OpenHarmony 平台特殊说明（不支持接口提示）](#示例-2openharmony-平台特殊说明不支持接口提示)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心使用前提](#1-核心使用前提)\r\n    - [2. 核心 API 说明](#2-核心-api-说明)\r\n    - [3. OpenHarmony 平台注意事项](#3-openharmony-平台注意事项)\r\n    - [4. 调用方式选择](#4-调用方式选择)\r\n  - [常见问题](#常见问题)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [参考资源](#参考资源)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n一个为 Cordova 应用提供应用图标角标（Badge）管理能力的插件，支持 Android、iOS 和 OpenHarmony 三平台，可灵活设置、获取、清除应用角标数值，适配主流移动操作系统特性。\r\n\r\n在移动应用开发中，应用图标角标是重要的消息提醒方式，可直观展示未读消息数、待办事项数等关键信息（如社交应用的未读消息、电商应用的待付款订单等）。该插件通过封装原生平台 API，为开发者提供了统一的角标管理接口，无需深入原生开发即可实现角标的设置、增量更新、获取及清除等功能，同时兼容不同平台的角标显示规则。\r\n\r\n该插件具备以下核心特性：支持固定数值设置与增量调整、自动适配平台角标显示规则、支持角标状态持久化、提供完善的错误处理机制。本文档主要说明在 OpenHarmony 系统中的应用。\r\n\r\n## 核心特性\r\n\r\n- **跨平台统一接口**：一套代码适配 Android、iOS、OpenHarmony 三平台，无需编写平台差异化代码，提供统一的角标管理 API，降低开发成本。\r\n\r\n- **灵活的角标操作**：支持固定数值设置、清除角标，适配 OpenHarmony 平台特性，可满足消息提醒、待办展示等各类业务场景需求。\r\n\r\n- **平台规则自动适配**：自动兼容各平台角标显示规则，尤其是 OpenHarmony 平台，贴合系统角标展示规范，无需手动适配系统差异。\r\n\r\n- **角标状态持久化**：角标数值可持久化保存，应用重启后仍能保留之前设置的角标状态，提升用户体验。\r\n\r\n- **完善的错误处理**：提供完整的错误反馈机制，API 调用失败时可获取具体错误信息，便于问题排查与修复。\r\n\r\n- **双调用方式支持**：所有 API 均支持 Promise 和传统回调函数两种调用方式，适配不同开发者的开发习惯。\r\n\r\n## 支持平台\r\n\r\n- Android 平台：API 21 及以上（Android 5.0+），支持主流品牌机型（华为、小米、OPPO、vivo、三星等），支持角标的设置、清除、增量调整等功能。\r\n\r\n- iOS 平台：11.0 及以上，适配 iOS 系统角标显示规则，支持完整的角标管理功能。\r\n\r\n- OpenHarmony 平台：5.0 及以上，支持应用角标的设置与清除，需与真实通知业务相结合，不直接支持自增、自检等接口。\r\n\r\n## 下载安装\r\n\r\n通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OpenHarmony 平台操作，安装过程自动完成平台配置，快速集成到 Cordova 项目。\r\n\r\n### 1. 从 npm 安装（推荐）\r\n\r\n通过 npm 安装最新稳定版，支持全平台集成，也可单独指定 OpenHarmony 平台安装：\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# Cordova CLI 全平台安装\r\ncordova plugin add cordova-plugin-badge\r\n\r\n# 指定 OpenHarmony 平台安装\r\nhcordova plugin add cordova-plugin-badge --platform ohos\r\n```\r\n\r\n### 2. 从 GitCode 安装（开发版本）\r\n\r\n如需测试最新功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OpenHarmony 平台）：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-badge.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-badge.git@develop --platform ohos\r\n```\r\n\r\n### 3. 安装指定版本\r\n\r\n如需兼容特定 Cordova 或 OpenHarmony 版本，可指定版本号安装：\r\n\r\n```bash\r\nhcordova plugin add cordova-plugin-badge@1.0.0 --platform ohos\r\n```\r\n\r\n### 4. 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-badge）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-badge  --platform ohos\r\n```\r\n### 5. 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n### 6. 卸载插件\r\n\r\n如需移除插件，执行以下命令，支持全平台卸载或仅卸载 OpenHarmony 平台插件：\r\n\r\n```bash\r\n# 全平台卸载\r\ncordova plugin remove cordova-plugin-badge\r\n\r\n# 指定 OpenHarmony 平台卸载\r\nhcordova plugin remove cordova-plugin-badge --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n以下示例均适配 OpenHarmony 平台，涵盖基础设置、清除角标等场景，结合 OpenHarmony 平台特性，可直接复制到项目中使用（需确保 Cordova 环境就绪）。\r\n\r\n### 示例 1：基础使用（设置/清除角标）\r\n\r\n设置角标数值、清除角标，适配消息通知场景，包含回调函数处理操作结果：\r\n\r\n```javascript\r\n// 等待 Cordova 环境完全加载（必须在 deviceready 事件后调用插件）\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\n\r\nfunction onDeviceReady() {\r\n  // 检查插件是否成功加载\r\n  if (window.cordova && window.cordova.plugins && window.plugin?.notification?.badge) {\r\n    // 设置角标（数值为 5，适配 OpenHarmony 平台，需结合真实通知业务）\r\n    function setBadge() {\r\n        plugin.notification.badge.set(5, function(){\r\n            document.getElementById(\"badgeInfo\").innerHTML = \"角标设置成功\";\r\n        });\r\n    }\r\n\r\n    // 清除角标（数值设为 0，OpenHarmony 平台将隐藏角标）\r\n    function clearBadge() {\r\n        plugin.notification.badge.clear(function(){\r\n            document.getElementById(\"badgeInfo\").innerHTML = \"角标清除成功\";\r\n        });\r\n    }\r\n\r\n    // 绑定按钮点击事件，触发角标操作\r\n    document.getElementById(\"setBadgeBtn\").addEventListener(\"click\", setBadge);\r\n    document.getElementById(\"clearBadgeBtn\").addEventListener(\"click\", clearBadge);\r\n  } else {\r\n    console.error(\"插件未加载，请检查安装是否正确\");\r\n  }\r\n}\r\n```\r\n\r\n### 示例 2：OpenHarmony 平台特殊说明（不支持接口提示）\r\n\r\nOpenHarmony 不直接支持自增、自减等角标接口，需结合真实通知业务实现，以下为不支持接口的提示示例：\r\n\r\n```javascript\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\n\r\nfunction onDeviceReady() {\r\n  const badgePlugin = window.plugin?.notification?.badge;\r\n  if (badgePlugin) {\r\n    // OpenHarmony 不支持的接口，调用将触发错误\r\n    try {\r\n      // 不支持：获取角标数值\r\n      badgePlugin.get(function(count) {\r\n        console.log(\"当前角标数值：\", count);\r\n      });\r\n    } catch (error) {\r\n      console.error(\"OpenHarmony 不支持 get 接口：\", error.message);\r\n    }\r\n\r\n    try {\r\n      // 不支持：角标自增\r\n      badgePlugin.increase();\r\n    } catch (error) {\r\n      console.error(\"OpenHarmony 不支持 increase 接口：\", error.message);\r\n    }\r\n\r\n    try {\r\n      // 不支持：角标自减\r\n      badgePlugin.decrease();\r\n    } catch (error) {\r\n      console.error(\"OpenHarmony 不支持 decrease 接口：\", error.message);\r\n    }\r\n\r\n    try {\r\n      // 不支持：检查角标是否支持\r\n      badgePlugin.isSupported(function(supported) {\r\n        console.log(\"角标是否支持：\", supported);\r\n      });\r\n    } catch (error) {\r\n      console.error(\"OpenHarmony 不支持 isSupported 接口：\", error.message);\r\n    }\r\n  } else {\r\n    console.error(\"插件未加载\");\r\n  }\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\n本插件使用流程简洁，核心需遵循“环境就绪→调用 API→处理结果”的逻辑，重点适配 OpenHarmony 平台使用场景，结合使用示例理解更高效。\r\n\r\n### 1. 核心使用前提\r\n\r\n插件所有 API 均需在 Cordova 环境完全就绪后调用，即必须在 `deviceready` 事件触发后执行，否则会出现“插件未加载”“接口未定义”等错误（所有示例均已遵循此前提）。\r\n\r\n### 2. 核心 API 说明\r\n\r\n插件在全局对象 `plugin.notification.badge` 下暴露所有功能接口，支持 Promise 和传统回调两种调用方式，适配 OpenHarmony 平台的核心 API 如下（不支持接口单独说明）：\r\n\r\n| API 方法 | 功能描述 | 说明（OpenHarmony 平台） |\r\n|---|---|---|\r\n| set(count, successCallback) | 设置角标数值 | count：非负整数，数值为 0 时清除角标；successCallback：可选，成功回调（无参数）；需结合真实通知业务使用。 |\r\n| clear(successCallback) | 清除角标 | successCallback：可选，成功回调（无参数）；本质是将角标数值设为 0，OpenHarmony 平台将隐藏角标。 |\r\n| get(callback) | 获取角标数值（不支持） | OpenHarmony 不直接支持该接口，调用将触发错误，需结合通知业务自行维护角标数值。 |\r\n| increase() | 角标自增（不支持） | OpenHarmony 不直接支持该接口，需自行维护角标数值并调用 set 方法实现自增效果。 |\r\n| decrease() | 角标自减（不支持） | OpenHarmony 不直接支持该接口，需自行维护角标数值并调用 set 方法实现自减效果。 |\r\n| isSupported(callback) | 检查角标是否支持（不支持） | OpenHarmony 不直接支持该接口，可通过判断插件是否加载成功间接确认角标功能是否可用。 |\r\n\r\n### 3. OpenHarmony 平台注意事项\r\n\r\n- OpenHarmony 5.0+ 版本均支持插件核心功能（设置、清除角标），无需额外配置系统权限，插件安装后即可调用。\r\n\r\n- OpenHarmony 不直接支持自增（increase）、自减（decrease）、获取（get）、自检（isSupported）接口，需结合真实的通知业务自行维护角标数值，通过 set 方法实现相关效果。\r\n\r\n- 角标设置需与真实通知业务相结合，否则可能出现角标显示异常（如设置后不显示），贴合 OpenHarmony 系统角标管理规范。\r\n\r\n- 角标数值仅支持非负整数，设置为 0 时将清除角标（OpenHarmony 平台将隐藏应用图标上的角标）。\r\n\r\n- 插件支持 Promise 和回调两种调用方式，建议根据项目开发习惯选择，Promise 方式可简化回调逻辑，提升代码可读性。\r\n\r\n### 4. 调用方式选择\r\n\r\n- 回调调用：适合传统开发习惯，通过回调函数处理操作结果，清晰区分成功与失败场景（对应示例 1）。\r\n\r\n- 特殊场景调用：OpenHarmony 平台需避开不支持的接口，通过自行维护角标数值，调用 set 方法实现自增、自减等效果。\r\n\r\n## 常见问题\r\n\r\n- 问题 1：OpenHarmony 平台调用 API 提示“plugin.notification.badge is undefined”？\r\n解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保在 deviceready 事件后调用插件，重新安装插件并重启项目。\r\n\r\n- 问题 2：设置角标后，OpenHarmony 应用图标上不显示角标？\r\n解决：OpenHarmony 角标需结合真实通知业务，确保应用有活跃通知，同时检查角标数值是否为非负整数，重新调用 set 方法重试。\r\n\r\n- 问题 3：调用 increase/decrease 接口提示错误？\r\n解决：OpenHarmony 不直接支持该类接口，需自行维护角标数值（如定义变量记录当前数值），通过 set 方法实现自增、自减效果。\r\n\r\n- 问题 4：清除角标后，角标仍显示？\r\n解决：确保调用 clear 方法，或调用 set(0)，同时检查应用是否有未清除的通知，清除通知后角标将正常隐藏。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-badge/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       ├── cpp/                  # C++ 原生代码\r\n│       │   └── Badge/            # 角标模块\r\n│       │       ├── Badge.cpp     # 应用角标功能的 C++ 实现\r\n│       │       └── Badge.h       # 应用角标功能的头文件\r\n│       └── ets/                  # ArkTS 代码（OpenHarmony API）\r\n│           └── components/       # 组件目录\r\n│               └── PluginAction/ # 插件动作组件\r\n│                   └── SetAppBadge.ets  # 设置应用角标的实现\r\n├── www/                          # Web 资源目录\r\n│   └── badge.js                  # JavaScript 角标接口（Cordova 桥接层）\r\n├── .gitignore                    # Git 忽略文件配置\r\n├── LICENSE                       # 项目开源许可证\r\n├── OAT.xml                       # OpenHarmony 审核配置文件\r\n├── package.json                  # Node.js 包配置\r\n├── plugin.xml                    # Cordova 插件描述文件（核心配置）\r\n└── README.md                     # 项目说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-badge/issues)，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-badge/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 参考资源\r\n\r\n- OpenHarmony 插件仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-badge](https://gitcode.com/CPF-Cordova/cordova-plugin-badge)\r\n\r\n- Android、iOS 插件说明：[https://www.npmjs.com/package/cordova-plugin-badge](https://www.npmjs.com/package/cordova-plugin-badge)\r\n\r\n- Cordova 官方文档：[Cordova Documentation](https://cordova.apache.org/)\r\n\r\n- OpenHarmony 开发文档：[OpenHarmony 官方文档](https://docs.openharmony.cn/)\r\n\r\n## 官方资源\r\n\r\n- OpenHarmony Cordova：[https://gitcode.com/CPF-Cordova/cordova-plugin-badge](https://gitcode.com/CPF-Cordova/cordova-plugin-badge)\r\n\r\n- Android、iOS：[https://www.npmjs.com/package/cordova-plugin-badge](https://www.npmjs.com/package/cordova-plugin-badge)","readmeFilename":"README.md"}