@capacitor/app

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

简介

@capacitor/app是capacitor生态系统中的核心插件，App的API提供了处理高级应用状态与事件的功能。为跨平台应用开发提供设备差异化适配能力，本文档仅说明在OpenHarmony环境下的使用情况。

API提供了高层级的应用状态与事件如pause、resume等。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/app

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/app

手动引入安装

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

1. 添加插件配置

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

{
  "pkg": "@capacitor/app",
  "classpath": "App"
}

2. 修改 CMake 配置

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

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

// ...

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

3. 复制源码文件

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

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

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

4. 添加 ArkTS 配置

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

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

卸载

# 卸载 app 插件
hionic plugin remove @capacitor/app

约束与限制

兼容性

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

1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

无需额外配置应用权限。

插件配置

支持以下插件配置项，可在capacitor.config.json中配置：

| 配置项 | 类型 | 描述 | |--------------------------|---------|-----------------| | disableBackButtonHandler | boolean | 禁用插件的默认返回按钮处理功能 |

配置示例

{
  "plugins": {
    "App": {
      "disableBackButtonHandler": true
    }
  }
}

使用示例

示例1：获取应用信息

import { App } from '@capacitor/app';

const handleGetInfo = async () => {
  try {
    const result = await App.getInfo();
    console.log('应用信息：', result);
  } catch (error) {
    console.error('获取应用信息失败:', error);
  }
};

示例2：获取应用当前状态

import { App } from '@capacitor/app';

const handleGetState = async () => {
  try {
    const result = await App.getState();
    console.log('应用状态：', result);
  } catch (error) {
    console.error('获取应用状态失败:', error);
  }
};

示例3：获取应用启动URL

import { App } from '@capacitor/app';

const handleGetLaunchUrl = async () => {
  try {
    const result = await App.getLaunchUrl();
    console.log('应用启动URL：', result);
  } catch (error) {
    console.error('获取应用启动URL失败:', error);
  }
};

示例4：应用最小化

import { App } from '@capacitor/app';

const handleMinimizeApp = async () => {
  try {
    await App.minimizeApp();
    console.log('应用已最小化');
  } catch (error) {
    console.error('最小化应用失败:', error);
  }
};

示例5：应用暂停事件监听

import { App } from '@capacitor/app';

const handleAddPauseListener = async () => {
  try {
    const listener = await App.addListener('pause', () => {
      console.log('应用已进入后台暂停');
    });
    console.log('已添加应用暂停监听器');
  } catch (error) {
    console.error('添加应用暂停监听器失败:', error);
  }
};

示例6：移除所有事件监听器

import { App } from '@capacitor/app';

const handleRemoveAllListeners = async () => {
  try {
    await App.removeAllListeners();
    console.log('已移除所有应用事件监听器');
  } catch (error) {
    console.error('移除监听器失败:', error);
  }
};

使用说明

引入@capacitor/app插件的App模块使用，所有API均基于Promise实现，支持异步调用。

1. 退出应用

方法签名

exitApp(): Promise<void>

说明

强制退出当前应用。

2. 获取应用信息

方法签名

getInfo(): Promise<AppInfo>

AppInfo

| 属性名 | 类型 | 说明 | |---------|--------|--------| | name | string | 应用名称 | | id | string | 应用标识符 | | build | string | 应用构建版本 | | version | string | 应用版本号 |

3. 获取应用状态

方法签名

getState(): Promise<AppState>

AppState

| 属性名 | 类型 | 说明 | |----------|---------|--------------| | isActive | boolean | 应用是否处于前台活跃状态 |

4. 获取启动URL

方法签名

getLaunchUrl(): Promise<AppLaunchUrl>

AppLaunchUrl

| 属性名 | 类型 | 说明 | |-----|--------|---------------| | url | string | 启动应用的URL，无则为空 |

5. 最小化应用

方法签名

minimizeApp(): Promise<void>

说明

将当前应用最小化至后台。

6. 切换返回按钮处理

方法签名

toggleBackButtonHandler(options: ToggleBackButtonHandlerOptions): Promise<void>

参数说明

| 参数名 | 类型 | 说明 | |---------|-------------------------------------------------------------------|---------------| | options | ToggleBackButtonHandlerOptions | 必选，返回按钮处理配置参数 |

ToggleBackButtonHandlerOptions

| 属性名 | 类型 | 说明 | |---------|---------|--------------| | enabled | boolean | 是否启用默认返回按钮处理 |

7. 事件监听

方法签名

addListener('appStateChange', ...): Promise<PluginListenerHandle>
addListener('pause', ...): Promise<PluginListenerHandle>
addListener('resume', ...): Promise<PluginListenerHandle>
addListener('appUrlOpen', ...): Promise<PluginListenerHandle>
addListener('backButton', ...): Promise<PluginListenerHandle>
removeAllListeners(): Promise<void>

监听说明

| 监听方法 | 返回类型 | 说明 | |------------------------------------|--------------------------------------------------------------|-------------| | addListener('appStateChange', ...) | Promise<PluginListenerHandle> | 监听应用状态变化 | | addListener('pause', ...) | Promise<PluginListenerHandle> | 监听应用暂停事件 | | addListener('resume', ...) | Promise<PluginListenerHandle> | 监听应用恢复事件 | | addListener('appUrlOpen', ...) | Promise<PluginListenerHandle> | 监听应用URL打开事件 | | addListener('backButton', ...) | Promise<PluginListenerHandle> | 监听硬件返回按钮事件 | | removeAllListeners() | Promise<void> | 移除插件所有原生监听器 |

PluginListenerHandle

| 属性名 | 类型 | |--------|---------------------------| | remove | () => Promise<void> |

URLOpenListenerEvent

| 属性名 | 类型 | 说明 | |-----|--------|----------| | url | string | 打开应用的URL |

特殊说明

该插件获取启动URL需在EntryAbility里注册getLaunchUrl方法，注册代码如下：

PluginRegisterHandle(this,want,"/App/App","getLaunchUrl","")

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml       # 插件配置文件

贡献代码

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

许可证

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