{"_id":"@cordova-ohos/cordova-plugin-backbutton","_rev":"5-976dc2cf45c5d67c5b89806653f96f6e","name":"@cordova-ohos/cordova-plugin-backbutton","dist-tags":{"latest":"0.3.1"},"versions":{"0.3.0":{"name":"@cordova-ohos/cordova-plugin-backbutton","version":"0.3.0","keywords":["cordova","backbutton","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-backbutton@0.3.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-backbutton/issues"},"dist":{"shasum":"bd30c1a7bc8491154fb15c08e87453d615367897","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-backbutton/-/cordova-plugin-backbutton-0.3.0.tgz","fileCount":9,"integrity":"sha512-7qukiFWd8P0Xgd8YtpZHkImjHYDwPGrS/SPlMt5/NdqiF7nSRLr/PoCmm9Hj6pFdCsS5Xtb8+TMu1ajYulOSuw==","signatures":[{"sig":"MEUCIQCWm7FUknVQIbpoXPKQYwRGhVJcepmZdvaz2flrOzDfuAIgKtFCy97E9Qk2qt7DyDtES+FY90DMjGPuovdmQ43Ora0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28588},"cordova":{"id":"cordova-plugin-backbutton","platforms":["ohos"]},"engines":{"cordovaDependencies":{"0.3.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"427b50b12334080b7c337dce74cc11bb5a314707","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-backbutton","type":"git"},"_npmVersion":"10.5.1","description":"Cordova Backbutton Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-backbutton_0.3.0_1773927861092_0.5881451860071578","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@cordova-ohos/cordova-plugin-backbutton","version":"0.3.1","description":"Cordova Backbutton Plugin","cordova":{"id":"cordova-plugin-backbutton","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-backbutton"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton/issues"},"keywords":["cordova","backbutton","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"0.3.1":{"@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-backbutton@0.3.1","gitHead":"fb8f276cdc4af32690a7299d0fd07a0f88733020","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-3D6xAdvuOo3UbPUdIEN+5E8MMAHiXCgjsMK+aR9xMU9Rf3ikZKbmFoo58LdkuXYdm7IoJFmDxgmi7cQB2efv/w==","shasum":"d207972c37e1b524e22683304a8a44040e2c83f6","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-backbutton/-/cordova-plugin-backbutton-0.3.1.tgz","fileCount":10,"unpackedSize":50347,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA/pF4ha8z8Isc6/VhAs8/FQpZvfz5JqkQ5jH7RIqQELAiAQlV6Gqx7mAKc7BWyU2BtJtCdOL69Pq459o6///xXRSg=="}]},"_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-backbutton_0.3.1_1785148319024_0.20358186084650498"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T13:44:20.979Z","modified":"2026-07-27T10:31:59.423Z","0.3.0":"2026-03-19T13:44:21.245Z","0.3.1":"2026-07-27T10:31:59.224Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","backbutton","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-backbutton"},"description":"Cordova Backbutton 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-backbutton</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-backbutton@0.3.0](https://npmjs.com/package/cordova-plugin-backbutton/v/0.3.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-backbutton](#cordova-plugin-backbutton)\r\n  - [简介](#简介)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [1. 常用安装（推荐）](#1-常用安装推荐)\r\n    - [2. 从 GitCode 安装（开发版本）](#2-从-gitcode-安装开发版本)\r\n    - [3. 离线安装（本地包）](#3-离线安装本地包)\r\n    - [4. 安装后验证](#4-安装后验证)\r\n    - [5. 卸载插件](#5-卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：基础用法（返回桌面/返回上一页）](#示例-1基础用法返回桌面返回上一页)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心使用前提](#1-核心使用前提)\r\n    - [2. 核心 API 说明](#2-核心-api-说明)\r\n    - [3. OHOS 平台注意事项](#3-ohos-平台注意事项)\r\n    - [4. 调用方式选择](#4-调用方式选择)\r\n  - [常见问题](#常见问题)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [参考资源](#参考资源)\r\n  - [官方资源](#官方资源)\r\n\r\n## 简介\r\n\r\n一个为 Apache Cordova 应用提供**灵活、可扩展**的硬件返回按钮事件处理插件，解决原生 `backbutton` 事件的优先级混乱、拦截不便等问题。本文档主要说明在 OHOS 系统中的应用，帮助开发者高效处理硬件返回按钮相关业务逻辑，提升应用交互体验。\r\n\r\n## 支持平台\r\n\r\n- Android 平台：适配主流 Android 版本，支持硬件返回按钮事件的监听、拦截与自定义处理。\r\n\r\n- iOS 平台：无硬件返回键，插件可安全安装，不影响应用打包与运行，无需额外适配。\r\n\r\n- OHOS 平台：适配 OHOS 5.0+ 系统，支持硬件返回按钮事件的监听、拦截，贴合 OHOS 应用交互规范，灵活控制返回行为。\r\n\r\n## 下载安装\r\n\r\n通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OHOS 平台操作，安装过程自动完成平台配置，快速集成到 Cordova 项目。\r\n\r\n### 1. 常用安装（推荐）\r\n\r\n通过 hcordova 命令安装最新稳定版，支持全平台集成，也可单独指定 OHOS 平台安装：\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装\r\nhcordova plugin add cordova-plugin-backbutton\r\n\r\n# 指定 OHOS 平台安装\r\nhcordova plugin add cordova-plugin-backbutton --platform ohos\r\n\r\n# 指定版本安装\r\nhcordova plugin add cordova-plugin-backbutton@1.0.0 --platform ohos\r\n```\r\n\r\n### 2. 从 GitCode 安装（开发版本）\r\n\r\n如需测试最新功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OHOS 平台）：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton.git@develop --platform ohos\r\n```\r\n\r\n### 3. 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-backbutton）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-backbutton --platform ohos\r\n```\r\n\r\n### 4. 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 5. 卸载插件\r\n\r\n如需移除插件，执行以下命令，支持全平台卸载或仅卸载 OHOS 平台插件：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-backbutton\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-backbutton --platform ohos\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以下示例均适配 OHOS 平台，涵盖基础用法、事件拦截、优先级设置等场景，可直接复制到项目中使用（需确保 Cordova 环境就绪）。\r\n\r\n### 示例 1：基础用法（返回桌面/返回上一页）\r\n\r\n实现硬件返回按钮触发返回桌面或返回上一页功能，包含成功与失败回调，适配 OHOS 平台交互逻辑：\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 && navigator.Backbutton) {\r\n    // 返回桌面（OHOS 平台适配，最小化应用到后台）\r\n    function setAppGoHome() {\r\n        navigator.Backbutton.goHome(\r\n            function() {\r\n                console.log('返回桌面成功');\r\n            }, \r\n            function() {\r\n                console.log('返回桌面失败');\r\n            }\r\n        );\r\n    }\r\n\r\n    // 返回上一页（适配 OHOS 应用页面导航逻辑）\r\n    function setAppGoBack() {\r\n        navigator.Backbutton.goBack(\r\n            function() {\r\n                console.log('返回上一页成功');\r\n            }, \r\n            function() {\r\n                console.log('返回上一页失败');\r\n            }\r\n        );\r\n    }\r\n  } else {\r\n    console.error(\"插件未加载，请检查安装是否正确\");\r\n  }\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\n本插件使用流程简洁，结合使用示例理解更高效。\r\n\r\n### 1. 核心使用前提\r\n\r\n插件所有 API 均需在 Cordova 环境完全就绪后调用，即必须在 `deviceready` 事件触发后执行，否则会出现“插件未加载”“接口未定义”等错误（所有示例均已遵循此前提）。\r\n\r\n### 2. 核心 API 说明\r\n\r\n插件在全局对象 `navigator.Backbutton` 下暴露核心方法，支持事件绑定、解绑、返回操作等，适配 OHOS 平台的核心 API 如下：\r\n\r\n| API 方法 | 功能描述 | 说明（OHOS 平台） |\r\n|---|---|---|\r\n| goHome(success, error) | 返回桌面（最小化应用） | success：成功回调（无参数）；error：失败回调（参数为错误对象，含 message 属性），OHOS 平台下实现应用最小化到后台。 |\r\n| goBack(success, error) | 返回上一页 | success：成功回调（无参数）；error：失败回调（参数为错误对象），适配 OHOS 应用页面导航逻辑，返回上一级页面。 |\r\n\r\n### 3. OHOS 平台注意事项\r\n\r\n- OHOS 平台 5.0+ 版本均支持插件功能，无需额外配置系统权限，插件安装后即可直接调用所有 API，无需手动声明权限。\r\n\r\n- `goHome` 方法在 OHOS 平台下实现应用最小化到后台，而非关闭应用，贴合 OHOS 应用生命周期管理规范，再次打开应用可恢复之前状态。\r\n\r\n\r\n### 4. 调用方式选择\r\n\r\n- 适合简单场景（如直接返回上一页、返回桌面），调用 `goBack`/`goHome` 方法，搭配成功/失败回调（对应示例 1）。\r\n\r\n## 常见问题\r\n\r\n- 问题 1：OHOS 平台调用 API 提示“navigator.Backbutton is undefined”？\r\n解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保在 deviceready 事件后调用插件，重新安装插件并重启项目。\r\n\r\n- 问题 2：硬件返回按钮触发后，无法阻断默认行为？\r\n解决：确保回调函数返回 `true`，只有返回 true 才能阻断事件冒泡；检查是否有更高优先级的回调函数未阻断事件。\r\n\r\n- 问题 3：goHome 方法调用后，应用直接关闭而非最小化？\r\n解决：OHOS 平台下 `goHome` 方法默认实现最小化，若出现关闭应用，检查 OHOS 应用配置是否正确，或重新安装插件重试。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-backbutton/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       ├── cpp/                  # C++ 原生代码\r\n│       │   └── AppMin/           # 返回键模块\r\n│       │       ├── BackbuttonPlugin.cpp  # 返回键监听功能的 C++ 实现\r\n│       │       └── BackbuttonPlugin.h    # 返回键监听功能的头文件\r\n│       └── ets/                  # ArkTS 代码（OpenHarmony API）\r\n│           └── components/       # 组件目录\r\n│               └── PluginAction/ # 插件动作组件\r\n│                   └── AppMinimize.ets  # 应用最小化的实现\r\n├── www/                          # Web 资源目录\r\n│   └── JS Backbutton.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-backbutton/issues)，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件（cordova-plugin-backbutton）基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 参考资源\r\n\r\n- OHOS 插件仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton](https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton)\r\n\r\n- Android、iOS 插件说明：[https://npmjs.com/cordova-plugin-backbutton](https://npmjs.com/cordova-plugin-backbutton)\r\n\r\n- Cordova 官方文档：[Cordova Documentation](https://cordova.apache.org)\r\n\r\n- OHOS 开发文档：[OpenHarmony 官方文档](https://docs.openharmony.cn/)\r\n\r\n## 官方资源\r\n\r\n- OpenHarmony Cordova：[https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton](https://gitcode.com/CPF-Cordova/cordova-plugin-backbutton)\r\n\r\n- Android/iOS：[https://npmjs.com/cordova-plugin-backbutton/issues](https://npmjs.com/cordova-plugin-backbutton/issues)\r\n","readmeFilename":"README.md"}