{"_id":"@capacitortest/capacitor-app","name":"@capacitortest/capacitor-app","dist-tags":{"latest":"8.0.0"},"versions":{"8.0.0":{"name":"@capacitortest/capacitor-app","version":"8.0.0","description":"The App API handles high level App state and events. For example, this API emits events when the app enters and leaves the foreground, handles deeplinks, opens other apps, and manages persisted plugin state.","capacitor":{"id":"@capacitor/app","platforms":["openHarmony"]},"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-app"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-app/issues"},"keywords":["capacitor","plugin","native"],"engines":{"capacitorDependencies":{"1.0.0":{"capacitor-openharmony":"8.0.0","hionic":">=1.0.0"}}},"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","gitHead":"d77b37ab911464323df7cc81311211020e7069ca","_id":"@capacitortest/capacitor-app@8.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-i4QxAajZMPjV613WrQxCgoZ+bd0nv+RMfoWfACsK1nxy2b4U6+v+uHW3+dGx/zhrhe9z6tfWp1eRRhfuL3lP9w==","shasum":"35d3d0a06f0e7b9b0955a7ece652b577a11b02b2","tarball":"https://registry.npmjs.org/@capacitortest/capacitor-app/-/capacitor-app-8.0.0.tgz","fileCount":9,"unpackedSize":41659,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBx0K3Cok4xEjVYAGKtXaGAL1Rcl3o4Ysk460HBCW/EBAiEAgvpHz8mYQ28s+iGFzG8ojsjtLGptjgjU90ojw3xUGpE="}]},"_npmUser":{"name":"ww42012315","email":"1203124007@qq.com"},"directories":{},"maintainers":[{"name":"ww42012315","email":"1203124007@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/capacitor-app_8.0.0_1770541575648_0.6585359153605945"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-08T09:06:15.463Z","8.0.0":"2026-02-08T09:06:15.785Z","modified":"2026-02-08T09:06:16.133Z"},"maintainers":[{"name":"ww42012315","email":"1203124007@qq.com"}],"description":"The App API handles high level App state and events. For example, this API emits events when the app enters and leaves the foreground, handles deeplinks, opens other apps, and manages persisted plugin state.","keywords":["capacitor","plugin","native"],"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-app"},"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-app/issues"},"license":"MIT","readme":"# `@capacitor/app@8.0.0`\r\n\r\n`@capacitor/app` 是Capacitor生态系统中的核心插件，App的API提供了处理高级应用状态与事件的功能。为跨平台应用开发提供设备差异化适配能力，本文档仅说明在OpenHarmony环境下的使用情况。\r\n\r\n\r\n\r\n## 插件简介\r\n\r\n`@capacitor/app` 提供了高层级的应用状态与事件如pause、resume等\r\n\r\n\r\n## 安装指南\r\n\r\n### 方式一:手动引入安装\r\n\r\n根据插件源码中 `plugin.xml` 配置在项目中添加/修改相关配置\r\n\r\n1. 根据`plugin.xml`的`config-json`项，找到`entry`模块中`capacitor.plugins.json`文件，并根据`param`标签添加配置。\r\n   ```\r\n   [\r\n     {\r\n       \"pkg\": \"@capacitor/app\",\r\n       \"classpath\": \"App\"\r\n     }\r\n   ]\r\n   ```\r\n2. 根据`plugin.xml`的`CMakeLists`项，找到`capacitor`模块，路径为`target`字段的文件`CMakeLists.txt`，添加`add_subdirectory`，同时添加`target_link_libraries`。\r\n   ```\r\n   add_subdirectory(App)\r\n   \r\n   // ...\r\n   注意需添加在-Wl,--whole-archive 和 -Wl,--no-whole-archive之间\r\n   target_link_libraries(capacitor PUBLIC\r\n   // ...\r\n      \"-Wl,--whole-archive\"\r\n      App\r\n      \"-Wl,--no-whole-archive\"\r\n   // ...\r\n   )\r\n   ```\r\n3. 根据`plugin.xml`的`source-file`项，将`src`字段的路径代码复制到`capacitor`模块中`target-dir`字段的目录中。\r\n   ```\r\n   将源码中src/main/cpp/App目录下的App.h、App.cpp、CMakeLists.txt文件文件引入到capacitor模块中src/main/cpp/App目录下\r\n   将源码中src/main/ets/components/App目录下的App.ets文件引入到capacitor模块中src/main/ets/components/App目录下\r\n   ```\r\n4. 在`capacitor`模块的`build-profile.json5`文件中，`buildOption/arkOptions/runtimeOnly/sources`配置项数组中加入步骤3中拷贝的ets文件路径:\r\n   ```\r\n    \"buildOption\": {\r\n      // ...\r\n      \"arkOptions\": {\r\n      \"runtimeOnly\":[\r\n      // ...\r\n      \"./src/main/ets/components/App/App.ets\"\r\n      // ...\r\n       ]\r\n     }\r\n    }\r\n   ```\r\n\r\n### 方式二:通过 HCapacitor CLI 安装\r\n待后续开源，该方式会取代方式一\r\n在 Capacitor 项目根目录执行以下命令，自动下载并集成插件：\r\n\r\n```\r\n安装hcionic\r\nnpm install -g hionic\r\n```\r\n\r\n\r\n```\r\n安装最新稳定版\r\n\r\nhionic plugin add @capacitor/app\r\n\r\n指定平台安装\r\n\r\nhionic plugin add @capacitor/app --platform ohos\r\n\r\n指定平台卸载\r\nhionic plugin remove @capacitor/app --platform ohos\r\n```\r\n\r\n## 配置\r\n以下配置可用\r\n\r\n| 数据                             | 类型                   | 描述              |\r\n|--------------------------------|----------------------|-----------------|\r\n| **`disableBackButtonHandler`** | <code>boolean</code> | 禁用插件的默认返回按钮处理功能 |\r\n\r\n### 示例\r\n\r\n#### capacitor.config.json\r\n\r\n载于：`capacitor.config.json`\r\n\r\n```json\r\n{\r\n  \"plugins\": {\r\n    \"App\": {\r\n        \"disableBackButtonHandler\": true\r\n    }\r\n  }\r\n}\r\n```\r\n## 核心 API：\r\n\r\n### 接口方法\r\n\r\n| 方法名                                                                | 返回类型                            | 描述                                 |\r\n|--------------------------------------------------------------------|---------------------------------|------------------------------------|\r\n| `exitApp()`                                                        | `Promise<void>`                 | 强制退出应用。                            |\r\n| `getInfo()`                                                        | `Promise<AppInfo>`              | 返回与应用相关的信息。                        |\r\n| `getState()`                                                       | `Promise<AppState>`             | 获取当前应用状态。                          |    \r\n| `getLaunchUrl()`                                                   | `Promise<AppLaunchUrl>`         | 获取启动应用时传入的 URL（如果有）。               |\r\n| `minimizeApp()`                                                    | `Promise<void>`                 | 将应用程序最小化。                          |\r\n| `toggleBackButtonHandler(options: ToggleBackButtonHandlerOptions)` | `Promise<void>`                 | 在运行时启用或禁用插件的返回按钮处理。                |    \r\n| `addListener('appStateChange', ...)`                               | `Promise<PluginListenerHandle>` | 监听应用的状态的变化。                        |\r\n| `addListener('pause', ...)`                                        | `Promise<PluginListenerHandle>` | 监听应用被暂停的事件。                        |\r\n| `addListener('resume', ...)`                                       | `Promise<PluginListenerHandle>` | 监听应用被恢复的事件。                        |\r\n| `addListener('appUrlOpen', ...)`                                   | `Promise<PluginListenerHandle>` | 监听应用的URL打开事件。                      |\r\n| `addListener('appRestoredResult', ...)`                            | `Promise<PluginListenerHandle>` | 不支持。                               |\r\n| `addListener('backButton', ...)`                                   | `Promise<PluginListenerHandle>` | 监听硬件返回按钮事件。一旦监听了此事件，默认的返回按钮行为将被禁用。 |\r\n| `removeAllListeners()`                                             | `Promise<void>`                 | 移除该插件的所有原生监听器。                     |\r\n\r\n### 数据结构`\r\n\r\n#### AppInfo\r\n\r\n| Prop         | Type     | Description                                                  |\r\n| ------------ | -------- | ------------------------------------------------------------ |\r\n| **`name`**   | `string` | 应用的名称。                                             |\r\n| **`id`**     | `string` | 应用的标识符。                                             |\r\n| **`build`**  | `string` | 构建版本。                                             |\r\n| **`version`**| `string` | 应用版本号。                                             |\r\n\r\n#### AppState\r\n\r\n| Prop         | Type     | Description                                                |\r\n| ------------ | -------- | ---------------------------------------------------------- |\r\n| **`isActive`**| `boolean`| 应用是否处于活跃状态。                                             |\r\n\r\n\r\n#### AppLaunchUrl\r\n\r\n| Prop          | Type     | Description                                                  |\r\n| ------------  | -------- | ------------------------------------------------------------ |\r\n| **`url`**     |`string`  | 用于打开应用的 URL。                                 |\r\n\r\n#### ToggleBackButtonHandlerOptions\r\n\r\n| Prop          | Type     | Description                                                  |\r\n| ------------  | -------- | ------------------------------------------------------------ |\r\n| **`enabled`** | `boolean`| 指示是否启用或禁用默认的返回按钮处理。                           |\r\n\r\n#### PluginListenerHandle\r\n\r\n| Prop          | Type                   |\r\n| ------------  | ---------------------- |\r\n| **`remove`** | `() => Promise<void>`   |\r\n\r\n#### URLOpenListenerEvent\r\n\r\n| Prop                          | Type                   | Description                                                  |\r\n| ----------------------------  | ---------------------- | ------------------------------------------------------------ |\r\n| **`url`**                     | `string`               | 应用被打开时使用的 URL。                                       |\r\n\r\n\r\n## 使用示例\r\n\r\n### 基础示例1：获取应用信息\r\n\r\n```\r\nimport { App } from '@capacitor/app';\r\n\r\nconst handleGetInfo = async () => {\r\n  try {\r\n    // 使用Capacitor App插件获取应用信息\r\n    const result = await App.getInfo();\r\n    \r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('get-info', {\r\n        status: 'success',\r\n        data: result\r\n      });\r\n    }\r\n  } catch (error) {\r\n    const errorMsg = error instanceof Error ? error.message : String(error);\r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('get-info', {\r\n        status: 'error',\r\n        message: `获取应用信息失败: ${errorMsg}`\r\n      });\r\n    }\r\n    console.error('获取应用信息失败:', error);\r\n  }\r\n};\r\n\r\n```\r\n\r\n### 基础示例2：获取应用的当前状态\r\n\r\n```\r\nconst handleGetState = async () => {\r\n  try {\r\n    // 使用Capacitor App插件获取应用状态\r\n    const result = await App.getState();\r\n    \r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('get-state', {\r\n        status: 'success',\r\n        data: result\r\n      });\r\n    }\r\n  } catch (error) {\r\n    const errorMsg = error instanceof Error ? error.message : String(error);\r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('get-state', {\r\n        status: 'error',\r\n        message: `获取应用状态失败: ${errorMsg}`\r\n      });\r\n    }\r\n    console.error('获取应用状态失败:', error);\r\n  }\r\n};\r\n\r\n```\r\n\r\n### 基础示例3：获取应用启动时的url\r\n\r\n```\r\nconst handleGetLaunchUrl = async () => {\r\n  try {\r\n    // 使用Capacitor App插件获取应用启动URL\r\n    const result = await App.getLaunchUrl();\r\n    \r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('get-launch-url', {\r\n        status: 'success',\r\n        data: result || { message: '未获取到启动URL' }\r\n      });\r\n    }\r\n  } catch (error) {\r\n    const errorMsg = error instanceof Error ? error.message : String(error);\r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('get-launch-url', {\r\n        status: 'error',\r\n        message: `获取应用启动URL失败: ${errorMsg}`\r\n      });\r\n    }\r\n    console.error('获取应用启动URL失败:', error);\r\n  }\r\n};\r\n\r\n```\r\n\r\n### 基础示例3：使app最小化\r\n\r\n```\r\nconst handleMinimizeApp = async () => {\r\n  try {\r\n    // 使用Capacitor App插件最小化应用\r\n    await App.minimizeApp();\r\n    \r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('minimize-app', {\r\n        status: 'success',\r\n        message: '应用已最小化（仅Android支持）'\r\n      });\r\n    }\r\n  } catch (error) {\r\n    const errorMsg = error instanceof Error ? error.message : String(error);\r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('minimize-app', {\r\n        status: 'error',\r\n        message: `最小化应用失败（仅Android支持）: ${errorMsg}`\r\n      });\r\n    }\r\n    console.error('最小化应用失败:', error);\r\n  }\r\n};\r\n\r\n```\r\n\r\n### 基础示例5：移除App插件的所有事件监听\r\n\r\n```\r\nconst handleRemoveAllListeners = async () => {\r\n  try {\r\n    // 使用Capacitor App插件移除所有监听器\r\n    await App.removeAllListeners();\r\n    \r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('remove-listeners', {\r\n        status: 'success',\r\n        message: '已移除所有应用事件监听器'\r\n      });\r\n    }\r\n  } catch (error) {\r\n    const errorMsg = error instanceof Error ? error.message : String(error);\r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('remove-listeners', {\r\n        status: 'error',\r\n        message: `移除监听器失败: ${errorMsg}`\r\n      });\r\n    }\r\n    console.error('移除监听器失败:', error);\r\n  }\r\n};\r\n\r\n```\r\n\r\n### 基础示例6：事件监听处理函数\r\n\r\n```\r\nconst handleAddPauseListener = async () => {\r\n  try {\r\n    // 添加应用暂停监听器\r\n    const listener = await App.addListener('pause', () => {\r\n      console.log('应用已暂停');\r\n      if (apiButtonSectionRef.value) {\r\n        apiButtonSectionRef.value.updateButtonResult('listener-pause', {\r\n          status: 'success',\r\n          message: '监听到：应用已进入后台'\r\n        });\r\n      }\r\n    });\r\n    \r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('listener-pause', {\r\n        status: 'success',\r\n        message: '已添加应用暂停监听器'\r\n      });\r\n    }\r\n  } catch (error) {\r\n    const errorMsg = error instanceof Error ? error.message : String(error);\r\n    if (apiButtonSectionRef.value) {\r\n      apiButtonSectionRef.value.updateButtonResult('listener-pause', {\r\n        status: 'error',\r\n        message: `添加监听器失败: ${errorMsg}`\r\n      });\r\n    }\r\n    console.error('添加应用暂停监听器失败:', error);\r\n  }\r\n};\r\n\r\n```\r\n\r\n### 该插件获取启动URL需在EntryAbility里注册getLaunchUrl方法\r\n\r\n```\r\n\r\nPluginRegisterHandle(this,want,\"/App/App\",\"getLaunchUrl\",\"\")\r\n\r\n```\r\n\r\n## 参考资料\r\n\r\n1. **Android、ios插件说明**：[www.npmjs.com](https://www.npmjs.com/package/capacitor-app)\r\n\r\n## 许可证\r\n\r\n本项目遵循 [MIT License](./LICENSE)","readmeFilename":"README.md","_rev":"1-965abd57398d02d81d88ac4723d75ea4"}