{"_id":"@cordova-ohos/cordova-plugin-appminimize","_rev":"5-86bf236c4594aaa94068ddc3139ba93d","name":"@cordova-ohos/cordova-plugin-appminimize","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@cordova-ohos/cordova-plugin-appminimize","version":"1.0.1","keywords":["cordova","appminimize","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-appminimize@1.0.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-appminimize/issues"},"dist":{"shasum":"90dc4f7f37400b26a509bb8e6e4c7a645fc357be","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-appminimize/-/cordova-plugin-appminimize-1.0.1.tgz","fileCount":9,"integrity":"sha512-xA5UV2jFQkgade4P1qLUQNB94b+HTscoTAuaCAeS1VHwswSW0lw+v1xkCDq8431t7SoombY1swIcN6WolrZr8Q==","signatures":[{"sig":"MEYCIQCnWMySheTvYok7hc+WXah7FXv8PmtsJTd+yuChbbO3EgIhANWHTems3Wb/E1QxNlyRAtep3mwzDEFZFDnEQwt8tEUp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30118},"cordova":{"id":"cordova-plugin-appminimize","platforms":["ohos"]},"engines":{"cordovaDependencies":{"1.0.1":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"5b7522a645c1d8077680e717e6a0e813412d5398","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-appminimize","type":"git"},"_npmVersion":"10.5.1","description":"Cordova File Transfer Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-appminimize_1.0.1_1773927614071_0.15565425105338315","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@cordova-ohos/cordova-plugin-appminimize","version":"1.0.2","description":"This is a cordova plugin to minimize the application in OHOS devices.","cordova":{"id":"cordova-plugin-appminimize","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-appminimize"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize/issues"},"keywords":["cordova","appminimize","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"1.0.2":{"@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-appminimize@1.0.2","gitHead":"bdd33904c84516ee37820dde6d9c67280dfcff7e","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-6acDDbGxauMs8PexYMUsgsZKjdA2HTuPWVbpTzfSyNNUFoRFTnXPSvWBYn75zKHOw/iUm9lTdybsXryvm7PCSw==","shasum":"d5a81a2027a80be8f8d80efacc18298dc4c1a1d5","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-appminimize/-/cordova-plugin-appminimize-1.0.2.tgz","fileCount":10,"unpackedSize":56261,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCea7q3lkPBgpg/5a4Pcmsp4Y4t9hJUWULikuCYBFgnWgIgPwerI61n9scKoApOQidRPGm/Bwqd1gja0dgmTsmuiJw="}]},"_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-appminimize_1.0.2_1785148015482_0.3838645413214812"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T13:40:13.971Z","modified":"2026-07-27T10:26:55.865Z","1.0.1":"2026-03-19T13:40:14.205Z","1.0.2":"2026-07-27T10:26:55.630Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","appminimize","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-appminimize"},"description":"This is a cordova plugin to minimize the application in OHOS devices.","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-appminimize</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-appminimize@1.0.1](https://npmjs.com/package/cordova-plugin-appminimize/v/1.0.1) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-appminimize](#cordova-plugin-appminimize)\r\n  - [简介](#简介)\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    - [6. 卸载插件](#6-卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：基础应用最小化（Cordova 原生应用）](#示例-1基础应用最小化cordova-原生应用)\r\n    - [示例 2：带回调的应用最小化（获取执行状态）](#示例-2带回调的应用最小化获取执行状态)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心使用前提](#1-核心使用前提)\r\n    - [2. 核心 API 说明](#2-核心-api-说明)\r\n      - [方法签名](#方法签名)\r\n      - [参数说明](#参数说明)\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一个为 Cordova 应用提供应用最小化（App Minimize）功能的轻量级插件，支持 Android、iOS 和 OHOS 平台，可实现将当前应用快速最小化到后台运行的核心能力，适配主流移动操作系统的应用生命周期管理特性。本文档主要说明在 OHOS 系统中的应用。\r\n\r\n在移动应用开发中，应用最小化功能是提升用户体验的重要补充，常用于临时退出应用（如查看三方应用信息后返回）、后台执行任务（如下载、播放音频）、快捷切换场景（如扫码后返回原应用）等场景。该插件通过封装原生平台的应用管理 API，为开发者提供了统一的跨平台接口，无需深入原生开发即可实现应用最小化操作，同时处理了不同平台应用生命周期的兼容性问题。\r\n\r\n该插件具备以下核心特性：支持三平台（Android/iOS/OHOS）统一调用、轻量级无冗余依赖、提供同步调用方式、适配平台应用后台运行机制、完善的错误处理与状态反馈、支持 Ionic 等主流 Cordova 衍生框架。\r\n\r\n## 核心特性\r\n\r\n- **跨平台一致性**：一套代码适配 Android、iOS、OHOS 三平台，无需编写平台专属逻辑，保持 API 调用统一，适配各平台应用生命周期管理规范。\r\n\r\n- **轻量无依赖**：插件体积小巧，无额外第三方冗余依赖，不增加应用包体积负担，不影响 OHOS 应用运行性能。\r\n\r\n- **同步调用**：支持同步调用方式，确保调用结果即时反馈，提升开发效率与用户体验。\r\n\r\n- **平台适配性强**：深度适配各平台应用后台运行机制，妥善处理应用最小化后的生命周期状态，尤其贴合 OHOS 平台应用管理规范。\r\n\r\n- **错误处理完善**：提供完整的错误反馈机制，调用失败时可通过回调获取具体错误信息，便于问题排查与修复。\r\n\r\n- **框架兼容**：支持 Ionic 等主流 Cordova 衍生框架，适配各类 Cordova 项目开发需求。\r\n\r\n## 支持平台\r\n\r\n- Android 平台：API 16 及以上（Android 4.1+），覆盖 99% 以上 Android 设备，支持应用最小化到后台功能。\r\n\r\n- iOS 平台：9.0 及以上，适配 iOS 主流版本及最新机型，支持应用后台最小化。\r\n\r\n- OHOS 平台：5.0+，适配 OHOS 系统应用，支持应用最小化到后台，贴合 OHOS 应用生命周期管理要求。\r\n\r\n## 下载安装\r\n\r\n通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OHOS 平台操作，安装过程自动完成平台配置。\r\n\r\n### 1. 常用安装\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# Cordova CLI 全平台安装\r\nhcordova plugin add cordova-plugin-appminimize\r\n\r\n# 指定 OHOS 平台安装\r\nhcordova plugin add cordova-plugin-appminimize --platform ohos\r\n```\r\n\r\n### 2. 从 GitCode 安装（开发版本）\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize.git@develop --platform ohos\r\n```\r\n\r\n### 3. 安装指定版本\r\n\r\n```bash\r\nhcordova plugin add cordova-plugin-appminimize@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-appminimize）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-appminimize  --platform ohos\r\n```\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### 6. 卸载插件\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-appminimize\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-appminimize --platform ohos\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：基础应用最小化（Cordova 原生应用）\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.plugins && window.plugins.appMinimize) {\r\n    // 基础用法：直接最小化应用（无回调，简洁高效）\r\n    window.plugins.appMinimize.minimize();\r\n  } else {\r\n    console.error(\"插件未加载，请检查安装是否正确\");\r\n  }\r\n}\r\n```\r\n\r\n### 示例 2：带回调的应用最小化（获取执行状态）\r\n\r\n通过回调函数获取最小化操作的执行状态，便于处理成功或失败场景（如最小化失败时提示用户）。\r\n\r\n```javascript\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\n\r\nfunction onDeviceReady() {\r\n  const appMinimize = window.plugins.appMinimize;\r\n  if (appMinimize) {\r\n    // 带回调的调用方式，获取执行状态\r\n    appMinimize.minimize(\r\n      () => {\r\n        // 成功回调：最小化操作完成\r\n        console.log(\"应用已成功最小化到后台\");\r\n      },\r\n      (error) => {\r\n        // 失败回调：输出错误信息\r\n        console.error(\"应用最小化失败：\", error.message);\r\n        alert(`最小化失败，请重试：${error.message}`);\r\n      }\r\n    );\r\n  } else {\r\n    console.error(\"AppMinimize 插件未加载\");\r\n  }\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\n本插件使用流程简洁，核心需遵循“环境就绪→调用 API→处理结果”的逻辑，重点适配 OHOS 平台使用场景，结合使用示例理解更高效。\r\n\r\n### 1. 核心使用前提\r\n\r\n插件所有 API 均需在 Cordova 环境完全就绪后调用，即必须在 `deviceready` 事件触发后执行，否则会出现“插件未初始化”“接口未定义”等错误（所有示例均已遵循此前提）。\r\n\r\n### 2. 核心 API 说明\r\n\r\n插件在全局对象 `window.plugins.appMinimize` 下暴露核心功能接口，核心方法为 `minimize(successCallback, errorCallback)`，支持同步调用，确保即时反馈。\r\n\r\n#### 方法签名\r\n\r\n```javascript\r\n// 带回调的调用方式（用于获取执行状态）\r\nwindow.plugins.appMinimize.minimize(successCallback, errorCallback)\r\n```\r\n\r\n#### 参数说明\r\n\r\n| 参数名 | 类型 | 说明 |\r\n|---|---|---|\r\n| successCallback | Function | 可选，执行成功回调，无参数，仅当应用最小化操作完成后触发，可用于提示用户操作结果。 |\r\n| errorCallback | Function | 可选，执行失败回调，参数为错误对象（含 message 属性），描述最小化失败原因（如权限不足、平台不支持等），便于问题排查。 |\r\n\r\n### 3. OHOS 平台注意事项\r\n\r\n- OHOS 平台 5.0+ 版本均支持插件功能，无需额外配置系统权限，插件安装后即可直接调用。\r\n\r\n- 应用最小化后，会保持当前运行状态（如页面数据、临时变量），再次打开应用时恢复至最小化前的界面，贴合 OHOS 应用后台管理机制。\r\n\r\n- 若调用最小化接口失败，可检查 OHOS 应用是否处于前台运行状态（后台应用无法执行最小化操作），或检查插件安装是否正确。\r\n\r\n- 支持 Ionic 等 Cordova 衍生框架，调用方式与原生 Cordova 项目一致，无需额外适配。\r\n\r\n### 4. 调用方式选择\r\n\r\n- 无回调调用：适合无需关注执行状态的场景，代码简洁，直接执行最小化操作（对应示例 1）。\r\n\r\n- 带回调调用：适合需要处理执行结果的场景（如最小化失败提示、日志上报），通过回调获取操作状态（对应示例 2）。\r\n\r\n## 常见问题\r\n\r\n- 问题 1：OHOS 平台调用最小化接口失败，提示“插件未加载”？\r\n解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保在 deviceready 事件后调用接口，重新安装插件并重启项目。\r\n\r\n- 问题 2：应用最小化后，再次打开无法恢复之前的页面状态？\r\n解决：OHOS 平台默认保持应用后台运行状态，若出现状态丢失，可检查应用是否配置了后台保活权限，或确认插件版本与 OHOS 系统版本兼容。\r\n\r\n- 问题 3：iOS/Android 平台调用正常，OHOS 平台调用无响应？\r\n解决：确保安装插件时指定了 --platform ohos 参数，检查 OHOS 系统版本是否为 5.0+，重新构建项目后重试。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-appminimize/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       ├── cpp/                  # C++ 原生代码\r\n│       │   └── AppMin/           # 应用最小化模块\r\n│       │       ├── AppMinimize.cpp  # 应用最小化功能的 C++ 实现\r\n│       │       └── AppMinimize.h    # 应用最小化功能的头文件\r\n│       └── ets/                  # ArkTS 代码（OpenHarmony API）\r\n│           └── components/       # 组件目录\r\n│               └── PluginAction/ # 插件动作组件\r\n│                   └── AppMinimize.ets  # 应用最小化的实现\r\n├── www/                          # Web 资源目录（与 src 平级）\r\n│   └── JS AppMinimize.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-appminimize/issues)，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件（cordova-plugin-appminimize）基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 参考资源\r\n\r\n- OHOS 插件仓库：[CPF-Cordova/cordova-plugin-appminimize](https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize)\r\n\r\n- Android、iOS 插件说明：[cordova-plugin-appminimize 官方指南](https://npmjs.com/cordova-plugin-appminimize)\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- OHOS Cordova：[https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize](https://gitcode.com/CPF-Cordova/cordova-plugin-appminimize)\r\n\r\n- Android/iOS：[https://npmjs.com/cordova-plugin-appminimize/issues](https://npmjs.com/cordova-plugin-appminimize)\r\n","readmeFilename":"README.md"}